PingAuthorize Server Documentation Index
Configuration Reference Home

JWT Access Token Validator

Note: this component stores cluster-wide configuration data and is mirrored across all servers in the topology within the the same cluster.

Note: changes to cluster-wide configuration objects are immediately and automatically mirrored across all servers within the same cluster, so offline changes are not supported.

JWT Access Token Validator validates JWT access tokens using local token inspection.

Parent Component
Relations from This Component
Properties
dsconfig Usage

Parent Component

The JWT Access Token Validator component inherits from the External Access Token Validator

Relations from This Component

The following components have a direct aggregation relation from JWT Access Token Validators:

Properties

The properties supported by this managed object are as follows:


General Configuration Basic Properties: Advanced Properties:
↓ description ↓ subject-claim-name
↓ enabled ↓ client-id-claim-name
↓ evaluation-order-index ↓ scope-claim-name
↓ authorization-server
↓ clock-skew-grace-period
Signing and Encryption Basic Properties: Advanced Properties:
↓ allowed-signing-algorithm  None
↓ signing-certificate
↓ jwks-endpoint-path
↓ encryption-key-pair
↓ allowed-key-encryption-algorithm
↓ allowed-content-encryption-algorithm

Basic Properties

description

Property Group
General Configuration
Description
A description for this Access Token Validator
Default Value
None
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

enabled

Property Group
General Configuration
Description
Indicates whether this Access Token Validator is enabled for use in PingAuthorize Server.
Default Value
None
Allowed Values
true
false
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

evaluation-order-index

Property Group
General Configuration
Description
When multiple JWT Access Token Validators are defined for a single PingAuthorize Server, this property determines the evaluation order for determining the correct validator class for an access token received by the PingAuthorize Server. Values of this property must be unique among all JWT Access Token Validators defined within PingAuthorize Server but not necessarily contiguous. JWT Access Token Validators with a smaller value will be evaluated first to determine if they are able to validate the access token.
Default Value
1000
Allowed Values
An integer value. Lower limit is 0.
Multi-Valued
No
Required
Yes
Admin Action Required
None. Modification requires no further action

authorization-server

Property Group
General Configuration
Description
Specifies the external server that will be used to aid in validating access tokens. In most cases this will be the Authorization Server that minted the token.
Default Value
Not specifying an authorization server implies that no external communication is required to validate access tokens.
Allowed Values
The DN of any HTTP External Server.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

clock-skew-grace-period

Property Group
General Configuration
Description
Specifies the amount of clock skew that is tolerated by the JWT Access Token Validator when evaluating whether a token is within its valid time interval. The duration specified by this parameter will be subtracted from the token's not-before (nbf) time and added to the token's expiration (exp) time, if present, to allow for any time difference between the local server's clock and the token issuer's clock.
Default Value
5 s
Allowed Values
A duration. Lower limit is 0 seconds.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

allowed-signing-algorithm

Property Group
Signing and Encryption
Description
Specifies an allow list of JWT signing algorithms that will be accepted by the JWT Access Token Validator. The JWT Access Token Validator will only accept tokens that are signed using signing algorithms in this list. By default, this list contains the set of all RSA signing algorithms. In general, however, this list of allowed signing algorithms should be strictly limited to those known to be used by the authorization server.
Default Value
RS256
RS384
RS512
Allowed Values
RS256 - RSA using SHA-256

RS384 - RSA using SHA-384

RS512 - RSA using SHA-512

ES256 - ECDSA using P-256 and SHA-256

ES384 - ECDSA using P-384 and SHA-384

ES512 - ECDSA using P-521 and SHA-512
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action

signing-certificate

Property Group
Signing and Encryption
Description
Specifies the locally stored certificates that may be used to validate the signature of an incoming JWT access token. If this property is specified, the JWT Access Token Validator will not use a JWKS endpoint to retrieve public keys.
Default Value
One of signing-certificate and jwks-endpoint-path must be specified, but not both.
Allowed Values
The DN of any Trusted Certificate.
Multi-Valued
Yes
Required
No
Admin Action Required
None. Modification requires no further action

jwks-endpoint-path

Property Group
Signing and Encryption
Description
The relative path to JWKS endpoint from which to retrieve one or more public signing keys that may be used to validate the signature of an incoming JWT access token. This path is relative to the base_url property defined for the validator's external authorization server. If jwks-endpoint-path is specified, the JWT Access Token Validator will not consult locally stored certificates for validating token signatures.
Default Value
One of signing-certificate and jwks-endpoint-path must be specified, but not both.
Allowed Values
An absolute URL, or a relative URL
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

encryption-key-pair

Property Group
Signing and Encryption
Description
The public-private key pair that is used to encrypt the JWT payload. If specified, the JWT Access Token Validator will use the private key to decrypt the JWT payload, and the public key must be exported to the Authorization Server that is issuing access tokens.
Default Value
No decryption will be applied.
Allowed Values
The DN of any Key Pair.
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

allowed-key-encryption-algorithm

Property Group
Signing and Encryption
Description
Specifies an allow list of JWT key encryption algorithms that will be accepted by the JWT Access Token Validator. This setting is only used if encryption-key-pair is set. The JWT Access Token Validator will only accept tokens that are encrypted using key encryption algorithm in this list. This list of allowed algorithms should be strictly limited to those known to be used by the authorization server.
Default Value
RSA_OAEP
Allowed Values
RSA_OAEP - RSA OAEP

ECDH_ES - ECDH-ES

ECDH_ES_A128KW - ECDH-ES with AES-128 Key Wrap

ECDH_ES_A192KW - ECDH-ES with AES-192 Key Wrap

ECDH_ES_A256KW - ECDH-ES with AES-256 Key Wrap
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action

allowed-content-encryption-algorithm

Property Group
Signing and Encryption
Description
Specifies an allow list of JWT content encryption algorithms that will be accepted by the JWT Access Token Validator. The JWT Access Token Validator will only accept tokens that are encrypted using content encryption algorithms in this list. This list of allowed algorithms should be strictly limited to those known to be used by the authorization server.
Default Value
A128CBC_HS256
A192CBC_HS384
A256CBC_HS512
Allowed Values
A128CBC_HS256 - Composite AES-CBC-128 HMAC-SHA-256

A192CBC_HS384 - Composite AES-CBC-192 HMAC-SHA-384

A256CBC_HS512 - Composite AES-CBC-256 HMAC-SHA-512
Multi-Valued
Yes
Required
Yes
Admin Action Required
None. Modification requires no further action


Advanced Properties

subject-claim-name (Advanced Property)

Property Group
General Configuration
Description
The name of the token claim that contains the subject, i.e. the logged-in user in an access token. If the claim specified by this property is present in the access token, then the PingAuthorize Server will set the HttpRequest.AccessToken.user_token flag to "true" when authorizing HTTP requests and responses with the policy decision point.
Default Value
sub
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

client-id-claim-name (Advanced Property)

Property Group
General Configuration
Description
The name of the token claim that contains the OAuth2 client Id.
Default Value
client_id
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

scope-claim-name (Advanced Property)

Property Group
General Configuration
Description
The name of the token claim that contains the scopes granted by the token.
Default Value
scope
Allowed Values
A string
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured Access Token Validators:

dsconfig list-access-token-validators
     [--property {propertyName}] ...

To view the configuration for an existing Access Token Validator:

dsconfig get-access-token-validator-prop
     --validator-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Access Token Validator:

dsconfig set-access-token-validator-prop
     --validator-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new JWT Access Token Validator:

dsconfig create-access-token-validator
     --validator-name {name}
     --type {type}
     --set enabled:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Access Token Validator:

dsconfig delete-access-token-validator
     --validator-name {name}