PingDirectory

Handling signed tokens

The token issuer must cryptographically sign all access tokens that the JSON web token (JWT) access token validator handles. The JWT access token validator validates a token’s signature using a public signing key provided by the issuer.

Steps

  • Configure the JWT access token validator with the issuer’s public signing key:

    Choose from:

    • Store the public key as a trusted certificate in the server’s local configuration using the trusted-certificate property.

    • Provide the issuer’s JSON Web Key Set (JWKS) endpoint using the jwks-endpoint-path property.

      To ensure that the JWT access token validator uses updated copies of the issuer’s public keys, the validator checks the configured JWKS endpoint in the following cases:

      • When the validator initializes

      • If the validator can’t find a suitable key for verification in its current set of keys

Example: Use a locally configured trusted certificate

The following example configures a JWT access token validator to use a locally stored public signing certificate to validate access token signatures. The signing certificate is assumed to have been obtained out-of-band and must be a PEM-encoded X.509v3 certificate.

# Create an identity mapper that expects the token subject to be a uid
dsconfig create-identity-mapper \
	--mapper-name "User ID Identity Mapper" \
	--type exact-match \
	--set enabled:true \
	--set match-attribute:uid \
	--set match-base-dn:ou=people,dc=example,dc=com

# Add the public signing certificate to the server configuration
dsconfig create-trusted-certificate \
	--certificate-name "JWT Signing Certificate" \
	--set "certificate</path/to/signing-certificate.pem"

# Create the Access Token Validator
dsconfig create-access-token-validator \
	--validator-name "JWT Access Token Validator" \
	--type jwt \
	--set enabled:true \
	--set evaluation-order-index:1000 \
	--set allowed-signing-algorithm:RS256 \
	--set "trusted-certificate:JWT Signing Certificate"
	--set "identity-mapper:User ID Identity Mapper"

Example: Use the issuer’s JWKS endpoint

The following example configures a JWT access token validator to retrieve public keys from a PingFederate authorization server’s JWKS endpoint.

# Create an identity mapper that expects the token subject to be a uid
dsconfig create-identity-mapper \
	--mapper-name "User ID Identity Mapper" \
	--type exact-match \
	--set enabled:true \
	--set match-attribute:uid \
	--set match-base-dn:ou=people,dc=example,dc=com

# Change the host name and port below, as needed
dsconfig create-external-server \
	--server-name "PingFederate External Server" \
	--type http \
	--set base-url:https://example.com:9031

# Create the Access Token Validator
dsconfig create-access-token-validator \
	--validator-name "JWT Access Token Validator" \
	--type jwt \
	--set enabled:true \
	--set evaluation-order-index:1000 \
	--set allowed-signing-algorithm:RS256 \
	--set "authorization-server:PingFederate External Server" \
	--set jwks-endpoint-path:/ext/oauth/jwks
	--set "identity-mapper:User ID Identity Mapper"