Access and refresh tokens

This guide provides detailed instructions for handling OpenID Connect (OIDC) access and refresh tokens when using Strivacity's Customer Identity and Access Management (CIAM) platform in the Authorization Code Grant flow. This flow enables web applications to authenticate users and securely retrieve access tokens from Strivacity’s identity provider, following OIDC and OAuth 2.0 protocols.

The following documentation corresponds to the process illustrated in the Authorization Code Grant diagram.

Prerequisites

1. OIDC application setup: Ensure that an OIDC-compliant application is configured in Strivacity. Refer to documentation on setting up OAuth2 and OIDC properties to understand how to configure the client.
2. Required permissions: Your application must be registered with the necessary permissions and have access to client credentials (client ID and client secret).
3. Redirect URI: Configure the redirect URI for your application in Strivacity’s settings. This is where Strivacity will send the authorization code after the user consents.

Requesting authorization code

The Authorization Code Grant flow starts by redirecting the user from the web application to Strivacity’s authorization endpoint to obtain an authorization code.

Endpoint:

GET https://{your-domain}/oauth2/auth

Request parameters:

Example request:

GET https://your-domain/oauth2/auth?
    client_id=YOUR_CLIENT_ID&
    scope=openid profile email&
    redirect_uri=https://yourapp.com/callback&
    response_type=code&
    state=xyzABC123&
    nonce=abc123

Receiving the authorization code

Once the user authenticates and consents, Strivacity redirects them back to your application’s redirect_uri with a code.

Response parameters:

• code: The authorization code that your application will exchange for tokens. This code is valid for one-time use and expires shortly.

Exchanging authorization code for tokens

Your application then exchanges the authorization code for an access token, ID token, and optionally a refresh token.

Endpoint:

POST https://{your-domain}/oauth2/token

Request headers:

• Authorization: Use Basic Authentication with base64-encoded client_id:client_secret.

Request body parameters:

Example request:

POST https://your-domain/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
nonce=abc123

Token response:

The response includes the following tokens:

• access_token: Used to access protected resources. Its validity period depends on the resource server configuration.
• id_token: Used to verify the user’s identity. This is short-lived and includes user information.
• refresh_token (optional): Used to obtain new access tokens after expiration without re-authenticating the user.

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "refresh_token": "def502008a8e2...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Storing and using tokens

Secure storage

Store the access_token, id_token, and refresh_token securely on the client side. Ensure that tokens are kept in a secure, encrypted storage mechanism, like an HTTP-only cookie or a secure session storage in browsers.

Token usage

• access_token: Use this token to access protected APIs or resources.
• id_token: Use this token to obtain user claims such as name, email, etc.
• refresh_token: Use this token to obtain a new access_token and id_token without requiring the user to log in again.

Refreshing tokens

When the access_token expires, your application can use the refresh_token to request a new token set without re-authenticating the user.

Endpoint:

POST https://{your-domain}/oauth2/token

Request headers:

• Authorization: Use Basic Authentication with base64-encoded client_id:client_secret.

Request body parameters:

Example request:

POST https://your-domain/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN

Token response:

This request returns a new access_token, and, if applicable, a new id_token and refresh_token.

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "refresh_token": "new_refresh_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Token introspection

Token introspection allows applications to validate access and refresh tokens by querying the introspection endpoint. This can be useful for checking a token’s status, expiration, and associated claims before using it for authorization.

Introspection endpoint

To introspect a token, send a POST request to the following endpoint:

https://{DOMAIN}/oauth2/introspect

Request requirements

Method

POST

Headers

Content-Type: application/x-www-form-urlencoded  
Authorization: Bearer {TOKEN}

The {TOKEN} in the Authorization header must be a token obtained earlier from the token endpoint using the client credentials flow with the read:token_introspection scope.

Request body

token={TOKEN_FOR_INTROSPECTION}

Replace {TOKEN_FOR_INTROSPECTION} with the token you want to validate.

Token expiration and rotation

Strivacity manages token expiration as follows:

• access_token: Typically short-lived and timed to the resource’s security needs.
• id_token: Also short-lived and used primarily for verifying user identity.
• refresh_token: Generally long-lived, but may be configured to expire based on Strivacity's token policies.

Handling expired tokens

• When an access_token expires, use the refresh_token to obtain a new one.
• If the refresh_token is also expired, the user will need to re-authenticate.

Refer to Strivacity's documentation for details on configuring token lifespans and refresh settings: Token Configuration.

Security best practices

1. Use HTTPS: Always use HTTPS to protect token exchanges and prevent interception.
2. Restrict scopes: Request only the scopes necessary for your application.
3. Validate tokens: For ID tokens, validate the signature and claims to confirm authenticity.

Following these steps ensures the secure handling of tokens in compliance with Strivacity’s OIDC implementation.