OAuth endpoints

This section explains the OAuth API endpoints within the OneWelcome Identity Platform.

For more details about the OAuth endpoints, see the OAuth specification.

OAuth roles

OAuth defines four roles:

• Resource owner: The user

• Authorization server: The OneWelcome Identity Platform that is responsible for managing tokens.

• Client: A website or app that wants to access the user's resources. Resources can be anything, such as personal data, documents, transactions, signatures, and images.

• Resource server: A server that contains the user resources that the client is accessing. It grants access to the resource when the client provides a valid token. It is also referred to as resource gateway.

OAuth flows

The OneWelcome Identity Platform supports all of the OAuth flows. However, only the authorization code grant and client credentials grant are recommended. The OAuth 2.0 specification describes the these flows:

• Authorization code
• Client credentials
• Implicit
• Resource Owner Password Credentials (ROPC)

When to use each flow

• The authorization code flow returns an access token that gives access to the 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.

• The implicit flow is a simplified OAuth flow previously recommended for public clients where the access token is returned immediately without an extra authorization code exchange step. It is no longer recommended to use the implicit flow due to poor security. Public clients, such as native apps and JavaScript apps, should use the authorization code flow with PKCE.

• The Resource Owner Password Credentials (ROPC) is deprecated and is no longer considered secure for most scenarios. See the topic on resource owner password credentials for more information.

Authorization endpoint

The authorization endpoint is used in the authorization code flow. In this flow, the the OneWelcome Identity Platform sends an access grant to the client. The client can exchange this access grant for an access token by calling the token endpoint.

The authorization code flow in the OneWelcome Identity Platform incorporates the Proof Key for Code Exchange (PKCE) feature to enhance the security of OAuth 2.0 interactions, mitigating the risk of authorization code interception attacks.

While the use of PKCE is optional for confidential clients, it is strongly recommended. However, for public clients, the use of PKCE is mandatory due to their inherent inability to maintain the confidentiality of client secrets. If a confidential client adds the code_challenge and code_challenge_method parameters in the authorization request. The code_verifier parameter is mandatory in the request to the token endpoint for that transaction.

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: onewelcome.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.

Authorization extensions

This endpoint allows additional request parameters. None of them are required. This section describes the parameters that are specific for the the OneWelcome Identity Platform.

idp

The idp parameter specifies the identity provider for the authentication. The value is the identifier of the identity provider in the OneWelcome Identity Platform.

Example value: idp=idpId

Example use case: An application supports registration using one identity provider for prospective customers and another identity provider for existing customers. Both identity providers are configured for this application.

external_idp

The external_idp parameter preselects the external identity provider in the OneWelcome Identity Platform for authentication. The value starts with urn:com:onegini:saml:idp: followed by the identifier of the identity provider in the OneWelcome Identity Platform.

This feature requires using the OneWelcome Identity Platform as an identity provider.

Example value: external_idp=urn%3Acom%3Aonegini%3Asaml%3Aidp%3Adigid

Example use case: An application authenticates the user with a third-party identity provider via the OneWelcome Identity Platform, but wants to skip the OneWelcome Identity Platform login screen.

external_idp_custom_param.*

The external_idp_custom_param parameter can be used to populate a key value map in the OneWelcome Identity Platform extension as part of the SAML authentication request. The key value map can be used for customizing styling or logic in combination with the session API.

This feature requires using OneWelcome Identity Platform 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. It also shows multiple values for a single key: key2 has values val2 and val3.

app_view

The app_view parameter provides an indication to the OneWelcome Identity Platform 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, which is not recommended. The default value for mobile apps is mobile.

Example value: app_view=mobile

Example use cases:

• A login page 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

The language parameter specifies the locale for translations during the authorization flow.

Example values: en or en_US

The contents of the language parameter are parsed as a Java Locale.

The language parameter supports the following formats:

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

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

hook_context_custom_param.*

The hook_context_custom_param parameter can be used to populate a contextCustomParams key value map in the access token web-hook and user details web-hook.

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

This example shows the ability to pass multiple keys: key1 and key2. It also shows multiple values for a single key: key2 has values val2 and val3. The contextCustomParams key value map for the above example value, has the following entries:

Example use-case: Provide context like 'on_behalf_of' and 'on_behalf_of_type' to make integration with an Externalized Authorization product possible.

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 provide more information about the specific error that happened.

Error cause parameters

The OneWelcome Identity Platform uses external identity providers to authenticate users. In some scenarios, authentication can fail, but it can be unclear why it failed.

If the SAML IDP is used and authentication failed due to a malformed request or some user interaction, the generic SAML error is available in the onegini_saml_error. To provide additional information, the onegini_error_cause parameter is sometimes added for a specific error during the authorization flow.

The onegini_saml_error and onegini_error_cause parameters are included in addition to the standard error response as defined by the OAuth specification RFC6749, section 4.1.2.1. These fields are only provided when a SAML IDP is used for authentication by the user.

The value of the onegini_saml_error attribute contains the SAML response status, such as urn:oasis:names:tc:SAML:2.0:status:NoPassive, of the SAML response that was sent by the external IDP to the the OneWelcome Identity Platform. 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

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.

Client authentication

The token endpoint supports two types of client authentication:

• Client Secret
• Private Key JWT

For more information, see authentication methods.

Revoke token endpoint

Use this endpoint to revoke tokens. The OneWelcome Identity Platform immediately makes the tokens invalid, but clients or resource servers do not receive a notification. When the resource server requests token introspection for 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.

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.

OAuth device flow extension

The OAuth device flow is an extension to the standard OAuth 2.0 protocol, specifically designed for devices with no browser or with limited input capability. This flow enables users to authorize such devices in a user-friendly and secure manner. After entering the correct code, the user proceeds through the standard authorization process, including authentication and, if enabled on the client, consent. For detailed specifications, refer to RFC 8628.

The following diagram illustrates the flow:

1. Device authorization request

   • The device client initiates the process by sending a request to the OneWelcome Identity Platform.

2. The OneWelcome Identity Platform responds with the device code, user code, and verification URI

   • The OneWelcome Identity Platform responds to the device client with a device code and a user code.

   • The device code is used by the device client to generate the access token.

   • The device client displays the user code and verification URI as text or a QR code to the user.

   • The verification URI is used by the user to authorize the device.

3. Display user code and verification URI

   • The verification URI points to a webpage hosted by the OneWelcome Identity Platform, and its theme can be customized using the user code template.

4. User enters code on webpage

   • The user uses another device, such as a smartphone, to visit the webpage (as instructed by the device client) and enters the user code or confirms it if the code was provided as a parameter in the URI.

5. Redirect to the authorization flow

   • After successful validation of the user code, the OneWelcome Identity Platform redirects the user to the authorization flow of the configured default IDP or the IDP defined in the request for this web client.

6. Authorize client

   • The user authorizes the client, usually by logging in and giving consent.

   • The consent page can be customized using the consent template.

7. Status page

   • After authorization, the OneWelcome Identity Platform displays a status page to the user.

   • The status page can be customized using the device authorization status template .

8. Token request

   • Concurrently to the user authorization process, the device client repeatedly requests a token from the OneWelcome Identity Platform.

   • Concurrently, the device client repeatedly requests a token from the OneWelcome Identity Platform.

9. Pending authorization

   • If the user hasn't authorized the device client yet, the OneWelcome Identity Platform responds with a message indicating that authorization is pending.

10. Wait five seconds

    • The device client waits five seconds before requesting the token again.

11. Access token

    • If the user has authorized the device client, the OneWelcome Identity Platform responds with an access token.

Device authorization request

The client initiates the authorization process by sending a POST request to the /oauth/device_authorization endpoint. This request includes the client's unique identifier (client_id) and optionally the requested scope and identity provider (idp).

The server responds with a device_code, user_code, and verification_uri. The user must visit this URI in a browser and enter the user code to authorize the device, after which they complete the standard authorization flow.

Each user code is composed of eight characters, exclusively using the following set: BCDFGHJKLMNPQRSTVWXZ.

Request and response example

Request:

POST /oauth/device_authorization HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

client_id=your-client-id&scope=openid&idp=idp123

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "device_code": "OVvqygRcDyw1zLda8Vh78OmVijaDSAPj09ebUIDZu9wP2tqsJgOW9x0ggFqNji4L",
    "user_code": "GMVRZTXC",
    "verification_uri": "https://example.com/oauth/device_authorization/verification",
    "verification_uri_complete": "https://example.com/oauth/device_authorization/verification?user_code=GMVRZTXC"
}

Token generation

The client polls the /oauth/token endpoint for an access token using the device_code and its client_id. It's important to note that clients are required to implement a polling interval of at least five seconds.

The server responds with a pending authorization message or, after successful authorization, the access token and related information.

Token generation examples

Unauthorized client example

Request:

POST /oauth/token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

device_code=OVvqygRcDyw1zLda8Vh78OmVijaDSAPj09ebUIDZu9wP2tqsJgOW9x0ggFqNji4L&client_id=client123&grant_type=urn:ietf:params:oauth:grant-type:device_code

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "authorization_pending",
    "error_description": "The authorization request is still pending"
}

While the 400 status code typically indicates an error, in this context, it is an expected outcome signaling that the client's authorization is still pending.

Authorized client example

Request:

POST /oauth/token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

device_code=OVvqygRcDyw1zLda8Vh78OmVijaDSAPj09ebUIDZu9wP2tqsJgOW9x0ggFqNji4L&client_id=client123&grant_type=urn:ietf:params:oauth:grant-type:device_code

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "bearer",
    "access_token": "D24A8C3742C613F547399C65BC9EC6462CD68F4213F3F085483DF895AFF40EE7",
    "refresh_token": "F41F194EFCDF64DA35221C756E281C40929667C96862709AF2F904F6A67B7C75",
    "expires_in": 900,
    "profile_id": "static"
}

Error handling

In-app device authorization grant

The in-app authorization feature enhances the OAuth 2.0 device authorization grant by allowing authorization within the application. This streamlines the user experience by avoiding redirection to a browser or authorization server and prevents the need for re-authentication, because the user is already logged in within the app.

The API facilitates device authorization directly within the app, using two key parameters:

• user_code: Entered by the user within the application.
• access_token: Belongs to the application making the request and must include the access:device-authorization:approve scope.

Example

Request:

POST /oauth/device_authorization/approve?user_code=ABCD1234 HTTP/1.1
Host: server.example.com
Authorization: Bearer eyJraWQiOiJhYzMxN...

Response:

HTTP/1.1 204 No Content

Error Handling

Device verification URLs

It may be beneficial to consider configuring specific URLs to simplify the implementation of the device client. This approach can streamline the process of integrating the authorization flow within the application. For details on setting up these URLs, refer to the relevant sections describing the use of APIs or the administration console.