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" \
...

bash

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

Go to Applications > Name > Sign On > General Settings and add Grant Types: JWT Bearer.
Under Applications > Name > Sign On > General Settings > Advanced > Authentication, set Token Endpoint Authentication Method to private_key_jwt.

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

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

Store the PEM-format value of the JWT issuer’s public key as an ESV in the secret store.
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 client configuration, but storing it as an ESV in a secret store is more secure and makes the secret easier to rotate. To store the key in the client configuration:

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:

If PingOne 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.

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

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

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

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"
    }
  ]
}

json

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:

Under Applications > Name > Sign On > General Settings > Advanced > Signing and Encryption, set Public key selector to JWKs_URI.
In the Json Web Key URI field, paste the URI to the JWK set.

Save your work.

Make sure all connections to PingOne 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:

Figure 1. JWT profile client authentication

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.

PingOne Advanced Identity Cloud cannot generate JWTs for this purpose.
The issuer returns a signed JWT to the client.
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
PingOne Advanced Identity Cloud validates the JWT using the public key from the client profile.
PingOne 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 PingOne Advanced 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, PingOne 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.

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.

Sample JWT profile client

The PingOne 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? in the Knowledge Base.