Description OAuth endpoints
This section explains the OAuth API endpoints within the Token Server. It's divided into the following subsections:
For details about the OAUth endpoints we refer to the OAuth specification. In this manual we only list the URI's of the endpoints.
Authorization endpoint
See the OAuth specification paragraph 3.1.
Endpoint: GET
or POST /oauth/authorize
Token endpoint
See the OAuth specification paragraph 3.1.
Endpoint: POST /oauth/token
Extensions on OAuth endpoints
Custom Token validation (deprecated)
Custom token validation has been deprecated in favor of token introspection. Existing applications are encouraged to upgrade.
In paragraph 1.1 of the OAuth specification it is stated that the interaction between the authorization server and resource server is beyond the scope of the OAuth specification. Since the Token Server is acting as the authorization server another entity will be acting as the resource server or API gateway as we also call it. Hence, this interaction is very important since the resource server needs to be able to interact with the Token Server in order to fetch the metadata related to an access token.
The Token Server extends the standard OAuth token endpoint with an additional grant type for this:
Endpoint POST /oauth/token
This endpoint requires HTTP Basic Authentication. The required credentials are the client id and client secret configured in the Admin console of the Token Server.
Note: Please look in the OAuth config section on how to configure an OAuth web client. For the token validation a special 'grant type' is introduced. In order to allow a client to perform token validation you must enable the grant type "Validate access token".
Parameter | Example value | Description |
---|---|---|
grant_type | urn:innovation-district.com:oauth2:grant_type:validate_bearer |
The custom grant type used for validating a bearer access token. The bearer access token is the default access token |
token | ABCDEF1234567890ABCDEF1234567890 |
The access token that was passed to the resource server in the resource request. |
Example response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"token_type": "bearer",
"client_id": "QNuBGQdV0CYb3Z6BKXlB9TvjHQNf46qF",
"expires_in": 300,
"scope": "read write",
"usage_limit": 10,
"reference_id": "myUserId",
"app_identifier": "oneginiApp",
"app_version": "1.0",
"app_platform": "ios",
"user_attributes":{
"amount":"5",
"email":"[email protected]",
"first_name":"John",
"currency":"EUR"
}
}
Attribute | Description |
---|---|
app_identifier | Identifier of the application in the Token Server oauth config. |
app_platform | Platform of the application in the Token Server oauth config. |
app_version | Version of the application in the Token Server oauth config. |
client_id | Client ID of the oauth client owning to the access token. |
expires_in | Number of seconds the access token is still valid. |
reference_id | The user identifier of the user that granted this access token to the oauth client. |
scope | Scopes the access token was requested for, when multiple scopes the String is space delimited. |
token_type | For token validation this field will always have the type bearer as a bearer token validation has been performed. |
usage_count | When a usage limit is set, this field indicates the number of times the access token has already been used. |
usage_limit | When a usage limit is set, this field indicates the max number of times the access token can be used. |
user_attributes | List of details about the user. Depending on the configured user detail mappings in the IdP this array can differ in size. When the header authenticator is used this list includes white listed request parameter values. |
Error response
A number of error responses can occur. Below the format of an error response is depicted. The table below that shows a list of the possible error responses with the possible cause.
The error responses are in the format of standard OAuth error responses of the Token endpoint.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request",
"error_description": "The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed."
}
Http status code | Error | Possible cause |
---|---|---|
400 | invalid_grant | The provided access token was invalid or expired. |
400 | invalid_request | The request is missing a required parameter. |
401 | invalid_client | The client credentials were invalid. |
400 | unauthorized_client | The client is not allowed to use this grant type. This means that the grant type Validate access token is not configured for this client. |
400 | unsupported_grant_type | The grant type that was used in the request is not recognised as a valid grant type. |
500 | internal_server_error | An unexpected internal server error has occurred. |