PingOne Advanced 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" \
...
bash

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

    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:

      openssl req \
-x509 -new -key [.var]_my-private-key.pem_ \
-out [.var]_my-public-certificate.pem_
      bash
      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 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"
    }
  ]
}
      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:

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

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.

    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

  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://<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, 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 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.