Handling signed and encrypted JWTs

The JSON web token (JWT) access token validator can accept encrypted access tokens. To enable this functionality, you must configure the access token validator with a private/public key pair and provide the public key to the token issuer.

About this task

The examples in each step configure a JWT access token validator to handle access tokens signed and encrypted using elliptic curve algorithms. For RSA signing and encryption algorithms, the configuration is similar, but you would choose different values for the allowed-signing-algorithm and allowed-encryption-algorithm properties.

Steps

Create an encryption key pair.

Example:

# Create an encryption key pair
dsconfig create-key-pair \
  --pair-name "JWT Elliptic Curve Encryption Key Pair" \
  --set key-algorithm:EC_256

Create the JWT access token validator:

Choose from:

Store the public key as a trusted certificate in PingAuthorize Server’s local configuration using the signing-certificate property.

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.

# 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 allowed-signing-algorithm:ES256 \
  --set "signing-certificate:JWT Signing Certificate" \
  --set "encryption-key-pair:JWT Elliptic Curve Encryption Key Pair" \
  --set allowed-key-encryption-algorithm:ECDH_ES

# Match the token's subject (sub) claim to the uid attribute
# of a SCIM resource
dsconfig create-token-resource-lookup-method \
  --validator-name "JWT 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

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.

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

# 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 "JWT Access Token Validator" \
  --type jwt \
  --set enabled:true \
  --set allowed-signing-algorithm:ES256 \
  --set "authorization-server:{pingfed}  External Server" \
  --set jwks-endpoint-path:/ext/oauth/jwks \
  --set "encryption-key-pair:JWT Elliptic Curve Encryption Key Pair" \
  --set allowed-key-encryption-algorithm:ECDH_ES

# Match the token's subject (sub) claim to the uid attribute
# of a SCIM resource
dsconfig create-token-resource-lookup-method \
  --validator-name "JWT 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

Export the public encryption key from PingAuthorize Server and provide it to your token issuer.

Without this public encryption key, the issuer cannot encrypt tokens that can be decrypted by the JWT access token validator.

Example:

You can run dsconfig to copy the public key to a file, or you can copy the value of the key pair’s certificate-chain property in the administrative console. Be prepared to enter your connection properties and bind password when prompted.

dsconfig get-key-pair-prop \
  --pair-name "JWT Elliptic Curve Encryption Key Pair" \
  --property certificate-chain