PingAM 7.5.1

Encrypt ID tokens and backchannel logout tokens

AM supports encrypting ID tokens and backchannel logout tokens to protect them against tampering attacks, outlined in the JSON Web Encryption specification (RFC 7516).

ID tokens and backchannel logout tokens share the same encryption configuration. You either encrypt both or none.

  1. Go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID.

  2. On the Signing and Encryption tab, select Enable ID Token Encryption.

  3. In the Id Token Encryption Algorithm field, enter the algorithm AM will use to encrypt ID tokens and backchannel logout tokens:

    Supported encryption algorithms

    • A128KW - AES Key Wrapping with 128-bit key derived from the client secret.

    • A192KW - AES Key Wrapping with 192-bit key derived from the client secret.

    • A256KW - AES Key Wrapping with 256-bit key derived from the client secret.

    • RSA-OAEP - RSA with Optimal Asymmetric Encryption Padding (OAEP) with SHA-1 and MGF-1.

    • RSA-OAEP-256 - RSA with OAEP with SHA-256 and MGF-1.

    • RSA1_5 - RSA with PKCS#1 v1.5 padding (not recommended).

    • dir - Direct encryption with AES using the hashed client secret.

    • ECDH-ES - Elliptic Curve Diffie-Hellman

    • ECDH-ES+A128KW - Elliptic Curve Diffie-Hellman + AES Key Wrapping with 128-bit key.

    • ECDH-ES+A192KW - Elliptic Curve Diffie-Hellman + AES Key Wrapping with 192-bit key.

    • ECDH-ES+A256KW - Elliptic Curve Diffie-Hellman + AES Key Wrapping with 256-bit key.

    • X25519 - Elliptic Curve Diffie-Hellman with Curve25519.

    • X448 - Elliptic Curve Diffie-Hellman with Curve448.

    Only the P-256, P-384, and P-521 curves are supported.

  4. In the ID Token Encryption Method field, enter the method AM will use to encrypt ID tokens and backchannel logout tokens:

    Supported encryption methods

    • A128CBC-HS256 - AES 128-bit in CBC mode using HMAC-SHA-256-128 hash (HS256 truncated to 128 bits)

    • A192CBC-HS384 - AES 192-bit in CBC mode using HMAC-SHA-384-192 hash (HS384 truncated to 192 bits)

    • A256CBC-HS512 - AES 256-bit in CBC mode using HMAC-SHA-512-256 hash (HS512 truncated to 256 bits)

    • A128GCM - AES 128-bit in GCM mode

    • A192GCM - AES 192-bit in GCM mode

    • A256GCM - AES 256-bit in GCM mode

  5. If you select an RSA encryption algorithm, perform one of the following actions:

    • Enter the public key in the Client ID Token Public Encryption Key field.

    • Enter a JWK set in the Json Web Key field.

    • Enter a URI containing the public key in the Json Web Key URI field.

  6. If you select an ECDH-ES encryption algorithm, perform one of the following actions:

    • Enter a JWK set in the Json Web Key field.

    • Enter a URI containing the public key in the Json Web Key URI field.

  7. If you select an algorithm other than RSA or ECDH-ES, select the Core tab and do either of the following:

    • Store the private key/secret in the Client secret field.

    • Set a Secret Label Identifier and store the secret in a secret store.

      AM uses the Secret Label Identifier to create a specific secret label for each OAuth 2.0 client. The secret label takes the form am.applications.oauth2.client.identifier.secret where identifier is the value of Secret Label Identifier.

      The identifier can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

      If you set a Secret Label Identifier and AM finds a matching secret in a secret store, the Client secret is ignored.

  • Several features of OAuth 2.0 use the string stored in the Client secret field to sign/encrypt tokens or parameters when you configure specific algorithms. For example, signing ID tokens with HMAC algorithms, encrypting ID tokens with AES or direct algorithms, or encrypting OpenID Connect parameters with AES or direct algorithms.

    These features must share the key/secret stored in the Client secret field, and you must ensure that they’re configured with the same algorithm.

  • If you set a Secret Label Identifier instead of a Client secret field, you can have multiple OAuth 2.0 client secrets in the secret store. This lets you rotate and retire secrets as necessary.

    AM uses the active secret in the secret store to encrypt or sign an ID Token. However, the relying party (RP) can initiate an OAuth 2.0 request with any one of the valid secrets in the secret store. Therefore, the active secret might not be the same secret that the RP used to initiate the request.

    For example, an OAuth 2.0 request might come in with a valid, non-active secret. AM encrypts the ID Token with the active secret. Regardless of the secret that the RP used to initiate the flow, the RP can only decrypt the token using the active secret (the secret with which AM encrypted the token).