how tos

Manage JSON Web Tokens

Using JWTs enables clients and servers to securely exchange information. Express lets lets you:

About JWTs

A JWT (pronounced “jot”) contains a claim or other verifiable data. Express generates JWTs as proof of authentication or authorization. When a user signs in to your app, Express can generate three types of time-limited JWTs:

ID token. Contains authenticated user data such as name and email.

Access token. Allows retrieving data from a protected resource.

Refresh token. Authorizes a new access token when a token expires.

The server returns a token only if two conditions are met:

  1. The app requests the scopes it wants returned in the token.
  2. The server is configured to allow those scopes to be returned.

Setting Token Time Limits

Setting time limits on tokens enhances security. A bad actor might intercept an access token. But after the token expires, the bad actor can’t use the token to impersonate the authorized user.

When available, you’ll see an Authorization Code Lifetime setting. While it’s not a JWT setting, it strengthens security by using the Proof Key For Code Exchange (PKCE) standard. For more information, see: Keeping Your Apps Secure with PKCE.

To use the Express Console: Go to Applications > App Name > General Settings.

alt text

To use Express REST calls: See the Express API documentation.

Configuring Scopes for Returning an ID Token

Express creates ID tokens when users sign in. You can configure the scopes, or permissions, used to determine the contents of the ID tokens.

To use the Express console: Navigate to Applications > App Name > OIDS Scopes:

alt text

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

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

M2M apps don’t use ID tokens because M2M apps don’t authenticate human users.

Configuring an Access Token

An access token is a credential used to access protected resources. You can define the claims associated with an access token.

To use the Express console: Navigate to Applications > Your App Name > OICD Scopes.

alt text

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

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

Configuring a Refresh Token

If one hour is not enough time for your users, configure a refresh token. When an access token expires, you can use a refresh token to get a new access token.

To use the REST API, follow this example:

content_copy COPY

curl --location --request POST "https://openam-{tenantName}" \
  --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, 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).

More Information

See the ForgeRock Access Management OpenID Connect 1.0 Guide.

For Express tokens specifications, see:

For blog posts about OAuth 2.0 and OIDC, see :