Authenticating Clients Using 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
JWT Bearer Client Authentication

The steps in the diagram are described below:

  1. The client requests a JWT from the issuer.

    Tip

    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/access_token.

    • 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:

    1. 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.

    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. 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. Go to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Signing and Encryption.

      2. In the 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.

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

    1. 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 lenght of the secret, see the Symmetric Key Entropy section of the OpenID Connect specification.

      You can only enter one HMAC secret.

    Tip

    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_id=myClient" \
--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.

Read a different version of :