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.
OpenID Connect ID Token Validators validate ID tokens issued by any OpenID Connect provider.
↓Parent Component
↓Relations from This Component
↓Properties
↓dsconfig Usage
The OpenID Connect ID Token Validator component inherits from the ID Token Validator
The following components have a direct aggregation relation from OpenID Connect ID Token Validators:
The properties supported by this managed object are as follows:
| General Configuration Basic Properties: | Advanced Properties: |
|---|---|
| ↓ description | ↓ subject-claim-name |
| ↓ enabled | |
| ↓ identity-mapper | |
| ↓ issuer-url | |
| ↓ clock-skew-grace-period | |
| ↓ evaluation-order-index | |
| Token Signing Basic Properties: | Advanced Properties: |
| ↓ allowed-signing-algorithm | ↓ jwks-cache-duration |
| ↓ signing-certificate | |
| ↓ openid-connect-provider | |
| ↓ jwks-endpoint-path |
| Property Group | General Configuration |
| Description | A description for this ID 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 ID Token Validator is enabled for use in the PingAuthorize 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 | Specifies the name of the Identity Mapper that should be used to correlate an ID token subject value to a user entry. 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 | None |
| Allowed Values | The DN of any Identity Mapper. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Property Group | General Configuration |
| Description | Specifies the OpenID Connect provider's issuer URL. This value uniquely identifies the OpenID Connect provider. An OpenID Connect provider will always provide its issuer URL as the value of an ID token's iss claim. If the value configured here does not exactly match the actual value in an ID token's iss claim, then the ID token will be considered invalid. In addition, if the relying party (for example, the Administrative Console) provides an issuer URL via an OAuth Bearer SASL bind, then that value must exactly match this issuer URL. |
| Default Value | None |
| Allowed Values | An absolute URL, or a relative URL |
| Multi-Valued | No |
| Required | Yes |
| 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 ID 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 | General Configuration |
| Description | When multiple ID Token Validators are defined for a single PingAuthorize Server, this property determines the order in which the ID Token Validators are consulted. Values of this property must be unique among all ID Token Validators defined within PingAuthorize Server but not necessarily contiguous. ID Token Validators with lower values will be evaluated first to determine if they are able to validate the ID token. |
| Default Value | None |
| 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 | Token Signing |
| Description | Specifies an allow list of JWT signing algorithms that will be accepted by the OpenID Connect ID Token Validator. The OpenID Connect ID Token Validator will only accept tokens that are signed using signing algorithms in this list. This list of allowed signing algorithms should be strictly limited to those known to be used by the OpenID Connect provider and no others. In general, 'RS256' may be chosen, as it is required by the OpenID Connect standard, but some providers may support more secure signing algorithms. If the OpenID Connect provider is PingFederate, then the supported ID token signing algorithm can be found in the client's ID Token Signing Algorithm configuration property. |
| Default Value | None |
| 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 | Token Signing |
| Description | Specifies the locally stored certificates that may be used to validate the signature of an incoming ID token. This property may be specified if a JWKS endpoint should not be used to retrieve public signing 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 | Token Signing |
| Description | Specifies the OpenID Connect provider that issues ID tokens handled by this OpenID Connect ID Token Validator. This property is used in conjunction with the jwks-endpoint-path property. |
| Default Value | Not specifying an OpenID Connect provider implies that no external communication is required to validate ID 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 | Token Signing |
| Description | The relative path to the JWKS endpoint from which to retrieve one or more public signing keys that may be used to validate the signature of an incoming ID token. This path is relative to the base_url property defined for the validator's OpenID Connect provider. If jwks-endpoint-path is specified, the OpenID Connect ID 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 |
subject-claim-name (Advanced Property)
| Property Group | General Configuration |
| Description | The name of the token claim that contains the subject; i.e., the authenticated user. This property specifies the token claim that contains the subject, which is the authenticated user identified by the ID token. The subject value is used by the validator's Identity Mapper to look up a matching user entry. By default, the standard sub claim is used. However, this value can be customized if the ID token contains a more appropriate claim to use for identity correlation. |
| Default Value | sub |
| Allowed Values | A string |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
jwks-cache-duration (Advanced Property)
| Property Group | Token Signing |
| Description | How often the ID Token Validator should refresh its cache of JWKS token signing keys. The value of this configuration property defines how frequently the ID Token Validator will retrieve the OpenID Connect provider's JWKS public signing keys. If the value is 0, a JWKS request will be performed every time a token validation request is made. |
| Default Value | 2h |
| Allowed Values | A duration. Lower limit is 0 seconds. Upper limit is 2147483647 seconds. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
To list the configured ID Token Validators:
dsconfig list-id-token-validators
[--property {propertyName}] ...
To view the configuration for an existing ID Token Validator:
dsconfig get-id-token-validator-prop
--validator-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing ID Token Validator:
dsconfig set-id-token-validator-prop
--validator-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new OpenID Connect ID Token Validator:
dsconfig create-id-token-validator
--validator-name {name}
--type openid-connect
--set enabled:{propertyValue}
--set identity-mapper:{propertyValue}
--set issuer-url:{propertyValue}
--set evaluation-order-index:{propertyValue}
--set allowed-signing-algorithm:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing ID Token Validator:
dsconfig delete-id-token-validator
--validator-name {name}