JWT Access Token Validator validates JWT access tokens using local token inspection.
The JWT Access Token Validator component inherits from the External Access Token Validator
The following components have a direct aggregation relation from JWT Access Token Validators:
The properties supported by this managed object are as follows:
| General Configuration Basic Properties: | Advanced Properties: |
|---|---|
| identity-mapper | subject-claim-name |
| description | client-id-claim-name |
| enabled | scope-claim-name |
| evaluation-order-index | |
| 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 |
| Property Group | General Configuration |
| Description | Specifies the name of the Identity Mapper that should be used for associating user entries with Bearer token subject names. The claim name from which to obtain the subject (i.e. the currently logged-in user) may be configured using the subject-claim-name property. |
| Default Value | Requests must specify a fully qualified DN. No attempt will be made to map a user name to a DN. |
| Allowed Values | The DN of any Identity Mapper. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| 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 |
| Property Group | General Configuration |
| Description | Indicates whether this Access Token Validator is enabled for use in Directory Server. |
| Default Value | None |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Property Group | General Configuration |
| Description | When multiple JWT Access Token Validators are defined for a single Directory Server, this property determines the evaluation order for determining the correct validator class for an access token received by the Directory Server. Values of this property must be unique among all JWT Access Token Validators defined within Directory 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
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. This property goes hand-in-hand with the identity-mapper property and tells the Identity Mapper which field to use to look up the user entry on the server. |
| 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 |
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}