Token Configuration

The following topics relate to token creation, configuration, and behavior:
otk43
The following topics relate to token creation, configuration, and behavior:
Introduction to Token Types
ID Token
ID Token is a token issued as a result of user authentication. For more information about ID tokens, see http://openid.net/.
Access Token
Access Token is used by an application to access API on behalf of a user. The two formats of tokens supported in OTK are UUID (default) and JSON Web Token (JWT). For more information about JWT tokens, see JSON Web Token.
Refresh Token
Refresh Token is used to obtain a new access token. It has a longer lifetime than access token. The user does not need to log in every time an access token expires. For customization of the refresh token, see Configure Refresh Token Behavior.
Understanding Access Tokens
In response to a successful client authorization request, the OTK Authorization server generates an access token, which is returned to the client and used to access an API. The access token is consumed by protected resources and is validated for the expiration and status to determine if the request to access to the resource is permitted. The granted scope validation is optional by the configuration in the API.
The OTK supports generation and validation of two types of access token: 
UUID Access Tokens 
UUID is the default access token format, for backward compatibility. Only the issuing Authorization server can validate the UUID access token. The token can be revoked through the OAuth Manager or a client call to the revocation endpoint. The Authorization server generates UUID formatted access tokens. When an incoming request presents a UUID access token, the database is queried and the token is validated. 
Associated policies:
  •  
    OTK Generate OAuth Token
     policy – generates a UUID access token.
  •  
    OTK Token Lifetime Configuration
     policy – contains the default setting for the oauth2_access_token_lifetime context variable. 
  •  
    #OTK Token Lifetime Configuration
     policy – provides customization of the settings in the OTK Token Lifetime Configuration policy.
JWT Access Tokens
The JWT access token is now supported for applications built on CA Mobile API Gateway.
The characteristics of the JWT access token are:
  • The JWT is signed with a private key and can be validated without calling the authorization server
  • Includes more information than a UUID token
  • Claims in JWT payload are visible to clients (JSON format)
  • Resource server and Clients can verify the token using the RS256 signing algorithm
  • JTI in the JWT can be used as a UUID token
For more information on how to enable JWT access token, how the validation is performed, and how to disable calls to authorization server for validation, go to  Configure JWT Access Tokens.
 
Example of a JWT access token:
 
The header of the JWT contains the kid claim value which references a public key that corresponds to the public JWK (JSON Web Key). 
{ "typ":"jwt", "alg": "RSA256", "kid": "key_id_of_used_private_key" }
The payload of the JWT contains the claims including the scopes and the JTI (JWT ID).
{
"iat": 1519860220,
"aud": "63e8c4b0-dbdf-4b99-8551-2f2b0bcd80ab",
"exp": 1519863820,
"jti": "d5ff6a3c-5744-488b-8882-54e5532db5f9",
"token_details": {
"scope": "openid email profile openid_client_registration",
"expires_in": 3600,
"token_type": "Bearer"
}
}
Configure Refresh Token Behavior
You can customize the reuse and expiration behavior of the refresh token.
The default behavior is as follows:
  1. A refresh token is for one-time use only.
  2. When a refresh token is used, a new refresh token is issued with a new expiration value.
To customize the default behavior for all refresh tokens:
  1. In the Policy Manager, open the 
    OTK OVP Configuration
     policy. Locate the policy in OTK/Policy Fragments/configuration/
  2. Copy the following assertions:
    1. Set Context Variable reuse_refresh_token
    2. Set Context Variable reuse_refresh_expiration
  3. Open the 
    #OTK OVP Configuration
     policy. Locate the policy in OTK/Customizations/
  4. Paste the assertions.
  5. Double-click each assertion and set the Expression field to 
    true
     or 
    false
    .
  6. Click 
    OK
    .
  7.  
    Save and Activate
     the policy.
Context Variable
Notes
reuse_refresh_token
Either 
true
 or 
false
.
If false, the refresh token is for one-time use only within the configured expiration time. After the refresh token is used, the token is deleted. A new refresh token is issued.
If true, the same refresh token can be reused multiple times until the configured expiration time.
reuse_refresh_expiration
Either 
true
 or 
false
.
Determines whether a new or the original expiration time is used for the refresh token.
If false, when a refresh token is used, a new expiration time is issued.
If true, the original expiration time is maintained for any newly issued or reused refresh token.
Set the Maximum Token Count
Set the maximum number of tokens that are allowed per resource owner and client. When the maximum number is exceeded, either deny the request and return an error, or cycle the tokens by adding the new token and removing the oldest.
For example,
  1. With the 
    max_oauth_token_count
     set to 5, all clients can access up to five instances of the same app without logging out of the first instance.
  2. When a client attempts to log in to more than five instances, the 
    max_oauth_token_behaviour 
    setting is applied. If set to cycle, the client is logged out of the first instance and logged into a new instance. If set to error, the client is not logged into the new instance and an error is returned. 
To set the maximum number of allowed tokens per resource owner and client:
  1. Open the OTK Storage Configuration policy. Find the policy in OTK/Policy Fragments/configuration.
  2. Copy the following assertions:
    1. Set Context Variable max_oauth_token_count
    2. Set Context Variable max_oauth_token_behaviour
  3. Open the #OTK Storage Configuration policy. Find the policy in OTK/Customizations.
  4. Paste the assertions.
  5. Double-click the assertions and modify the default values.
  6. Click 
    OK
    .
  7.  
    Save and Activate
    .
Context Variable
Notes
max_oauth_token_count
The number of OAuth tokens that are allowed per resource owner and client application.
max_oauth_token_behaviour
Either 
cycle
 or 
error
.
If cycle, the oldest token is removed and the new token is issued.
If error, the new token is not issued. An error is returned.
Implement Client-Specific Configuration
You can configure token behavior for a specific client. 
For example, to customize the reuse refresh token behavior for a specific client, open OAuth Manager, select the client, and add context variables to the custom field.
{ "reuse_refresh_token":"true" "reuse_refresh_expiration":"true" }
Further policy changes are required to capture the custom values. See  Client-Specific Customization.