PingOne Platform APIs

Create a client secret JWT

The CLIENT_SECRET_JWT property is a supported value on the application’s tokenEndpointAuthMethod property. This client authentication method uses the application’s client secret to sign a JWT, which is passed in as a property to authenticate the token request.

For JWT-based client authentication, the token supports the following required and optional claims.

Claim Type Required Description

iss

String

Required

A string that specifies the issuer. This value must match the application ID (client ID) of the PingOne application.

sub

String

Required

A string that specifies the identifier for the authenticated user. This value must match the application ID (client ID) of the PingOne application.

aud

URI

Required

A string that lists the audience, the resources for which this token is intended. Valid options are: (1) the token endpoint (/as/token), (2) the issuer uri (/as), (3) the endpoint being called (for example, /as/introspect). The value must be the full URL, including the PingOne domain, or custom domain.

exp

Timestamp

Required

A timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire, as defined in JWT RFC7519. This JWT must not be expired. Tokens that expire more than one hour from now are rejected.

nbf

Timestamp

Optional

A "not before" timestamp. If present, the JWT must be valid. JWTs are rejected if nbf is in the future.

Other properties of the JWT are:

  • The optional iat and jti claims from the JSON Web Token (JWT) spec are not validated. Refer to RFC7523 JWT Format and Processing Requirements.

  • The JWT can include other claims in addition to those listed above.

  • The JWT must be signed. For CLIENT_SECRET_JWT signing, the platform supports only the HS256, HS384, and HS512 symmetric keyed hashing algorithm.

  • The JWT must be valid.

Prerequisites and workflow

The following information describes the OIDC parameters and the steps for generating and signing the JWT.

  1. Retrieve the environment id property value associated with your application.

  2. Retrieve the clientId and clientSecret property values for the application.

  3. Install a JWT generator.

  4. Generate the signed JWT using the JWT generator. To create the client_secret_jwt JWT, the token generator will require values for the following parameters:

    Parameter Description

    Signing algorithm

    The JWT signing algorithm. Options for the client_secret_jwt JWT are HS256, HS384, and HS512.

    Signing key

    The signing key for the client_secret_jwt JWT, which is the application’s clientSecret property value.

    Expiration

    The expiration date, expressed as the number of seconds from the time of creation. The typical value is 3600 seconds.

    Claims

    The claims required by the token. Required claims are iss, sub, aud, and exp.

  5. Record the JWT returned successfully by the JWT generator.

If the aud value uses a custom domain, the URL uses the custom domain instead of the PingOne domain and environment ID. For example, https://<customDomain>/as/token.

Use the JWT in a token request

For applications that set the tokenEndpointAuthMethod to CLIENT_SECRET_JWT, the token request requires the following two properties:

  • client_assertion

    A JWT that contains a signed assertion with the application’s credentials. This is the JWT that you generated and signed with your application’s client secret.

  • client_assertion_type

    A string that specifies the client assertion type. The value of this property must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

For more information about the token request, refer to Token.