Management API
This section describes the Management API of the Authorization Server. Once you have setup the Authorization Server service instance, you will need to provision scopes and register clients before access tokens can be requested. The Authorization Server will provide access tokens for registered (known) clients only.
The Management API's purpose is to help with the process of provisioning scopes and client registration via a set of HTTP based APIs and managing them.
Provisioning Scopes
A scope is what is known as an arbitrary string based on the user's context. Examples such as normal_scope, admin_scope determines the user's access level and the scopes that are associated with that level. Scope values cannot have space characters and it is recommended that any space be substituted with the underscore character.
Scopes can be added and removed using the /scope endpoint URI after the Management API base URI, as is set in the custom.conf file while setting up the Authorization Server.
Example - Scope endpoint URI
http(s)://hostname:port/management-api-base-uri/scope
The following table lists all HTTP APIs available for provisioning scopes and the expected success return value.
| URI | HTTP Method | Input Parameters | Input format | Input Example | Return Value | Return Format | Return Example |
|---|---|---|---|---|---|---|---|
| /scope | GET | None | N/A | N/A | Space delimited list of all scopes provisioned | JSON | {"scope":"normal_scope admin_scope"} |
| /scope | POST | Space delimited list of scopes to be provisioned | JSON | {"scope":"normal_scope admin_scope"} | Space delimited list of scopes provisioned succesfully | JSON | {"scope":"normal_scope admin_scope"} |
| /scope | PATCH | Space delimited list of scopes to be removed | JSON | {"scope":"admin_scope"} | Space delimited list of scopes removed successfully | JSON | {"scope":"admin_scope"} |
Client Registration
A client is an application that requires the use of the REST API hosted on the REST Server agent.
When the OAuth2 authorization is enabled in the REST Server agent, the client must obtain an access token such as generated by Authorization Server and then provide the access token via the Authorization HTTP header for REST API requests. The client must be registered first before obtaining the access token from the Authorization Server. Any unregistered client will not be accepted.
Clients can be registered and removed using the /clients endpoint URI after the Management API base URI.
Example - Client endpoint URI
http(s)://hostname:port/management-api-base-uri/clients
The client name MUST be unique.
The following table lists all HTTP APIs available for provisioning scopes and the expected success return value:
| URI | HTTP Method | Input Parameters | Input format | Input Example | Return Value | Return Format | Return Example |
|---|---|---|---|---|---|---|---|
| /clients | GET | None | N/A | N/A | List of all clients registered | JSON | [{"client_name":"Some App","client_id":"YCuIPYVa0GryebpzniAZU5VGqye_dxBGdcXI","client_secret":"Ofy1-QfO3yrFYdk3dj1pmM30GKVre9Q6bMk6V7YIRmqGHwaijQ","scope":"normal_scope admin_scope"}] |
| /clients/<client_name> | GET | None | N/A | N/A | Client details for the <client_name> specified | JSON | {"client_name":"Some App","client_id":"YCuIPYVa0GryebpzniAZU5VGqye_dxBGdcXI","client_secret":"Ofy1-QfO3yrFYdk3dj1pmM30GKVre9Q6bMk6V7YIRmqGHwaijQ","scope":"normal_scope admin_scope"} |
| /clients | POST | client_name and scope of the client to be registered | JSON | {"client_name":"Some App","scope":"normal_scope admin_scope"} | Clients details for the <client_name> registered | JSON | {"client_name":"Some App","client_id":"YCuIPYVa0GryebpzniAZU5VGqye_dxBGdcXI","client_secret":"Ofy1-QfO3yrFYdk3dj1pmM30GKVre9Q6bMk6V7YIRmqGHwaijQ","scope":"normal_scope admin_scope"} |
| /clients/<client_name> | DELETE | N/A | N/A | N/A | Status for the removal of the client with <client_name> | JSON | {"status":"success"} |
| /clients/<client_name> | PUT | scope of client to be registered or modified if client exists | JSON | {"scope":"normal_scope admin_scope"} | Client details for the <client_name> that is registered or modified | JSON | {"client_name":"Some App","client_id":"YCuIPYVa0GryebpzniAZU5VGqye_dxBGdcXI","client_secret":"Ofy1-QfO3yrFYdk3dj1pmM30GKVre9Q6bMk6V7YIRmqGHwaijQ","scope":"normal_scope admin_scope"} |
| /clients/<client_name> | PATCH | N/A | N/A | N/A | Client details for the <client_name> that is specified and with new client_id and client_secret generated | JSON | {"client_name":"Some App","client_id":"YCuIPYVa0GryebpzniAZU5VGqye_dxBGdcXI","client_secret":"Ofy1-QfO3yrFYdk3dj1pmM30GKVre9Q6bMk6V7YIRmqGHwaijQ","scope":"normal_scope admin_scope"} |
HTTP Status Code
The Management API in the Authorization Server will return certain codes to the client to indicate a successful or unsuccessful request. The following table will show the HTTP Status Code for successful HTTP API calls as well as all unsuccessful HTTP API calls.
| HTTP Status Code | Return Value | Return Format | Return Example |
|---|---|---|---|
| 200 (Successful) | This indicates that the HTTP API call is successful. The response will often include a body that is dependent on which method was used in the request. | JSON | Highly dependent on the HTTP method type. |
| 400 (Bad Request) | Status of the HTTP API call and description of the status. Error is due to incorrect usage of the HTTP API by the user. | JSON | {"status":"error","description":"invalid form data"} |
| 401 (Unauthorized) | Incorrect username and/or password provided for the HTTP API call when HTTP Basic Authentication is enabled for the Management API. The response HTTP header parameter "WWW-Authenticate" will be set to "Basic" in this case. | N/A | N/A |
| 500 (Internal Server Error) | Status of the HTTP API call and description of the status. Error is due to the Authorization Server unable to handle the request internally. | JSON | {"status":"error","description":"database error"} |
Access Token Endpoint
The access token endpoint is used by the client to request for access tokens. All clients have to be registered by using the Management API before the access token can be requested as all unregistered clients will not have their token request accepted. See the Client Registration section above for more information.
Every registered client will have a client_id and client_secret assigned by the Authorization Server and the access token can only be requested using this set of client credentials.
The access token can be requested using the Access Token URI that was configured using the access-token-uri parameter.
Example - Access Token URI
if the access-token-uri parameter value was configured to /token. The access token endpoint would be:
http(s)://hostname:port/token
The client can request for the access token at the access token endpoint by following the steps below:
- Setting the "client_id" and "client_secret" as username and password respectively in the HTTP Basic Authentication header.
- Setting the "grant_type" parameter using the "application/x-www-form-urlencoded" format in the HTTP request entity-body. The value MUST be set to "client_credentials".
- In the case that the client doesn't support HTTP Basic Authentication, the "client_id" and "client_secret" can be set using the the "application/x-www-form-urlencoded" format in the HTTP request entity-body as well using the "client_id" and "client_secret" parameter names respectively.
Example - Using HTTP Basic Authentication header
HTTP access token request by specifying client_id and client_secret in the HTTP Basic Authentication header
POST /token HTTP/1.1 Host: oauth2.server.com Authorization: Basic WUN1SVBZVmEwR3J5ZWJwem5pQVpVNVZHcXllX2R4QkdkY1hJOk9meTEtUWZPM3lyRllkazNkajFwbU0zMEdLVnJlOVE2Yk1rNlY3WUlSbXFHSHdhaWpR Content-Type: application/x-www-form-urlencoded grant_type=client_credentials
Example - Using application/x-www-form-urlencoded in the HTTP request entity-body
HTTP access token request by specifying client_id and client_secret in the application/x-www-form-urlencoded format in the HTTP request entity-body
POST /token HTTP/1.1 Host: oauth2.server.com Content-Type: application/x-www-form-urlencoded grant_type=client_credentials client_id=YCuIPYVa0GryebpzniAZU5VGqye_dxBGdcXI client_secret=Ofy1-QfO3yrFYdk3dj1pmM30GKVre9Q6bMk6V7YIRmqGHwaijQ
The access token response will contain the following parameters to the entity-body of the HTTP response with a 200 (OK) status code:
| entity-body | Description |
|---|---|
access_token | The access token issued by the Authorization Server |
token_type | Value will always be Bearer |
expires_in | The lifetime (in seconds) of the access token |
Example - HTTP access token response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 572
{
"access_token":"eyJraWQiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJSaWVsbGUgQXBwIiwic2NvcGUiOiJzY29wZTEgc2NvcGUzIiwiaXNzIjoiZGlnaXRhbHJvdXRlIiwiZXhwIjoxNTIwMjY4MTk2LCJpYXQiOjE1MjAyNjYzOTZ9.fInkdt_Fe4QQ-gAgI7CszIMkru61aec6OYxQsotkydh5xVczJsaJ-QkAfPtJ0tTVkAYeJZYmVEi_aApY8HNJMrZgvS07S8PnBOwsPUAPAHTDVU3u3c9zqhVzV5233rcoMdiUK61Qa7MoreE_4BwxjYMbek08DscwPWRZ-3V1r49PZ5i2MI5kfj4LdNTcuJZZ62-oILupdvVCiGTt9poGZqZdktEkgKANXPhxp1oQ-w1LD9uhmsRWP_6Cd4R1ky1HJxEocbDtx0uf068De4v1rxH2myaz7faZBexeQEUHjiDLxomnBnQENTfxTEVIj7WLqenAzPIkAOC_KvVv5EaJJg",
"token_type":"Bearer",
"expires_in":1800
}
In the event of an error when requesting for an access token, The Authorization Server will respond with an HTTP 400 (Bad Request) status code, unless it is specified otherwise. The response will include the following parameters:
| entity-body | Description |
|---|---|
| error | A single ASCII [USASCII] error code from the following:
|
| error_description | Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. |
Example - HTTP access token error response
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 64
{"error":"invalid_client","error_description":"Unknown client"}