A JSON Web Token (JWT) is commonly used as the physical structure for an OAuth2 token, even though a JWT is not part of the OAuth2 standard. A JWT holds a resource owner’s identity, client identity, issuing and expiration timestamps, and scopes used by a resource server’s authorization process. Other authorization server-defined claims (also known as JSON fields) can be added by a vendor's implementation. A JWT is a Base64-encoded value that contains three sub-structures that describe the data integrity signature algorithm, the user’s identity claims, and the data-integrity signature. Each sub-structure is delimited by a period ('.').

Structure name Description
Header Contains information about the JWT payload's and data integrity signature structures
Payload Contains multiple JWT claims (JSON fields) that describe an authenticated user's ID, issuing and expiration timestamps, scope, client ID, and other values
Signature Contains a binary digital signature of the header and payload structures, that is produced using the signature algorithm type and size contained in the header

A JWT's payload has a small number of common user identity claim fields, but for the most part is wide open to customization of what it contains. Common identity claim fields include:

JWT field name Description Required in JWT token Required in OAuth2 token
iss The URI of the authorization server that issued the JWT token. Yes Yes
sub The user ID. For OAuth2, it is the resource owner’s ID. Yes Yes
aud Can be a string value holding a single recipient identifier (also known as resource server ID) that limits the token’s access to a single resource server. Can also be an array of strings with each array element holding a single recipient identifier, which then allows the token to access multiple resource servers. Yes Yes
client_id This identifies the unique client ID registered by a client application with an authorization server, and is used by a resource server to determine whether the issued JWT can be used to access resource owner data. No Yes
jti A unique identifier for this token that can be used to detect replay attacks and establish client login sessions. optional optional
iat The JWT creation date. Yes Yes
exp The JWT expiration date, after which it can not be used by a resource server. optional optional
nbf The JWT validation date, before which it can not be used by a resource server. optional optional
scope OAuth2 field name that carries a space delimited list of scopes that serve to tell a resource server what data and operations the client is authorized to access. Yes Yes
token_type OAuth2 field name. Indicates the HTTP authorization header scheme that this token was issued in (typically the bearer value). optional optional
<other> Any other authorization server-provided claims. optional optional

A JWT's header can specify one of a set of data-integrity algorithm types based on the JWS standard, which includes HMAC (secret-key) and RSA (public-private key) types.

Header field name Description Required
alg The JWS algorithm name used for generating and verifying the JWT's signature field value. For more information, see the table of JWS signature names. Yes
typ The type of token data format. If not specified, it often defaults to JWT by most vendor implementations. No
kid The alias key ID name that identifies a keystore entry that contains the encryption key value used by the resource server to validate the JWT's signature field value. No

WS signature names:

JWS algorithm name Cryptographic algorithms Key size
HS256 HMAC w. SHA 256
HS384 HMAC w. SHA 384
HS512 HMAC w. SHA 512
RS256 RSA signature w. SHA 256
RS384 RSA signature w. SHA 384
RS512 RSA signature w. SHA 512

JSON Web Encryption (JWE)

Developers have the ability to encrypt the payload in a JSON Web Token (JWT). Encrypted tokens ensure point-to-point security. Existing OAuth2 applications have the option to replace JSON Web Signature (JWS) tokens with JWE tokens. New applications developed and deployed to OAuth2/OpenID Connect environments must use JWE tokens to meet regulatory requirements.
Note: The OpenEdge Advanced Security add-on is required to use JWE tokens.

The client and authorization server selections determine the settings for the JWE properties. To configure encryption of the tokens, configure the following:

  1. Set the related JWE properties. The variables keystorePath, keystorePassword, and keystoreAlias are unique to your system. 
     ## "jwe": JWT Encryption
 jwtToken.keystore.jwe.key.selector=pkcs12EncKeySelector
 jwtToken.keystore.jwe.path=keystorePath
 jwtToken.keystore.jwe.pwd=keystorePassword
 jwtToken.keystore.jwe.alias=keystoreAlias
 jwtToken.keystore.jwe.cache=true
Related properties include:
Table 1. JWE properties
Property Description 
jwtToken.keystore.jwe.key.selector
 Identifies the key selector. Valid values are :
  • noJWEKeySelector
  • pkcs12EncKeySelector
 
jwtToken.keystore.jwe.path
 Path to the local key store with private keys. The default value is [ ]. 
jwtToken.keystore.jwe.pwd
 Encrypted keystore password similar jwtToken.keystore.pwd to access the keystore store defined by jwtToken.keystore.jwe.path. The default value is [ ]. 
jwtToken.keystore.jwe.alias
 List of private key aliases in the JWE keystore. The default value is [ ]. 
jwtToken.keystore.jwe.cache
 Defines whether to cache JWE private keys or extract them from the keystore every time. The default value is true.