PingOne Platform APIs

Create a login_hint_token JWT

A login_hint_token is a JWT that provides a way for the client to identify and authenticate the end-user without needing to encode the entire authentication request in a signed JWT. The following information describes the OIDC parameters and the steps for generating and signing the token.

Prerequisites

  1. Install a JWT token generator such as jwtgen globally using npm install -g jwtgen. This action requires npm.

  2. Retrieve the environment id property value associated with your worker application and user.

  3. Retrieve the clientId and clientSecret property values for the worker application.

  4. Retrieve the user ID id or username property value for whom this token will be associated.

For non-production applications, you can use the PingOne Login Hint Token Generator to generate a login_hint_token value. This utility requires the same parameters described above (environment ID, client ID, client secret, and user ID or username). The tool also requires that you select one of PingOne’s geographic regions.

Generate a signed token

The header parameters cty and enc must not be included in the login_hint_token JWT header. PingOne does not support nested signing or encryption operations here.

The command to generate the login_hint_token JWT takes the following parameters:

Parameter Description

-a

Specifies the JWT signing algorithm. Options are HS256, HS384, and HS512.

-s

Specifies the signing key, which is the application’s clientSecret property value.

-e

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

--claims

Specifies the claims required by the token:

  • iss: A string that specifies the client ID of the issuer creating the token

  • sub: A string that specifies the identifier for the authenticated user (for example, the id or username property value).

  • iat: An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued.

  • exp: An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire.

  • aud: A string that specifies the intended audience for this token.

For example, a common iss claim value is the client ID for PingFederate, with the aud claim specifying PingOne as the intended audience for the token. The issuer claim identifies the identity provider that authenticated the user (PingFederate) and the audience claim identifies PingOne.

  1. Run the jwtgen command.

    jwtgen -a "HS256" -s "YOUR_CLIENT_SECRET" -e 3600 --claims '{
"iss":"YOUR_CLIENT_ID",
"sub":"YOUR_USER_ID_OR_USERNAME",
"iat":1300819380,
"exp":1300819391,
"aud":"https://auth.pingone.com/YOUR_ENVIRONMENT_ID/as"
}'

  2. Record the token returned successfully by the command to use as the value of the login_hint_token property in the authorize request.

You can use the PingOne JWT Decoder to view the claims information in a JSON Web Token. This utility asks you to provide the JWT token, and it returns a Header (the type of encoded object in the payload), the Payload (the JWT claims set), and the Signature (an encoding of the Header and Payload).