A request property JWT enables OIDC/OAuth2 request parameters to be passed as a single, self-contained parameter. Using a JWT enables integrity protection of parameters that are required for risk-based authentication or privacy and consent use cases.

This sample shows the information required in a transaction approval JWT:

"jwtHeader": {
  "alg": "HS256",
  "typ": "JWT"
},
"jwtBody":
{
  "aud": "https://auth.pingone.com/{{envId}}/as",
  "iss": "{{appId}}",
  "pi.template": {
    "name": "transaction",
    "variables": {
      "sum": "1,000,000",
      "currency": "USD",
      "recipient": "Charlie Parker"
    }
  },
  "pi.clientContext": {
    "alert.color": "red"
  }
}

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 name of the transaction notification template that you want to use.

Generate a signed token

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

Parameter Description
-a Specifies the JWT signing algorithm. Options are HS256.
-s Specifies the signing key, which is the application’s clientSecret property value.
--claims Specifies the claims required by the token:
  • iss: A string that specifies the application ID of the issuer creating the token
  • aud: A string that specifies the intended audience for this token.
  • pi.template: A string that specifies the template name and the variables required by the template.
  • pi.clientContext: A string that specifies the key-value pairs that define the client context.
  • pi.remoteIp: A string that specifies the user’s IP address. This is an optional property used with authentication policies that include IP-based conditions.

The following command creates a JWT for the request property specified in the authorization request:

  1. Run the jwtgen command.
jwtgen -a "HS256" -s "<applicationSecret>" --claims '{
    "aud":"https://auth.pingone.com/{{envId}}/as",
    "iss":"{{appId}}",
    "pi.template":{"name":"transaction","variables":{"sum":"1,000,000","currency":"USD","recipient":"Charlie Parker"}},
    "pi.clientContext":{"alert.color":"red"}}'
  1. Record the token returned successfully by the command to use as the value of the request property in the authorize request.