search
tutorials

Tokens

JSON Web Tokens (JWT) support the secure exchange of information between clients and servers.


When users sign in to your apps, ForgeRock Identity Cloud Express can generate three types of time-limited JWT tokens:

  • ID token: Includes user data, such as name and email.
  • Access token: Supports retrieving a protected resource.
  • Refresh token: Gets a new access token when a token expires.

When an app requests a token, the token is returned based on two things:

  1. The scopes the app requests.
  2. What is allowed on the server.

The application must ask in the tokens for the scopes it wants returned. The server must be configured to allow those scopes to be returned.

QUICK TIP
You can view the contents of JWT tokens with online JSON token decoders.


Security

Time limits on tokens promote security. For example, if someone intercepts an access token, it can’t be used to impersonate a user after the token expires.

In addition, you may also see an Authorization Code Lifetime. While it’s not a JWT token, it supports security with the Proof Key For Code Exchange (PKCE) standard. For more information, see the following section: Keeping Your Apps Secure with PKCE.

You can configure the time limits through the console as shown below, or through REST calls. See our API documentation.

alt text

ID Token

Express creates ID tokens when users sign in. You can configure the content of ID tokens based on options in the OIDC Scopes panel of your app:

alt text

The claims returned in the ID token are “standard” claims as defined in the OpenID Connect specification.

The default lifetime of an id_token is based on the JWT Token Lifetime, 3600 seconds.

QUICK TIP
ID tokens don’t apply to service (M2M) apps, as they don’t authenticate regular users.

Access Token

An access token is a credential used to access protected resources. You can define the claims associated with an access token in the API Scopes tab of your app:

alt text

NOTE
Available API scopes vary by type of app. For more information, see our section on Management API Scopes.

The default lifetime of an access_token is 3600 seconds (one hour). Once your app requests and receives an access token, the app can use the token to retrieve resources.

Refresh Token

If one hour is not enough time for your users, a refresh token can help. When an access token expires, you can use a refresh token to get a new access token. Use a REST call like the following example:

content_copy COPY

curl --location --request POST "https://openam-{tenantName}.forgeblocks.com/oauth2/access_token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic {BASE_64_ENCODED_STRING}" \
  --data "grant_type=refresh_token&refresh_token={refreshToken}"

In this REST call, you’d use substitute:

  • Name of your tenant
  • Existing refresh token
  • Base64-encoded string based on your client_id:client_secret. You can use the following command to set up the Base64-encoded string:

content_copy COPY

echo -n CLIENT_ID:CLIENT_SECRET | base64

The default lifetime of a refresh_token is 604800 seconds (one week).

Additional Reading

For more information, see the ForgeRock Access Management OpenID Connect 1.0 Guide.

If you want to review specifications for Express tokens, see:

For a conversational perspective of OAuth 2.0 and OIDC, see the following blog posts: