OAuth endpoints

This section explains the OAuth API endpoints within the Onegini Token Server.

For details about the OAuth endpoints we refer to the OAuth specification.

Introduction

Roles

OAuth defines four roles:

• Resource owner: the user
• Authorization server: the Onegini Token Server. It's responsible for managing tokens.
• Client: a website or app that wants to access the user's resources. Resources can be anything: personal data, documents, transactions, signatures, images, etc.
• Resource server: a server that contains the user's resources that are being accessed by the client. It grants access to the resource when the client provides a valid token. It is also referred to as Resource Gateway.

Flows

The OAuth 2.0 specification describes the following flows to obtain tokens:

• Authorization code
• Client credentials
• Implicit
• Resource owner password credentials (ROPC)

The Onegini Token Server supports all of these flows. However, only the authorization code grant and client credentials grant are recommended.

When to use which flow:

• The authorization code flow returns an access token that gives access to resources of a specific user. For example, when the user wants to check their insurance policy, the resource server needs to know on behalf of which user the client wants to access the policy. User interaction is often required during this flow.
• The client credentials flow returns an access token that gives access to resources for a specific client. For example, when the user requests the general terms and conditions document, the resource server needs to know which client requests access to this document. The resource server does not need to know on behalf of which user the client requests access. Obtaining the access token can be automated and does not require user interaction.

Authorization endpoint

The authorization endpoint is used in the authorization code flow and the implicit flow. In the authorization code flow, the Onegini Token Server sends an access grant to the client. The client can exchange this access grant for an access token by calling the token endpoint. In the implicit flow, the Onegini Token Server sends the access token with the response.

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

Example request for the authorization code flow:

GET /oauth/v1/authorize?response_type=code&client_id=exampleApp&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect HTTP/1.1
Host: onegini.example.com

Example success response for the authorization code flow:

HTTP/1.1 302 Found
Location: https://client.example.com/redirect?code=myAccessGrant12345&state=xyz

Specification

See the OAuth specification section 3.1 and the specification for Proof Key for Code Exchange by OAuth Public Clients (PKCE).

Authorization extensions

This endpoint allows additional request parameters. None of them are required. This section describes the parameters that are specific for the Onegini Token Server.

idp

Specifies the identity provider for the authentication. The value is the identifier of the identity provider in the Onegini 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%3Acom%3Aonegini%3Asaml%3Aidp%3Adigid

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.

external_idp_custom_param.*

This parameter can be used to populate a key value map in the Onegini Extension as part of the SAML Authentication Request. The key value map can be used in the Onegini CIM product for customizing styling or logic in combination with the Session API. This feature requires Onegini CIM to be used as an identity provider .

Example value: external_idp_custom_param.key1=val1&external_idp_custom_param.key2=val2&external_idp_custom_param.key2=val3

This example shows the ability to pass multiple keys: key1 and key2, and multiple values for a single key: key2 has values val2 and val3.

Example use cases are described in the extension custom parameters topic guide.

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.

Authorization error extensions

Apart from the standard error parameters provided by the OAuth specification, in some error scenarios additional parameters are returned. These parameters are meant to give more information about the specific error that happened.

Error cause parameters

The Onegini Token Server uses external Identity Providers to authenticate users. In some scenarios authentication can fail, but it can be a bit unclear why it failed.

In case the SAML IdP is used and authentication failed due to a malformed request or due to some user interaction, the generic SAML error will be available in onegini_saml_error. To provide additional information the onegini_error_cause parameter is sometimes added in case of a specific error during the authorization flow.

The onegini_saml_error and onegini_error_cause parameters are included on top of the standard error response as defined by the OAuth specification RFC6749, section 4.1.2.1. Currently, these fields are only provided when a SAML IdP is used for authentication by the end user. The value of the onegini_saml_error attribute contains the SAML response status ( e.g. urn:oasis:names:tc:SAML:2.0:status:NoPassive) of the SAML response that was sent by the external IdP to the Onegini Token Server. For a list of SAML status codes see the SAML 2.0 core specification, section 3.2.2.2 The value of the onegini_error_cause can contain more detailed information about the error cause like custom error codes, which are especially useful in processes like on-boarding. Values can be, for example, no_existing_customer, invalid_birthdate, fraud_detected or whatever is defined as custom error in the user journey.

Token endpoint

The token endpoint returns an access token for the following flows:

• authorization code
• client credentials
• resource owner password credentials

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

Example request for the authorization code flow:

POST /oauth/v1/token HTTP/1.1
Host: server.example.com
Authorization: Basic ZXhhbXBsZUFwcDp0aGVTZWNyZXRUaGF0QmVsb25nc1RvVGhlRXhhbXBsZUFwcA==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=myAccessGrant12345&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect

Example success response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "token_type": "bearer",
  "access_token": "myAccessToken12345",
  "refresh_token": "myRefreshToken12345",
  "expires_in": 900,
  "profile_id": "static"
}

Specification

See the OAuth specification section 3.2 and the specification for Proof Key for Code Exchange by OAuth Public Clients (PKCE).

Client Authentication

The token endpoint supports two types of client authentication:

• Client Secret
• Private Key JWT

For more information, see Authentication Methods documentation.

Revoke token endpoint

Use this endpoint to revoke tokens. The Onegini Token Server will immediately make them invalid, but clients or resource servers will not receive a notification. When the resource server requests token introspection or token validation with the token, the response does indicate that this token is no longer valid.

Endpoint: POST /oauth/revoke or POST /oauth/v1/revoke

Example request:

POST /oauth/v1/revoke HTTP/1.1
Host: server.example.com
Authorization: Basic ZXhhbXBsZUFwcDp0aGVTZWNyZXRUaGF0QmVsb25nc1RvVGhlRXhhbXBsZUFwcA==
Content-Type: application/x-www-form-urlencoded

token=myAccessToken12345&token_type_hint=access_token

Example success response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

Specification

See the OAuth specification for token revocation and the specification for Proof Key for Code Exchange by OAuth Public Clients (PKCE).

Note for refreshing and revoking the access token: When a public client uses the authorization code grant type with PKCE, the request parameter client_id is mandatory. For confidential clients both the client id and the client secret are sent as basic authentication credentials via the authorization header.

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 Onegini 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 Onegini Token Server in order to fetch the metadata related to an access token.

The Onegini 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 Onegini 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.

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

Attribute	Description
app_identifier	Identifier of the application in the Onegini Token Server oauth config.
app_platform	Platform of the application in the Onegini Token Server oauth config.
app_version	Version of the application in the Onegini 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

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.
403	Unable to determine identity provider	The idp is disabled, non-existent, or not configured for this client.
500	internal_server_error	An unexpected internal server error has occurred.