--- title: JWT profile description: 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: component: pingoneaic page_id: pingoneaic:am-oauth2:client-auth-jwt canonical_url: https://docs.pingidentity.com/pingoneaic/am-oauth2/client-auth-jwt.html keywords: ["Authentication", "OAuth 2.0", "Federation", "JWT", "Clients", "Setup & Configuration"] page_aliases: ["oauth2-guide:client-auth-jwt.adoc"] section_ids: client_configuration: Client configuration the_jwt_profile_flow: The JWT profile flow the_jwt_profile_claims: The JWT profile claims sample_jwt_profile_client: Sample JWT profile client --- # 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](https://www.rfc-editor.org/rfc/rfc7523.html): ```bash $ 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). If 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 Advanced Identity Cloud admin console: 1. Go to Applications > *Name* > Sign On > General Settings > Advanced > Authentication and set Token Endpoint Authentication Method to `private_key_jwt`. 2. Update additional settings depending on the mechanism for signing the JWT. Advanced 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) Store the PEM-format value of the JWT issuer's public key as an ESV 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.Storing the JWT issuer's public key as an ESV in a secret store is more secure and makes the secret easier to rotate.However, you can also store the JWT issuer's public key in the client configuration. To do so:1) Generate a public key certificate based on the PEM value of the private key. For example: ```bash openssl req \ -x509 -new -key [.var]_my-private-key.pem_ \ -out [.var]_my-public-certificate.pem_ ``` If you don't have access to the private key required to create this certificate, consider using a JWK set instead. 2) Under Applications > *Name* > Sign On > General Settings > Advanced > Authentication, set Client JWT Bearer Public Key to the value of the PEM certificate you created in the previous step: ``` -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- ``` If Advanced Identity Cloud finds a valid secret mapped to the am.applications.oauth2.client.identifier.jwt.public.key secret label, it ignores the contents of this field. This format doesn't provide key ID (kid) support. 3) 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](https://openid.net/specs/openid-connect-core-1_0.html#SymmetricKeyEntropy) 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: ```json { "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. | 3. Save your work. Make sure all connections to Advanced 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: ![Advanced Identity Cloud supports use of a JWT for client authentication.](_images/oauth2-jwt-bearer-authn.svg)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. Advanced 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` For example, using the client credentials grant: ```bash $ curl \ --request POST \ --data "client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer" \ --data "client_assertion=the-signed-JWT" \ --data "grant_type=client_credentials" \ "https://[.var]##__##/am/oauth2/realms/root/realms/alpha/access_token" ``` 4. Advanced Identity Cloud validates the JWT using the public key from the client profile. 5. Advanced 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 Advanced Identity Cloud token endpoint, such as `https:///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, Advanced 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. Add the third party issuer to the client configuration for authentication to succeed. Under Native Consoles > Access Management, go to Applications > OAuth 2.0 > Clients > *Client ID* > Advanced and update the Accepted JWT Issuers field. For example, if you add `https://my.issuer.com` to this list, an OAuth 2.0 client, `myClient`, can authenticate with a JWT from that issuer. | | `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`. | Advanced 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](https://www.rfc-editor.org/rfc/rfc7523.html#section-3). ## Sample JWT profile client The Advanced 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?](https://support.pingidentity.com/s/article/How-do-I-access-and-build-the-sample-code-provided-for-PingAM) in the *Knowledge Base*.