← Back to plugin index

JWT Access Token Format
Description
JWT Access Tokens allow to add metadata to the token. This is useful when clients send Access Tokens to third parties (e.g. resource servers). These third parties can read metadata directly from the token (e.g. validity time), without making any requests (e.g. Token Introspection) to the authorization server.

Security Warning: Using this feature has a major security drawback: Revoked / invalidated tokens might still be considered valid by third parties.

Third parties must validate the JWT according to current security best practices (signature validation, validation of Registered Claims, etc.).

The JWT always includes the following claims:
  • iat - Issue Time
  • nbf - Not Valid Before
  • exp - Expiration Time (claim is not included if token has infinite validity)
  • jti - JWT ID (random value)
  • random - A random value defined through "OAuth 2.0 Token Generator Settings" for the token entropy
  • scope - A JSON array defining the scope of the access token
Type name
JwtAccessTokenFormat
Class
com.airlock.iam.oauth2.application.configuration.token.JwtAccessTokenFormatConfig
May be used by
OIDC Authorization Code / Hybrid Flow OIDC Authorization Code / Hybrid Flow OAuth 2.0 Authorization Code Grant
License-Tags
OAuthServer
Properties
Include Subject Claim (includeSubjectClaim)
Description
If enabled, the username will be included as subject claim (sub).
Attributes
Boolean
Optional
Default value
false
Issuer (issuer)
Description
The issuer claim (iss). If left empty the claim will not be included.
Attributes
String
Optional
Audience (audience)
Description

The audience claim (aud) to include. If left empty the claim will not be included.

If there is one audience, the claim is written as a string, for multiple values as an array.

Attributes
String-List
Optional
Not Valid Before Skew [s] (notValidBeforeSkew)
Description
The skew that will be subtracted from the token creation date to define the not-before claim (nbf).
Attributes
Integer
Optional
Default value
5
Scopes As Space Separated String (scopesAsSpaceSeparatedString)
Description
When enabled, scopes are written as space-separated string claim (as required by RFC 9086). Otherwise, the scope claim will be issued as a string array, even if it only contains a single value.
Attributes
Boolean
Optional
Default value
true
Custom Claims (customClaims)
Description

Custom claims to include in the JWT.

Multiple claims with the same name can be configured if each has a claim condition which ensures that only one of them will be included at runtime.

The following claims are automatically set by Airlock IAM and therefore will be ignored if defined as custom claim.
  • iss
  • aud
  • exp
  • nbf
  • iat
  • jti
  • random
  • scope

Note: When "Persist Claims" is disabled, custom claims are collected when the Access Token is requested by an OAuth 2.0 client and not when the Access Token is issued. Therefore the values of the custom claims may change between issue and request time.

Attributes
Plugin-List
Optional
Assignable plugins
Claim Set Custom Claim Client ID Custom Claim Context Data String Custom Claim Dynamic Boolean Custom Claim Formatted Date And Time Context Data Custom Claim Formatted LocalDate Context Data Custom Claim Session ID Custom Claim Static Boolean Custom Claim Static String Custom Claim String Format Custom Claim String Value Provider Custom Claim User Roles Custom Claim Username Custom Claim
Distributed Claims (distributedClaims)
Description

Distributed Claims to add to the JWT.

These claims allow providing a URL to a 3rd party claims provider in the response where additional claims may be obtained.

Attributes
Plugin-List
Optional
Assignable plugins
Distributed Claim
Signature (signature)
Description
The signature of the Access Token.

Security Warning: The signature must be verified by the consumer of the JWT before the content is interpreted. When using "JWT Access Token No Signature", the consumer must not trust the content of the JWT and therefore not use it as authenticated data.

Security Warning: Verifying the signature and validity of the self-contained JWT is not sufficient to validate the access token. The access token might have been revoked and thus consumers must verify the validity of the access token (e.g. using Token Introspection) before being used for access control.

Attributes
Plugin-Link
Mandatory
Assignable plugins
JWT Access Token No Signature JWT Access Token Private Key Signature
YAML Template (with default values) 

type: JwtAccessTokenFormat
id: JwtAccessTokenFormat-xxxxxx
displayName: 
comment: 
properties:
  audience:
  customClaims:
  distributedClaims:
  includeSubjectClaim: false
  issuer:
  notValidBeforeSkew: 5
  scopesAsSpaceSeparatedString: true
  signature: