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",
    "variant": "{{variantName}}",
    "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

Install a JWT token generator such as jwtgen globally using npm install -g jwtgen. This action requires npm.
Retrieve the environment id property value associated with your worker application and user.
Retrieve the clientId and clientSecret property values for the worker application.
Retrieve the name of the transaction notification template that you want to use.

Note: For non-production applications, you can use the PingOne JWT Encoder located on the Developer Tools page (JWT Encoder) to generate a JSON Web Token. This utility asks you to provide values for the JWT header, the JWT payload (the set of claims), and the RSA private key. The JWT Encoder page provides detailed documentation about these three components.

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. For information see Notifications Templates. `pi.clientContext`: A string that specifies the key-value pairs that define the client context. For information see Device Authentictation. `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:

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

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

Note: You can use the PingOne JWT Decoder located on the Developer Tools page (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).