Description OAuth endpoints

This section explains the OAuth API endpoints within the Token Server. It's divided into the following subsections:

• Authorization endpoint
  • Specification
  • Authorization extensions
    • idp
    • external_idp
    • app_view
    • language
• Token endpoint
  • Specification
  • Custom Token validation (deprecated))
    • Success
    • Error

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

Endpoints: GET /oauth/authorize or GET /oauth/v1/authorize

Specification

See the OAuth specification paragraph 3.1.

Authorization extensions

This endpoint allows additional request parameters. None of them are required.

idp

Specifies the identity provider for the authentication. The value is the identifier of the identity provider in the Token Server.

Example value: idp=idpId

Example use case: an application that supports registration via an identity provider for future customers (prospects) and another identity provider for existing customers. Both identity providers would be configured for this application.

external_idp

Preselects the external identity provider in Onegini CIM for authentication. The value starts with urn:com:onegini:saml:idp: followed by the identifier of the identity provider in Onegini CIM. This feature requires Onegini CIM to be used as an identity provider.

Example value: external_idp=urn:com:onegini:saml:idp:digid

Example use case: an application that authenticates the user with the third party identity provider via Onegini CIM but wants to skip the login screen of the latter.

app_view

Indication for Onegini CIM that the pages are shown within a mobile app. Passing this parameter is only needed when a web client is used for a mobile device (not recommended). The default value for mobile apps is mobile.

Example value: app_view=mobile

Example use cases:

• a login page that should not show the mobile login button when the user visits the login page from within the mobile app.
• Pages shown in the mobile app should not get a navigation menu.

language

Specifies the locale for translations during the authorization flow, except when the Header Identity Provider is used.

Example values: en or en_US

The contents of the language parameter are parsed as Java Locale. Supported formats for the language parameter:

• languageCode, example: en
• languageCode_countryCode, example: en_US
• languageCode_countryCode_variant, example: en_US_east

Example use case: the registration flow for the application should present all screens in the same language.

Token endpoint

Endpoints: POST /oauth/token or POST /oauth/v1/token

Specification

See the OAuth specification paragraph 3.1.

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: validate_access_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".

Success

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"
  }
}

Error

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." 
}