Access Management 7.2.2

Authenticate clients with JWT profiles

Clients can send a signed JWT to the authorization server as credentials instead of the client ID and/or secret, as per (RFC 7523) JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants. The authorization server must be able to validate the JWT to authenticate the client.

The following diagram demonstrates the JWT Bearer client authentication flow:

JWT Bearer Client Authentication
Figure 1. JWT Bearer Client Authentication

  1. The client requests a JWT from the issuer.

    Clients usually generate their own JWTs before starting the OAuth 2.0/OpenID Connect flow, but they can delegate the task to a specific service in your environment if required. AM cannot generate JWTs for this purpose.

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

    The JWT must contain, at least, the following claims in the payload:

    • iss. Specifies the unique identifier of the JWT issuer. This could also be the client, or a third party.

    • sub. Specifies the principal who is the subject of the JWT. Must be set to the client ID.

    • aud. Specifies the authorization server that is the intended audience of the JWT. Must be set to the authorization server’s token endpoint. For example, https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token.

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

    • exp. Specifies the expiration time.

      Providing a JWT with an expiry time greater than 30 minutes causes AM to return a JWT expiration time is unreasonable error message.

    • jti. Specifies a random, unique identifier for the JWT.

      This claim is required if the client requests the openid scope and optional otherwise.

    For more information about the JWT, read the RFC 7523 standard.

    The JWT issuer must digitally sign the JWT or have a Message Authentication Code (MAC) applied by the issuer. When the issuer is also the client, the client can sign the JWT by using a private key.

    AM ignores keys specified in JWT headers, such as `jku` and `jwe`. Regardless of who issues the JWT, you must configure the public key or HMAC secret in the client profile so AM can validate it:

    Configuring certificates represented as PEM files

    1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Signing and Encryption.

    2. In the Client JWT Bearer Public Key field, enter the public certificate. For example:

      -----BEGIN CERTIFICATE-----
MIIDETCCAfmgAwIBAgIEU8SXLjAN...
-----END CERTIFICATE-----

      You can only enter one certificate.

    3. In the Public key selector drop-down list, select X509.

    Configuring Public Keys in JWK Format

    You can either enter the JWK Set in the client profile, or store the JWK Set in a URI that exposes it to AM:

    • To store the JWK Set in the client profile:

      1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Signing and Encryption.

      2. In the Json Web Key field, enter the JWK Set. For example:

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

        Enter a JWK Set with multiple JWKs if you plan to rotate certificates.

      3. In the Public key selector drop-down list, select JWKs.

    • To store the JWK Set in a URI:

      1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Signing and Encryption.

      2. In the [.label]# Json Web Key URI# field, configure the URI that exposes the JWK Set.

        Ensure that the following related properties have sensible values for your environment:

        • JWKs URI content cache timeout in ms

        • JWKs URI content cache miss cache time

      Store a JWK Set with multiple JWKs if you plan to rotate certificates.

      1. In the Public key selector drop-down list, select JWKs_URI.

    Configuring HMAC secrets

    1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Core.

    2. In the Client secret field, enter the HMAC secret. For more information about the length of the secret, see the Symmetric Key Entropy section of the OpenID Connect specification.

      You can only enter one HMAC secret.

    OpenID Connect clients must also specify the authentication method they are using in their client profiles. See OpenID Connect client authentication.

  3. The client includes the JWT and a client assertion type in the call to the OAuth 2.0 endpoint in the following parameters:

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

    • client_assertion=my_JWT

    For example:

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

  4. The authorization server validates the JWT with the public key stored in the client profile.

  5. The authorization server issues a response to the client. This response may include, for example, an access token.

A sample Java-based client to test the JWT token bearer flow is provided.

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for AM (All versions)? in the Knowledge Base.