Identity Cloud

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 Identity Cloud admin UI:

  1. Go to Applications > Name > Sign On > General Settings and add Grant Types: JWT Bearer.

  2. Under Applications > Name > Sign On > General Settings > Advanced > Authentication, set Token Endpoint Authentication Method to private_key_jwt.

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

    Identity Cloud 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. Under Applications > Name > Sign On > General Settings > Advanced > Authentication, set Client JWT Bearer Public Key to the PEM-format value of the JWT issuer’s public key, as in the following example:

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

    2. Under Applications > Name > Sign On > General Settings > Advanced > Signing and Encryption, set Public key selector to X509.

    A client can have only one public key.

    HMAC secret

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

    1. Under Applications > Name > Client Credentials, 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):

    1. Under Applications > Name > Sign On > General Settings > Advanced > Signing and Encryption, set Public key selector to JWKs.

    2. In the Json Web Key field, paste the JWK Set, as in the following 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 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:

    1. Under Applications > Name > Sign On > General Settings > Advanced > Signing and Encryption, set Public key selector to JWKs_URI.

    2. In the Json Web Key URI field, paste the URI to the JWK set.

  4. Save your work.

Make sure all connections to Identity Cloud 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.

    Identity Cloud 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. Identity Cloud validates the JWT using the public key from the client profile.

  5. Identity Cloud 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 Identity Cloud token endpoint, such as https://<tenant-env-fqdn>/am/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, Identity Cloud 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.

Identity Cloud 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 Identity Cloud code samples include a Java-based client to test the JWT token bearer flow.

For details, refer to How do I access and build the sample code provided for AM (All versions)? in the Knowledge Base.

Copyright © 2010-2024 ForgeRock, all rights reserved.