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.

      The JWT access token validator then retrieves the issuer’s public keys when it initializes. This method ensures that the JWT access token validator uses updated copies of the issuer’s public 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"