PingAM 7.5.1

JWT profile

The OAuth 2.0 client authenticates by sending a signed JSON Web Token (JWT) Bearer Token as described in RFC 7523, JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants:

$ curl \
--request POST \
--data "client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer" \
--data "client_assertion=the-signed-JWT" \
…​

Client configuration

The JWT issuer must digitally sign the JWT or apply a Message Authentication Code (MAC). When the client is the JWT issuer, it can sign the JWT with a private key.

To use this authentication method for a confidential OAuth 2.0 client, edit the client profile in the AM admin UI:

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

  2. Add Grant Types: JWT Bearer.

  3. Set Token Endpoint Authentication Method to private_key_jwt.

  4. Save your work before switching tabs.

  5. Update additional settings depending on the mechanism for signing the JWT.

    AM must validate the JWT to authenticate the client.

    Mechanism Settings

    Certificate-based

    The client protects the JWT with public-private key cryptography with the public key in a digital certificate.

    1. Store the PEM-format value of the JWT issuer’s public key as a secret in the secret store.

    2. Map this secret to the am.applications.oauth2.client.identifier.jwt.public.key secret label, where identifier is the value of the Secret Label Identifier configured for the client on the Core tab.

    You can store the JWT issuer’s public key in the configuration, but storing it in a secret store is more secure and makes the secret easier to rotate. To store the key in the configuration:

    1. On the Signing and Encryption tab, set Client JWT Bearer Public Key to the PEM-format value of the JWT issuer’s public key, for example:

      -----BEGIN CERTIFICATE-----
MIIDETCCAfmgAwIBAgIEU8SXLjANBgkqhkiG9w0BAQsFADA5MRswGQYDVQQKExJvcGVuYW0uZXhh
bXBsZS5jb20xGjAYBgNVBAMTEWp3dC1iZWFyZXItY2xpZW50MB4XDTE0MTAyNzExNTY1NloXDTI0
...
TeGSgcqEAd6XlGXY1+M/yIeouUTi0F1bk1rNlqJvd57Xb4CEq17tVbGBm0hkECM8
-----END CERTIFICATE-----

    2. Set Public key selector to X509.

    If AM finds a valid secret mapped to the am.applications.oauth2.client.identifier.jwt.public.key secret label, it ignores the contents of this field.

    A client can have only one public key.

    HMAC secret

    The client protects the JWT with a Hash-based Message Authentication Code (HMAC).

    On the Core tab, reset the client secret to the HMAC secret.

    The HMAC secret must contain at least 32 octets and sufficient entropy for a cryptographically strong key, as described in the Symmetric Key Entropy section of the OpenID Connect 1.0 specification.

    A client can have only one HMAC secret.

    JWK set in the client profile

    The client protects the JWT with public-private key cryptography with the public key in a JSON Web Key (JWK).

    On the Signing and Encryption tab:

    1. Set Public key selector to JWKs.

    2. Paste the JWK set into the Json Web Key field.

      The JWK set is similar to the following:

      {
  "keys": [
    {
      "alg": "RSA-OAEP-256",
      "kty": "RSA",
      "use": "sig",
      "kid": "RemA6Gw0...LzsJ5zG3E=",
      "n": "AL4kjz74rDo3VQ3Wx...nhch4qJRGt2QnCF7M0",
      "e": "AQAB"
    }
  ]
}

      Enter a JWK set with multiple JWKs for certificate rotation.

    JWK set in a URI

    The client protects the JWT with public-private key cryptography with the public key in a JWK.

    On the Signing and Encryption tab:

    1. Set Public key selector to JWKs_URI.

    2. Paste the URI to the JWK set into the Json Web Key URI field.

  6. Save your work.

Make sure all connections to AM use HTTPS to protect any secrets, including the JWT.

The JWT profile flow

The following sequence diagram shows a JWT profile authentication flow:

JWT profile client authentication
Figure 1. JWT profile client authentication

  1. The client requests a JWT from the issuer.

    Clients can generate their own JWTs. They can also delegate the task to a separate service in the deployment.

    AM cannot generate JWTs for this purpose.

  2. The issuer returns a signed JWT to the client.

  3. The client POSTs the JWT and a client assertion type as parameters of an OAuth 2.0 request:

    • client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer

    • client_assertion=the-signed-JWT

  4. AM validates the JWT using the public key from the client profile.

  5. AM issues the response, such as an access token.

The JWT profile claims

The JWT Bearer Token must contain at least the following claims:

Claim Description

aud

The authorization server that is the intended audience of the JWT; must be the AM token endpoint, such as https://openam.example.com/openam/oauth2/realms/root/realms/alpha/access_token.

To specify additional audiences that will be permitted when verifying the JWT, set the Additional Audience Values property of the OAuth 2.0 provider.

exp

The expiration time.

This must be at most 30 minutes in the future. If not, AM returns a JWT expiration time is unreasonable error message.

iss

The unique identifier of the issuer that digitally signs the JWT:

  • The client_id if it generates its own JWT.

  • A third party if a separate service generates the JWT.

jti

A random, unique identifier for the JWT.

Required if the client requests the openid scope; otherwise optional.

sub

The principal who is the subject of the JWT; must be the client_id.

AM ignores keys specified in JWT headers, such as jku and jwe.

For additional details, refer to the section of RFC 7523 on JWT Format and Processing Requirements.

Sample JWT profile client

The AM code samples include a Java-based client to test the JWT token bearer flow.

For details, read to How do I access and build the sample code provided for PingAM?.