Skip to content

User Management API

Jump to bottom
Daniel edited this page Sep 1, 2017 · 16 revisions

This page describes the Gatekeeper's User Management module API, along many details such the endpoints, methods and functions available to the Gatekeeper API. It also defines the GK's User Management message exchange with the GK API.

The Gatekeeper's User Management is responsible for the authentication and authorization processes, managing the identity and the access to the Service Platform (SP) and controlling the permissions of the platform users and micro-services, allowing or denying the requested actions.

User Management Architecture

The User Management module's architecture is currently composed by three key different sub-components, which are the Adapter (the API, found in son-gkeeper/son-gtkusr), Keycloak and support MongoDB Database.

                            +-----------------------------------------------+                   
                            |                 User Management               |
                            |    +--------------+         +-----------+     |
+----------------+          |    |   Adapter    +---------+ Keycloak  |     |   
| Gatekeeper API +----------+    | (son-gtkusr) |         +-----------+     | 
+----------------+          |    |      /       |         +-----------+     |
                            |    |     API      +---------+  MongoDB  |     |
                            |    +--------------+         +-----------+     |
                            +-----------------------------------------------+

User Management API Input Message definition

Action HTTP method Path Response Requires token
User Registration POST /api/v1/register/user 201 Created
400: Bad request		 No
Service Registration POST /api/v1/register/service 201 Created
400: Bad request		 No

User Management expected message format:

  • HTTP method: POST

  • Content-type: JSON recommended
    request.content_type = 'application/json'

  • User Registration JSON object:

{"username" => "user",
          "enabled" => true,
          "totp" => false,
          "emailVerified" => false,
          "firstName" => "User",
          "lastName" => "Sample",
          "email" => "user.sample@email.com.br",
          "credentials" => [
              {"type" => "password",
               "value" => "1234"}
          ],
          "requiredActions" => [],
          "federatedIdentities" => [],
          "attributes" => {"userType": ["developer"]},
          "realmRoles" => [],
          "clientRoles" => {},
          "groups" => []}
  • Service Registration JSON object:
{"clientId": "myclient",
      "surrogateAuthRequired": false,
      "enabled": true,
      "clientAuthenticatorType": "client-secret",
      "secret": "1234",
      "redirectUris": [
          "/auth/myclient"
      ],
      "webOrigins": [],
      "notBefore": 0,
      "bearerOnly": false,
      "consentRequired": false,
      "standardFlowEnabled": true,
      "implicitFlowEnabled": false,
      "directAccessGrantsEnabled": true,
      "serviceAccountsEnabled": true,
      "publicClient": false,
      "frontchannelLogout": false,
      "protocol": "openid-connect",
      "fullScopeAllowed": false}

User registration template definition:

  • username: The user account name. REQUIRED
  • enabled: States if the user account is enabled. true by default. REQUIRED
  • totp: Time Based QR code authentication. false by default
  • emailVerified: States if user's email address is verified . false by default. REQUIRED
  • firstName: User's first name. REQUIRED
  • lastName: User's last name. REQUIRED
  • email: User's email address. REQUIRED
  • credentials:
  • {type: Type of credential. Set to password for users. REQUIRED
  • value}: The user's password. REQUIRED
  • requiredActions: User's actions to enable the account. Set it [] by default. REQUIRED
  • federatedIdentities: Links electronic user's identity. Set it [] by default.
  • attributes: Custom dict to set user's properties. Each dict's key value is a list.

This is used by son-gtkusr to assign User Type roles:

  • {"userType": ["Type of user"]}: User type declares the user role to be assigned (developer, customer..). REQUIRED
  • realmRoles: User roles that enables permissions for realm scope. Set it [] by default.
  • clientRoles: User roles that enables permissions for micro-service scope. Set it {} by default.
  • groups: User aggregation groups. Set it [] by default.

Micro-service Client registration template definition:

  • clientId: Micro-service name. REQUIRED
  • surrogateAuthRequired: Set false by default.
  • enabled: Set to true to enable the service account. REQUIRED
  • clientAuthenticatorType: Type of credentials. Set to client-secret. REQUIRED
  • secret: Service account password value. REQUIRED
  • redirectUris: Sets a redirect URI. It is not used but is a required field.
  • ["/auth/myclient"]: Pattern of redirect URI. REQUIRED
  • webOrigins: Root of the micro-service. Set to [] by default.
  • notBefore: Internal parameter: Set to 0 by default.
  • bearerOnly: Set to false. REQUIRED
  • consentRequired: Set to false. REQUIRED
  • standardFlowEnabled: Enables standard token flow. Set to true. REQUIRED
  • implicitFlowEnabled: false. REQUIRED
  • directAccessGrantsEnabled: Enables service account auth flow. Set to true. REQUIRED
  • serviceAccountsEnabled: Enables a service account for the micro-service. Set to true. REQUIRED
  • publicClient: Disables auth. Set to false. REQUIRED
  • frontchannelLogout: Allows external logout. Set to false.
  • protocol: States the auth standard protocol. Set to "openid-connect". REQUIRED
  • fullScopeAllowed: Enables admin role. Set to false. REQUIRED

User 'sampleuser' registration example: 

POST
url = URI("http://<address>:<port>/api/v1/register/user")
request.content_type = 'application/json'
request.body = {"username" => "sampleuser",
          "enabled" => true,
          "totp" => false,
          "emailVerified" => false,
          "firstName" => "User",
          "lastName" => "Sample",
          "email" => "user.sample@email.com.br",
          "credentials" => [
              {"type" => "password",
               "value" => "1234"}
          ],
          "requiredActions" => [],
          "federatedIdentities" => [],
          "attributes" => {"userType": ["developer"]},
          "realmRoles" => [],
          "clientRoles" => {},
          "groups" => ["developers"]}
  • Response: 
{
  "username": "sampleuser",
  "userId": "83c4118a-f25e-4963-b6fe-b5dedfed6503"
}

Micro-service 'son-catalogue' registration example: 

POST
url = URI("http://<address>:<port>/api/v1/register/service")
request.content_type = 'application/json'
request.body = {"clientId"=> "son-catalogue",
    "surrogateAuthRequired"=> false,
    "enabled"=> true,
    "clientAuthenticatorType"=> "client-secret",
    "secret"=> "1234",
    "redirectUris": [
        "/auth/son-catalogue"
    ],
    "webOrigins"=> [],
    "notBefore"=> 0,
    "bearerOnly"=> false,
    "consentRequired"=> false,
    "standardFlowEnabled"=> true,
    "implicitFlowEnabled"=> false,
    "directAccessGrantsEnabled"=> true,
    "serviceAccountsEnabled"=> true,
    "publicClient"=> false,
    "frontchannelLogout"=> false,
    "protocol"=> "openid-connect",
    "fullScopeAllowed"=> false
}
Action HTTP method Path Response Requires token
User Log-in POST /api/v1/login/user 200: OK
401: Unauthorized		 No
Service Log-in POST /api/v1/login/service 200: OK
401: Unauthorized		 No

User Management expected message format for User Login:

  • HTTP method: POST

  • Authorization header must include a string following the next pattern:
    encoded_username_password = base64.strict_encode64("username"+":"+"password")
    request.env["HTTP_AUTHORIZATION"] = "Basic encoded_username_password"

  • User Management parses authorization header this way: 

pass = request.env["HTTP_AUTHORIZATION"].split(' ').last
plain_pass  = Base64.decode64(pass)
username = plain_pass.split(':').first # params[:username]
password = plain_pass.split(':').last # params[:password]

Examples: 

POST
url = URI("http://<address>:<port>/api/v1/login/user")
request["authorization"] = 'Basic YWRtaW46YWRtaW4="

User Management expected message format for Service Login:

  • HTTP method: POST

  • Authorization header must include a string following the next pattern:
    encoded_clientName_secret = base64.strict_encode64("clientName"+":"+"secret")
    request.env["HTTP_AUTHORIZATION"] = "Basic encoded_clientName_secret"

  • User Management parses authorization header this way: 

pass = request.env["HTTP_AUTHORIZATION"].split(' ').last
plain_pass  = Base64.decode64(pass)
clientName = plain_pass.split(':').first # params[:clientName]
secret = plain_pass.split(':').last # params[:secret]

Examples: 

POST
url = URI("http://<address>:<port>/api/v1/login/service")
request["authorization"] = 'Basic YWRtaW46YWRtaW4="
Action HTTP method Path Response Requires token
Log-out POST /api/v1/logout 204: No Content
401: Unauthorized		 Yes

User Management expected message format for both User or Service to logout:

  • HTTP method: POST

  • Authorization header must include a string following the next pattern:
    request.env["HTTP_AUTHORIZATION"] = "Bearer <access_token>

  • User Management parses authorization header this way:
    user_token = request.env["HTTP_AUTHORIZATION"].split(' ').last

Examples: 

POST
url = URI("http://<address>:<port>/api/v1/logout")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
Action HTTP method Path Response Requires token
Token Authorization POST /api/v1/authorize 200: OK
401: Unauthorized		 Yes

User Management expected message format:

  • HTTP method: POST

  • Authorization header must include a string following the next pattern:
    request.env["HTTP_AUTHORIZATION"] = "Bearer <access_token>

  • Content-type: JSON or QUERY are supported
    request.content_type = 'application/json'

The Gatekeeper API needs to provide two critical parameters:

  • provide the UrlPath the user is trying to access (/path/.../last). In this case, is important to note that the User Management takes care of the path and last parts. This is useful to differentiate actions that use the same HTTP method, e.g.: GET /packages is considered a read action, while GET /packages/download is considered download action.

  • provide the HTTP method from the user request (GET, POST, PUT, DELETE, ...)
    The Gatekeeper can provide this information to the User management in the request Body, using JSON or form formats.
    This is critical because the User Management needs to know which is the resource the user is trying to access through the URL path, and which is the action the user is trying to trigger through the HTTP method. The user management will evaluate if the user has the proper role to access the resource and read/write/execute the resource.

  • Body: JSON object 

{"path": "/pathTotheResource/optionalAction",
 "method": "httpMethod"}
  • Query: url?path=/pathTotheResource/optionalAction?&method=httpMethod

Examples using application/json:

  • User requests to GET a descriptor from SP Catalogues 
POST
url = URI("http://<address>:<port>/api/v1/authorize")
request["authorization"] = 'Bearer eyJhbGciOiJSX0NpUUhmTm9nIn0...'
request.content_type = 'application/json'
request.body = {"path": "/services", "method": "GET"}
  • User requests to POST a package to SP Catalogues 
POST
url = URI("http://<address>:<port>/api/v1/authorize")
request["authorization"] = 'Bearer eyJhbGciOiJSX0NpUUhmTm9nIn0...
request.content_type = 'application/json
request.body = {"path": "/packages", "method": "POST"}

DEPRECATED
Examples using x-www-form-urlencoded:

  • User requests to GET a descriptor from SP Catalogues 
POST
url = URI("http://<address>:<port>/api/v1/authorize")
request["authorization"] = 'Bearer eyJhbGciOiJSX0NpUUhmTm9nIn0...'
request.content_type = x-www-form-urlencoded
request.body = "path/services&method=GET"

DEPRECATED

  • User requests to POST a package to SP Catalogues 
POST
url = URI("http://<address>:<port>/api/v1/authorize")
request["authorization"] = 'Bearer eyJhbGciOiJSX0NpUUhmTm9nIn0...'
request.content_type = x-www-form-urlencoded'
request.body = "path/packages&method=POST"
Action HTTP method Path Response Requires token
Userinfo (OIDC endpoint) POST /api/v1/userinfo 200: OK
401: Unauthorized		 Yes

The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. These Claims are normally represented by a JSON object that contains a collection of name and value pairs for the Claims.

User Management expected message format for Userinfo endpoint:

  • HTTP method: POST

  • Authorization header must include a string following the next pattern:
    request.env["HTTP_AUTHORIZATION"] = "Bearer <user_access_token>

  • User Management parses authorization header this way:
    user_token = request.env["HTTP_AUTHORIZATION"].split(' ').last

Examples: 

POST
url = URI("http://<address>:<port>/api/v1/userinfo")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'

  • Response:
    {"sub":"8031545e-d4da-4086-8cb2-a417f3460de2","name":"myName myLastName","preferred_username":"tester01","given_name":"myName","family_name":"myLastName","email":"myname.company@email.com"}

  • Where:

  • sub: Subject-Identifier for the End-User at the Issuer. Internal to the User management
  • name: End-User's full name in displayable form including all name parts
  • preferred_username: Shorthand name by which the End-User is referred to at the Service Platform
  • given_name: Given name(s) or first name(s) of the End-User
  • family_name: Surname(s) or last name(s) of the End-User
  • email: End-User's preferred e-mail address
  • Gatekeeper API suggestion:
    In order to get the username from any user's Access Token, GK API should parse preferred_username from this request response.
Action HTTP method Path Response Requires token
UM Public Key GET /api/v1/public-key 200: OK
400: Bad request		 No

This endpoint exposes the SONATA 'realm' public key from the Keycloak. The public key is required to decode the JWT (Access Token) and obtain its header, payload, and signature. This is the process required to verify the status of the token (expiration time).

User Management expected message format for Public key endpoint:

  • HTTP method: GET

  • User Management response:
    It returns a text/html;charset=utf-8 that contains string with the public key. The public key is not provided in the encapsulated message format (Encapsulation Boundaries), so the client requesting it will have to add -----BEGIN PUBLIC KEY----- at the beginning and -----END PUBLIC KEY----- at the end of the public key.

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/public-key")
  • Response: 
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjgbyvnNVuTpc5xrCzE9PS59DMLvVWpINJ/T3SCHNASzAHDpKm/43YRCFFYDM2nGIQuUbyGlWsHrdhiZwpi1e8tdUHsW2LNBVJ7/RqEj/2oNiVh2BMEp2HHNtpobKg5kKGvciG9vMcvbdwLcG2i+hRL4B1p5C8W3npqTwE/WBpmaKdh8ae2qiUC/2LSn52qxq1LyWKEfLE0Om8QwYi1o54pybWKDi3SSj1Ksl2FrkGZ9FU0ZkOuLMMyXDe62npaycSCeUkgYR2aPcA5pEFufcXUDieg1RJwrMZog+w02cNlEl/QLZqULIMM0R8HlI5UWHEPk5pKXP2bwO8nIck0MU5QIDAQAB
  • Client Encapsulated message format Public key: 
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjgbyvnNVuTpc5xrCzE9PS59DMLvVWpINJ/T3SCHNASzAHDpKm/43YRCFFYDM2nGIQuUbyGlWsHrdhiZwpi1e8tdUHsW2LNBVJ7/RqEj/2oNiVh2BMEp2HHNtpobKg5kKGvciG9vMcvbdwLcG2i+hRL4B1p5C8W3npqTwE/WBpmaKdh8ae2qiUC/2LSn52qxq1LyWKEfLE0Om8QwYi1o54pybWKDi3SSj1Ksl2FrkGZ9FU0ZkOuLMMyXDe62npaycSCeUkgYR2aPcA5pEFufcXUDieg1RJwrMZog+w02cNlEl/QLZqULIMM0R8HlI5UWHEPk5pKXP2bwO8nIck0MU5QIDAQAB
-----END PUBLIC KEY-----
Action HTTP method Path Response Requires token
Translate username to User ID GET /api/v1/userid
/api/v1/userid?username=		 200: OK
400: Bad request		 Yes

User Management expected message format for user ID endpoint:

  • HTTP method: GET

  • Authentication header includes the Access Token

  • Optional: username can be queried in the URL

  • User Management response:
    It returns the user ID for the given Access Token or queried username

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/userid")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response:
    {'userId': '773746-24fsf2-24dsr2-424dd'} 
GET
url = URI("http://<address>:<port>/api/v1/userid?username=user01")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response:
    {'userId': '773746-24fsf2-24dsr2-424dd'}
Action HTTP method Path Response Requires token
Check if token's status is active GET /api/v1/token-status 200: OK
401: Unauthorized		 Yes
Check if token has expired GET /api/v1/token-check 200: OK
401: Unauthorized		 Yes

The first Action checks if the provided access token is still valid for the User Management and its status is active. It does not consider expiration time.
The second Action checks if the provided access token is alive or expired, considering its lifespan. However, it does not check if the token is valid for the User Management.
User Management expected message format for token status or expiry check:

  • HTTP method: GET

  • Required header: Authorization set with the token to be evaluated

  • User Management response:
    It returns an HTTP code which states the result of the check.

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/token-status")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response:
    Valid token: 200, OK
    Expired token: 401, Unauthorized

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/token-check")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response:
    Valid token: 200, OK
    Expired token: 401, Unauthorized
Action HTTP method Path Response Requires token
List registered users GET /api/v1/users 200: OK
400: Bad request		 No
List registered client services GET /api/v1/services 200: OK
400: Bad request		 No
List available roles GET /api/v1/roles 200: OK
400: Bad request		 No

User Management expected message format for list users, client services and roles:

  • HTTP method: GET

  • Optional: username and clientId can be queried in the URL

  • User Management response:
    It returns a list of users, client services or roles, with their stored information

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/users")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
  {
    "id": "5e1ef7d8-b5cd-4835-8bcb-68b182140fa9",
    ....
  },
  { "id": "5e1ef7d8-b5cd-4835-845f-61b18a230da1",
    ....
  },
  ....
]

GET
url = URI("http://<address>:<port>/api/v1/users?username=user01")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
  {
    "id": "5e1ef7d8-b5cd-4835-8bcb-68b182140fa9",
    "createdTimestamp": 1492094414797,
    "username": "user01",
    "enabled": true,
    "totp": false,
    "emailVerified": false,
    "firstName": "User",
    "lastName": "Sample",
    "email": "user.sample@email.com",
    "attributes": {
      "userType": [
        "developer"
      ]
    },
    "disableableCredentialTypes": [
      "password"
    ],
    "requiredActions": []
  }
]

GET
url = URI("http://<address>:<port>/api/v1/services")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
{
    "id": "7653c60b-7324-4a2e-9a68-56b158f81c21",
    "clientId": "adapter",
    ....,
},
....
]

GET
url = URI("http://<address>:<port>/api/v1/services?name=adapter")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
{
    "id": "7653c60b-7324-4a2e-9a68-56b158f81c21",
    "clientId": "adapter",
    "surrogateAuthRequired": false,
    "enabled": true,
    "clientAuthenticatorType": "client-secret",
    "redirectUris": [
      "http://localhost:8081/adapter"
    ],
    "webOrigins": [
      "http://localhost:8081"
    ],
....
}

GET
url = URI("http://<address>:<port>/api/v1/roles")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
  {
    "id": "01f4eb68-be6e-4497-a35c-f885af23c17d",
    "name": "customer",
    "description": "${role_read-repositories},${role_write-repositories},${role_execute-catalogue}",
    "scopeParamRequired": false,
    "composite": false,
    "clientRole": false,
    "containerId": "5605a737-93ff-402d-a0fe-064f9b0f05dd"
  },
  ....
]
Action HTTP method Path Response Requires token
List current user sessions GET /api/v1/sessions/users 200: OK
400: Bad request		 No
List user's sessions GET /api/v1/sessions/users/:username 200: OK
400: Bad request		 No
List current client service sessions GET /api/v1/sessions/services 200: OK
400: Bad request		 No

User Management expected message format for list sessions of users, user's sessions and sessions of client services:

  • HTTP method: GET

  • Optional: username can be added as parameter

  • User Management response:
    It returns a list of current users sessions, or client services sessions, or a user's current sessions

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/sessions/users")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
  {
    "id": "18073909-1cd0-405a-988d-e7073717e2c3",
    "username": "service-account-adapter",
    "userId": "743676a5-cdd7-4e33-9c16-3bba5f3ff9cc",
    "ipAddress": "127.0.0.1",
    "start": 1492597076000,
    "lastAccess": 1492597076000,
    "clients": {
      "78aab20b-78a2-49c3-a6c7-9115053d421f": "adapter"
    }
  },
  {
    "id": "3ae6e7f7-d144-4881-a354-45a16a78723c",
    "username": "user04",
    "userId": "c2e01595-81c8-4c9c-8b19-387cbb08ae62",
    "ipAddress": "172.20.0.17",
    "start": 1492597606000,
    "lastAccess": 1492597606000,
    "clients": {
      "78aab20b-78a2-49c3-a6c7-9115053d421f": "adapter"
    }
  }
]

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/sessions/users/user04")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
  {
    "id": "3ae6e7f7-d144-4881-a354-45a16a78723c",
    "username": "user04",
    "userId": "c2e01595-81c8-4c9c-8b19-387cbb08ae62",
    "ipAddress": "172.20.0.17",
    "start": 1492597606000,
    "lastAccess": 1492597606000,
    "clients": {
      "78aab20b-78a2-49c3-a6c7-9115053d421f": "adapter"
    }
  }
]

Examples: 

GET
url = URI("http://<address>:<port>/api/v1/sessions/services")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
  {
    "clientId": "adapter",
    "active": "4",
    "id": "78aab20b-78a2-49c3-a6c7-9115053d421f"
  },
  {
    "clientId": "son-catalogue",
    "active": "1",
    "id": "9325ee76-105a-434a-9d32-d6b6c03bc672"
  }
]
Action HTTP method Path Response Requires token
Update user's Public key and/or certificate PUT /api/v1/signatures/:username 200: OK
400: Bad request		 Yes

User Management expected message format in order to add or update user's Public key and certificate (optional). This is only allowed to 'developer' users:

  • HTTP method: PUT
  • Authentication header includes the Access Token
  • Parameter: username
  • Body: JSON object that includes public_key field (required) and certificate field (optional)
{"public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArVFiBHBiLPFRGrMobAxcK98SJRKKXJOkA66NL0UEgR7g8hOjVySchYUvtGAU5wi2ZCjmPGDT0hrJd1WEBplv0kT7YrIgdRGXGH73OJFjH8c7iX+XBwk0sH1K+KMUbszSbWFCKAlyHhYa8vz95RyzmzoMJZW6TeadlhRLuVw52RECaK9eIJu311oFA8os3z8J65olLexT0vF+B9Oqtn1gVJUfC0w984PXwMoGzSOVCbb5jD0/blAXonMS8PU+JFSGF4trTwRcmjw349NDEifUQamdHE8pynuxSpAuMN2WAPAlJpjnw/fHUxQFgRNGki6vHmegnQ6qmcbuorVW3oXkMwIDAQAB", "certificate": "optional"}
  • User Management response: 200, OK

Examples:

  • Before: 
[
  {
    "id": "b8bef49d-87ff-4fcd-a64d-15e0d34fcdcb",
    "createdTimestamp": 1493038492034,
    "username": "user04",
    "enabled": true,
    "totp": false,
    "emailVerified": false,
    "firstName": "firstName",
    "lastName": "lastName",
    "email": "mail1234@mail.com",
    "attributes": {
      "phone_number": [
        "123123123"
      ],
      "userType": [
        "developer"
      ],
      "certificate": null,
      "public_key": null
    },
    "disableableCredentialTypes": [
      "password"
    ],
    "requiredActions": []
  }
]
  • After: 
[
  {
    "id": "b8bef49d-87ff-4fcd-a64d-15e0d34fcdcb",
    "createdTimestamp": 1493038492034,
    "username": "user04",
    "enabled": true,
    "totp": false,
    "emailVerified": false,
    "firstName": "firstName",
    "lastName": "lastName",
    "email": "mail1234@mail.com",
    "attributes": {
      "phone_number": [
        "123123123"
      ],
      "userType": [
        "developer"
      ],
      "certificate": null,
      "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArVFiBHBiLPFRGrMobAxcK98SJRKKXJOkA66NL0UEgR7g8hOjVySchYUvtGAU5wi2ZCjmPGDT0hrJd1WEBplv0kT7YrIgdRGXGH73OJFjH8c7iX+XBwk0sH1K+KMUbszSbWFCKAlyHhYa8vz95RyzmzoMJZW6TeadlhRLuVw52RECaK9eIJu311oFA8os3z8J65olLexT0vF+B9Oqtn1gVJUfC0w984PXwMoGzSOVCbb5jD0/blAXonMS8PU+JFSGF4trTwRcmjw349NDEifUQamdHE8pynuxSpAuMN2WAPAlJpjnw/fHUxQFgRNGki6vHmegnQ6qmcbuorVW3oXkMwIDAQAB"
    },
    "disableableCredentialTypes": [
      "password"
    ],
    "requiredActions": []
  }
]
Action HTTP method Path Response Requires token
Get user data / List registered users GET /api/v1/users
/api/v1/users?username="username"
/api/v1/users?id="id"
 200: OK
400: Bad request		 No
Update user data PUT /api/v1/users?username="username"
/api/v1/users?id="id"
 204: No content
400: Bad request		 No
Delete user DELETE /api/v1/users?username="username"
/api/v1/users?id="id"
 204: No content
400: Bad request		 No

User Management expected message format for get/list, update and delete users:

  • HTTP method: GET

  • Optional: GET method optionally can query for username and id in the URL

  • User Management GET response:
    It returns a list of users or user data with their/its stored information

Example: 

GET
url = URI("http://<address>:<port>/api/v1/users?username=user01")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
  {
    "id": "5e1ef7d8-b5cd-4835-8bcb-68b182140fa9",
    "createdTimestamp": 1492094414797,
    "username": "user01",
    "enabled": true,
    "totp": false,
    "emailVerified": false,
    "firstName": "User",
    "lastName": "Sample",
    "email": "user.sample@email.com",
    "attributes": {
      "userType": [
        "developer"
      ]
    },
    "disableableCredentialTypes": [
      "password"
    ],
    "requiredActions": []
  }
]
  • HTTP method: PUT
  • Required: PUT method requires either username or id query in the URL
  • Body must contain a JSON object similar to the user registration form, however username, id, email are forbidden fields
  • Supported queries in the URL: URL: http://<address>:<port>/api/v1/users?username=username or URL: http://<address>:<port>/api/v1/users?id=user_uuid Content-Type: application/json

Important: When updating user attributes, request's Body must include all user's attributes data fields, the whole hash (except public_key). If a field is missing it will be removed from the user attributes data. This means that if mobile number update is requested, body will be like: Body: {"attributes":{"phone_number":[92848374232],"userType":["developer"]}}

The suggested workflow should be to first GET the user data from http://<address>:5600/api/v1/users?username=username, parse the attributes and update (PUT) them including the changes.

It is also important to mention that username field can't be modified nor updated.

  • User Management PUT response:
    It returns a 204 code response

Example: 

PUT
url = URI("http://<address>:<port>/api/v1/users?username=user01")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
body = {
"credentials":[{"type":"password","value":"1234"}],
"firstName": "MYFIRSTNAME",
"lastName": "lastName",
"attributes":{"phone_number":[123123123],"userType":["developer"], "public_key": "asniu42783GgGFGg3827receg", "deck_num": "192"}
}

  • Response:
    204 No Content

  • HTTP method: DELETE

  • Required: DELETE method requires either username or id query in the URL

  • User Management DELETE response:
    It returns a 204 code response

Example: 

DELETE
url = URI("http://<address>:<port>/api/v1/users?username=user01")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response:
    204 No Content
Action HTTP method Path Response Requires token
Get service data / List registered service clients GET /api/v1/services
/api/v1/services?name="name"
/api/v1/services?id="id"
 200: OK
400: Bad request		 No
Delete service client DELETE /api/v1/services?name="name"
/api/v1/services?id="id"
 204: No content
400: Bad request		 No

User Management expected message format for get/list and delete services:

  • HTTP method: GET
  • Optional: GET method optionally can query for name and id in the URL
  • User Management GET response:
    It returns a list of service' clients or client data with their/its stored information

Example: 

GET
url = URI("http://<address>:<port>/api/v1/services?name=son-catalogue")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: 
[
{
    "id": "e3688103-2132-47d6-859b-2742ee9e4662",
    "clientId": "son-catalogue",
    "surrogateAuthRequired": false,
    "enabled": true,
    "clientAuthenticatorType": "client-secret",
...
]

  • HTTP method: DELETE

  • Required: DELETE method requires either name or id query in the URL

  • User Management DELETE response:
    It returns a 204 code response

Example: 

DELETE
url = URI("http://<address>:<port>/api/v1/services?name=son-catalogue")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response:
    204 No Content
Action HTTP method Path Response Requires token
Assign role to a user POST /api/v1/roles/assign 204: No content
400: Bad request		 No
Unassign role to a user POST /api/v1/roles/unassign 204: No content
400: Bad request		 No

User Management expected message format to assign/unassign role to a user:

  • HTTP method: POST
  • Body must contain a JSON object with next fields properly set: username, role
  • User Management POST response:
    It returns 204 code
Action HTTP method Path Response Requires token
Assign group to a user POST /api/v1/groups/assign 204: No content
400: Bad request		 No
Unassign group to a user POST /api/v1/groups/unassign 204: No content
400: Bad request		 No

User Management expected message format to assign/unassign group to a user:

  • HTTP method: POST
  • Body must contain a JSON object with next fields properly set: username, group
  • User Management POST response:
    It returns 204 code
Action HTTP method Path Response Requires token
Create new group POST /api/v1/groups 201 Created
400: Bad request		 No
Update existing group PUT /api/v1/groups?name= 204: No content
400: Bad request		 No
Delete existing group DELETE /api/v1/groups?name= 204: No content
400: Bad request		 No

User Management expected message format to create a new group:

  • HTTP method: POST
  • User Management POST response: It returns a 201 code

Example: 

POST
url = URI("http://<address>:<port>/api/v1/groups")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
request.body = {
    "name" => "guests",
    "scopeParamRequired" => false,
    "composite" => false,
    "clientRole" => false
}
  • Response: It returns a 201 code response

User Management expected message format to update existing groups:

  • HTTP method: PUT
  • Query: Group Id or name
  • User Management PUT response: It returns a 204 code

Example: 

PUT
url = URI("http://<address>:<port>/api/v1/groups?name=guests")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
request.body = {
    "name" => "visitors",
    "scopeParamRequired" => false,
    "composite" => false,
    "clientRole" => false
}
  • Response: It returns a 204 code response

User Management expected message format to delete existing groups:

  • HTTP method: DELETE
  • User Management DELETE response: It returns a 204 code

Example: 

DELETE
url = URI("http://<address>:<port>/api/v1/groups?name=guests")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: It returns a 204 code response
Action HTTP method Path Response Requires token
Create new role POST /api/v1/roles 201 Created
400: Bad request		 No
Update existing role PUT /api/v1/roles?name= 204: No content
400: Bad request		 No
Delete existing role DELETE /api/v1/roles?name= 204: No content
400: Bad request		 No

User Management expected message format to create a new role:

  • HTTP method: POST
  • User Management POST response: It returns a 201 code

Example: 

POST
url = URI("http://<address>:<port>/api/v1/roles")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
request.body = {
    "name" => "guest",
    "description" => "Role",
}
  • Response: It returns a 201 code response

User Management expected message format to update existing roles:

  • HTTP method: PUT
  • Query: Role Id or name
  • User Management PUT response: It returns a 204 code

Example: 

PUT
url = URI("http://<address>:<port>/api/v1/roles?name=guest")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
request.body = {
    "name" => "visitor",
    "description" => "Role",
}
  • Response: It returns a 204 code response

User Management expected message format to delete existing roles:

  • HTTP method: DELETE
  • User Management DELETE response: It returns a 204 code

Example: 

DELETE
url = URI("http://<address>:<port>/api/v1/roles?name=guest")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: It returns a 204 code response
Action HTTP method Path Response Requires token
List resource permissions GET /api/v1/resources 201 Created
400: Bad request		 No
Create resource permission POST /api/v1/resources 201 Created
400: Bad request		 No
Update existing resource permission PUT /api/v1/resources?name= 204: No content
400: Bad request		 No
Delete existing resource permission DELETE /api/v1/resources?name= 204: No content
400: Bad request		 No

User Management expected message format to list available resource permissions:

  • HTTP method: GET
  • User Management GET response: It returns a 201 code

Example: 

GET
url = URI("http://<address>:<port>/api/v1/resources")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: It returns a 201 code response
[
    {
        "_id": {
            "$oid": "59a7feeb730c6e0001000000"
        },
        "clientId": "gtkapi",
        "created_at": "2017-08-31T12:19:55.440+00:00",
        "description": "This is a global rule set to provide authorization permissions to the gtkapi endpoints",
        "policies": [
            {
                "name": "developer",
                "description": "SONATA Realm role authorized to request the resource",
                "type": "role",
                "logic": "positive",
                "scopes": null
            },
...

User Management expected message format to add a new resource permission:

  • HTTP method: POST
  • User Management POST response: It returns a 201 code

Example: 

POST
url = URI("http://<address>:<port>/api/v1/resources")
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
request.body =     {
        "clientId": "catalogue",
        "description": "This is a global rule set to provide authorization permissions to the service endpoints",
        "policies": [
            {
                "name": "developer",
                "description": "SONATA Realm role authorized to request the resource",
                "type": "role",
                "logic": "positive",
                "scopes": null
            },
            {
                "name": "customer",
                "description": "SONATA Realm role authorized to request the resource",
                "type": "role",
                "logic": "positive",
                "scopes": null
            },
            {
                "name": "admin",
                "description": "SONATA Realm role authorized to request the resource",
                "type": "role",
                "logic": "positive",
                "scopes": null
            },
            {
                "name": "son-slm",
                "description": "SONATA Realm role authorized to request the resource",
                "type": "role",
                "logic": "positive",
                "scopes": null
            },
            {
                "name": "owner",
                "description": "SONATA Realm user owner of the resource",
                "type": "user",
                "logic": "positive",
                "scopes": null
            }
        ],
        "resource_owner_name": "catalogue_api",
        "resources": [
            {
                "resource_name": "services",
                "description": null,
                "type": "resource",
                "URI": "services",
                "owner": "catalogue",
                "associated_permissions": [
                    {
                        "name": "read",
                        "description": "Read a catalogue service resource",
                        "apply_policy": [
                            "developer",
                            "son-slm"
                        ],
                        "action": "GET"
                    },
                    {
                        "name": "write",
                        "description": "Store a catalogue service resource",
                        "apply_policy": [
                            "developer",
                            "owner"
                        ],
                        "action": "POST"
                    },
                    {
                        "name": "update",
                        "description": "Update a catalogue service resource",
                        "apply_policy": [
                            "developer",
                            "owner"
                        ],
                        "action": "PUT"
                    },
                    {
                        "name": "delete",
                        "description": "Remove a catalogue service resource",
                        "apply_policy": [
                            "developer",
                            "owner"
                        ],
                        "action": "DELETE"
                    }
                ]
            }
  • Response: It returns a 201 code response

User Management expected message format to update existing resource permissions:

  • HTTP method: PUT
  • User Management PUT response: It returns a 204 code

Example: 

PUT 
url = URI("http://<address>:<port/api/v1/resources?name=catalogue") 
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
request.body =  { 
        "clientId": "catalogue",
        "description": "This is a rule set for the service endpoints",
        "policies": [
            {
...
  • Response: It returns a 204 code response

User Management expected message format to existing resource permissions:

  • HTTP method: DELETE
  • User Management POST response: It returns a 204 code

Example: 

DELETE
url = URI("http://<address>:<port/api/v1/resources?name=catalogue") 
request["authorization"] = 'Bearer eyJhbGciOiJSkxX0NpUUhmTm9nIn0...'
  • Response: It returns a 204 code response
Clone this wiki locally