PingAuthorize

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.

Example 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

allowed-signing-algorithm

Specifies the signing algorithms that the access token validator accepts.

allowed-key-encryption-algorithm

Specifies the key-encryption algorithms that the access token validator accepts.

allowed-content-encryption-algorithm

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 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 configuration

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"