Skip to main content

Using OIDC Client Credentials to generate an Access Token another service can use to verify your Application

This article goes through how you can use Client Credentials to identify your Application when using another 3rd party service.

The process has three steps:

  1. The Application retrieves a new Access Token from the ID service. It uses the Client ID and Client Secret credentials to generate a token using the OAuth 2.0 Client Credentials Flow.

  2. The Application makes an API call to the 3rd party service with the Access Token.

  3. The 3rd party service validates the received Token using the ID service.

Request an Access Token using Client Credentials flow​

Make a POST call to the token endpoint, specifying grant type grant_type=client_credentials and providing your Client ID and Client Secret values using client_id and client_secret parameters.

For example using curl:

curl --location \
    --request POST \
    'https://{id-service-url}/openid/token?grant_type=client_credentials&client_id={your-client-id}&client_secret={your-client-secret}'

Successful response will look like:

{
    "access_token": "hinxbB9GcdmNyImNg3GGeJfsi2jBXO2Q",
    "token_type": "Bearer",
    "expires_in": 604799
}

The access_token value is your token. The expires_in value is the number of seconds the token will be valid. You can re-use the token while it is valid.

Optionally, you can configure the ID service to provide Access Tokens which are in the form of a signed JSON Web Token (JWT) which includes the expiration time within itself. These JWT formatted tokens may also enable the 3rd party service to validate the token without a call to the ID service.

Example payload of a JWT formatted access token:

{
    "iss": "https://{id-service-url}",
    "iat": 1680448034,
    "exp": 1681052834,
    "sub": "{your-client-id}",
    "aud": "{your-client-id}"
}

The iss value is the base URL of the ID service, iat value is the epoch time of token issuing, exp is the epoch time of token expiration, sub and aud values are the client ID.

Make an API call to the 3rd party service​

Provide the Access Token with the API request in a manner the API supports. Typically tokens are provided as Bearer Tokens using the Authorization header:

Authorization: Bearer {token}

Some services may accept the token as a query parameter or in other ways.

3rd party validates the token​

After receiving the token the 3rd party service should verify that it is a valid token. For performance reasons it might cache validation information. There are multiple ways to verify a token:

  1. Using the OAuth 2.0 Introspection endpoint of the ID Service

  2. Using the OIDC UserInfo endpoint of the ID Service

  3. If the token is in signed JWT format, by validating the signature, the expiration time, the issuer and the subject locally using the ID Service’s public JWKS keys.

Using the Introspection endpoint​

The 3rd party service needs it’s own OIDC Client credentials to use the Introspection endpoint. This client must be configured to allow it to use introspection on tokens generated by other clients.

Call the /openid/introspect API in the following manner:

curl --location 'https://{id-service-url}/openid/introspect' \
    --header 'Authorization: Basic {base64(client-id:client-secret)}' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'token={token}'

Provide the 3rd party client’s credentials using Basic Authorization header. Provide the token which is being validated as token parameter.

The response looks like:

{
    "active": true,
    "clientId": "{your-client-id}",
    "tokenType": "access_token",
    "exp": 1681052834,
    "sub": "{your-client-id}"
}

The 3rd party service must check the following details:

  • active value is true. The value can be false indicating that the token is expired, unknown, or otherwise invalid.

  • sub value is the Client ID of your application and the service will identify your application by this value. The clientId value is also your application’s client ID, but the sub value indicates that this token identifies the client itself.

  • exp again is the epoch time of expiration.

Using the UserInfo endpoint​

Using this method requires that the ID Service runs version 4.22 or newer.

This includes using the /openid/userinfo API, which is compatible with OIDC UserInfo specifications, to check the sub value again.

TODO example.

Validating locally​

Using this method includes downloading the openid/jwks.json file beforehand and validating the signature and the contents of the JWT-formatted access token locally.

TODO example.