Access token validator types
PingAuthorize Server works with many different types of access token validators.
Click the tabs to learn more about the following types of access token validators:
-
PingFederate
-
JSON Web Token (JWT)
-
Mock access token
-
Third-party
-
External application programming interface (API) gateway
-
PingFederate
-
JWT
-
Mock access token
-
Third-party
-
External API gateway
PingFederate access token validator
To verify the access tokens that a PingFederate authorization server issues, the PingFederate access token validator uses HTTP to submit the tokens to PingFederate Server’s token introspection endpoint.
This step allows the authorization server to determine whether a token is valid.
If you are using PingFederate 10.0 or earlier, ensure that PingFederate is configured to respond to OAuth and OpenID Connect (OIDC) requests by selecting the Enable OAuth 2.0 Authorization Server (AS) role and OpenID Connect check boxes, as explained in Enabling the OAuth AS role. Starting with PingFederate 10.1, these items are always enabled. |
Because this step requires an outgoing HTTP request to the authorization server, the PingFederate access token validator might perform slower than other access token validator types. The validation result is guaranteed to be current, which is an important consideration if the authorization server permits the revocation of access tokens.
Before attempting to use a PingFederate access token validator, create a client that represents the access token validator in the PingFederate configuration. This client must use the Access Token Validation grant type.
ExampleExample PingFederate access token validator configuration
In PingFederate, create a client with the following properties:
-
Client ID: PingAuthorize
-
Client authentication: Client Secret
-
Allowed grant types: Access Token Validation
Take note of the client secret that is generated for the client, and use PingAuthorize Server’s dsconfig
command to create an access token validator:
# Change the host name and port below, as needed dsconfig create-external-server \ --server-name "{pingfed} External Server" \ --type http \ --set base-url:https://example.com:9031 # Create the Access Token Validator dsconfig create-access-token-validator \ --validator-name "{pingfed} Access Token Validator" \ --type ping-federate \ --set enabled:true \ --set "authorization-server:{pingfed} External Server" \ --set client-id:{pingauthorize} \ --set "client-secret:<client secret>" --set evaluation-order-index:2000 # Match the token's subject (sub) claim to the uid attribute # of a SCIM resource dsconfig create-token-resource-lookup-method \ --validator-name "{pingfed} Access Token Validator" \ --method-name "User by uid" \ --type scim \ --set scim-resource-type:Users \ --set 'match-filter:uid eq "%sub%"' \ --set evaluation-order-index:1000
Replace <client secret> with the client secret value generated by the PingFederate client.
JWT access token validator
The JWT access token validator verifies access tokens that are encoded in JWT format, which can be signed in JSON web signature (JWS) format or signed and encrypted in JSON web encryption (JWE) format.
The JWT access token validator inspects the JWT token without presenting it to an authorization server for validation. Because the JWT access token validator doesn’t make a token introspection request for every access token that it processes, it performs faster than the PingFederate access token validator. The access token is self-validated however, so the JWT access token validator cannot determine whether the token has been revoked.
Supported JWS/JWE features
For signed tokens, the JWT access token validator supports the following JWT web algorithm (JWA) types:
-
RS256
-
RS384
-
RS512
-
ES256
-
ES384
-
ES512
For encrypted tokens, the JWT access token validator supports the following key-encryption algorithms:
-
RSA-OAEP
-
ECDH-ES
-
ECDH-ES+A128KW
-
ECDH-ES+A192KW
-
ECDH-ES+A256KW
For encrypted tokens, the JWT access token validator supports the following content-encryption algorithms:
-
A128CBC-HS256
-
A192CBC-HS384
-
A256CBC-HS512
The JWT access token validator configuration defines three allow lists for the JWS/JWE signing and encryption algorithms that it will accept. You should customize these allow lists to reflect only the signing and encryption algorithms used by your access token issuer and no others. Doing so minimizes the access token validator’s security threat surface.
Configure these allow lists using the following configuration properties.
Property | Description |
---|---|
|
Specifies the signing algorithms that the access token validator accepts. |
|
Specifies the key-encryption algorithms that the access token validator accepts. |
|
Specifies the content-encryption algorithms that the access token validator accepts. |
Mock access token validator
A mock access token validator is a special access token validator type used for development or testing purposes. It accepts arbitrary tokens without validating whether a trusted source issued them. This approach allows a developer or tester to make bearer token-authenticated requests without first setting up an authorization server.
Mock access tokens are formatted as plain-text JSON objects using standard JWT claims.
Always provide the Boolean active
claim when creating a mock token. If this value is true
, the token is accepted. If this value is false
, the token is rejected.
If the sub
claim is provided, a token owner lookup populates the TokenOwner
policy request attribute, as with the other access token validator types.
The following example cURL command provides a mock access token in an HTTP request:
curl -k -X GET https://localhost:8443/scim/v2/Me -H 'Authorization: Bearer {"active": true, "sub":"user.3", "scope":"email profile", "client":"client1"}'
Never use mock access token validators in a production environment because they do not verify whether a trusted source issued an access token. |
Example
Example mock access token validator configuration
The configuration for a mock access token validator resembles the configuration for a JWT access token validator. However, the JSON web signature (JWS) signatures require no configuration because mock tokens are not authenticated.
# Create the Access Token Validator dsconfig create-access-token-validator \ --validator-name "Mock Access Token Validator" \ --type mock --set enabled:true \ --set evaluation-order-index:9999 # Match the token's subject (sub) claim to the uid attribute # of a SCIM resource dsconfig create-token-resource-lookup-method \ --validator-name "Mock Access Token Validator" \ --method-name "User by uid" \ --type scim \ --set 'match-filter:uid eq "%sub%"' \ --set evaluation-order-index:1000
Third-party access token validator
To create custom access token validators, use the Server SDK.
External API gateway access token validator
An external API gateway access token validator is a special access token validator that the Sideband API can use when the API gateway itself can validate and parse access tokens. This type of access token validator accepts a set of parsed access token claims from a trusted gateway and performs no further parsing or validation of its own. For information about how the tokens are processed, see Sideband access token validation.
External API gateway access token validators are exclusively for use by Sideband API endpoints. If you assign an external API gateway access token validator to any other server component, either explicitly or implicitly, it is ignored. |
Example
The following example shows how to configure an external API gateway access token validator with a token resource lookup method and assign it to an existing Sideband API endpoint:
dsconfig create-access-token-validator \ --validator-name "API Gateway Access Token Validator" \ --type external-api-gateway \ --set enabled:true \ --set evaluation-order-index:0 dsconfig create-token-resource-lookup-method \ --validator-name "API Gateway Access Token Validator" \ --method-name "Users by uid" \ --type scim \ --set scim-resource-type:Users \ --set 'match-filter:uid eq "%sub%"' \ --set evaluation-order-index:0 dsconfig set-sideband-api-endpoint-prop \ --endpoint-name "My API" \ --set "access-token-validator:API Gateway-Provided Access Token Validator"