Configure JWT Access Tokens

This page explains how to generate and configure JWT Access Tokens.
This page explains how to generate and configure OAuth Access Tokens as JSON Web Tokens (JWTs).
Associated policies:
  • OTK Generate JWT OAuth Token
    – Generates a JWT access token
  • #OTK Generate JWT OAuth Token
    – Allows you to customize the JWT access token. Includes sample code that inserts a preferred user value into the JWT payload if the scope includes OpenID.  
Generate a JWT Access Token
By default, the Authorization server generates UUID formatted OAuth Access tokens. The following instructions show how to enable the Authorization server to issue an OAuth access token in JWT format. Custom configuration is performed within the policy by setting context variables and enabling or disabling assertions.
To enable the Authorization server to generate JWT Access tokens:
  1. In Policy Manager, open the
    #OTK Generate JWT OAuth Token
    By default, the assertions in this policy are disabled.
  2. Enable all assertions in the policy.  You can select multiple assertions, right-click, and select Enable Assertion.
  3. Disable the
    All assertions must evaluate to true
    folder. This folder provides additional configuration for OpenID Connect. See
    Add an Additional Claim to the JWT Payload
    for more details.
  4. Save and Activate
    the policy.
The following example shows the default JWT access token claims:
Context Variable
The date and time the access token expires.
Add Custom Claims to the JWT Payload
Custom claims are used to provide additional information to the protected API for validation or access control. Claims can be added to the JWT as long as the payload maintains a valid JSON format.
If you add claims to the JWT payload, do not include any sensitive information that clients should not see, such as password.
The procedure to add additional claims is as follows:
  • Pass in the value
  • Extract the value
  • Set a value to the payload context variable
Add a Custom Claim
To add a custom claim to the default JWT Payload:
  1. Prepare the #OTK Generate JWT OAuth Token policy as described above. Leave the
    All assertions must evaluate to true
    folder disabled.
  2. Double-click the "Set Context Variable payload..." assertion.
    The payload properties appear with the default claims expressed in JSON format.
  3. Edit the Expression field, adding your custom claims. Click
  4. Save and Activate
    the policy.
Add an OpenID Connect Custom Claim
The disabled folder in the #OTK Generate JWT OAuth Token policy contains assertions that check that OpenID Connect is in scope (openid), and add the preferred_username claim. The preferred_username claim allows access to the userinfo endpoint: openid\connect\v1\userinfo.
Use the example to add any OpenID Connect dependent claim.
To set the preferred_username claim:
  1. Prepare the #OTK Generate JWT OAuth Token policy as described above.
  2. Enable the
    All assertions must evaluate to true
    folder. The preferred_username claim is pre-configured.
  3. Save and Activate
Validate a JWT Access Token
You can validate a JWT Access Token with or without querying the Authorization Server.
Validate With the Authorization Server Database
OTK validates an access token by first checking if it is a UUID or a JWT.
If a JWT is detected, the OTK verifies the signature, then extracts the jti from the JWT to validate it the same way as the UUID token.
Querry Authorization server db
Validate Without the Authorization Server Database
You can customize the validation behavior in the
#OTK Validate JWT OAuth Token
policy not to require the Authorization Server database query. By default, OTK supports validation of the signature only. To extract and validate additional information from the access token, such as iss, exp, aud, and scope, customize the validation.
Validation UUID and JWT
Disable access to Authorization Server database and
Customize validation of JWT claims:
  1. Open the
    #OTK Validate JWT OAuth Token
  2. Enable the
    Evaluate JSON Path Expression
    assertions. Enabling extracts the listed values from the access token. Add logic to how the values should be validated by building your own policy.
  3. Disable the
    Set Context Variable querry_db as String to: true
  4. Save and Activate
    the policy.
If you do not use the Authorization server database for JWT validation, revoking the access token through OAuth Manager has no effect. The JWT access token remains valid until it expires.