Create the pre-authorized request

Pre-authorized request payload claims

The pre-authorized request payload must contain the following claims.

Table 1. MUST claims
Claim name	Description	Valid values
iss	Unique identifier of credential issuer that issued the JWT	Valid URI of the credential issuer.
sub	Principal subject identifier	The unique identifier of a user.
exp	JWT expiration time	The number of seconds from 1970-01-01T0:0:0Z as measured in UTC. Note: The JWT expiration time cannot be more than 3600 seconds in the future.
jti	JWT identifier	A randomly generated opaque string.

The pre-authorized request payload can contain the following claims.

Table 2. MAY claims
Claim name	Description	Valid values
aud	The authorization server's issuer published in well-known endpoint.	Valid URI of the credential issuer.
sub_type	Principal subject identifier type.	Either 'uid', 'username', or 'externalId'. The default is 'uid'.
realm	Principal subject realm	The identity source realm that the `sub` belongs to.
iat	JWT creation time	The number of seconds from 1970-01-01T0:0:0Z as measured in UTC. Note: The JWT creation time cannot be more than 3600 seconds in the past.
tx_code	Credential issuer's override of pre-authorized settings.	A JSON object having claims as described in the Transaction code claims table.
issuer_state	An opaque value to bind credential issuer context with the access token generated.	Any string. It can also be a JWT.

The tx_code claim only take effect when such override is allowed in pre-authorized settings. In this mode, when the tx_code claim presents, a transaction code is generated. The Transaction code claims tables describe possible override options.

Table 3. Transaction code claims
Claim name	Description	Valid value
input_mode	Determine the transaction code character-set.	Either 'numeric' (only numbers) or 'text' (alphanumeric)
length	Determine the length of transaction code.	A numeric value between 4-10
description	The message for wallet application to show to the end-user.	Any string
channel	Describe how to deliver the transaction code to the end-user.	A JSON object having claims as described in Table 4 below.

Three channels are available to deliver the transaction code: email, sms, or other means that are determine by credential issuer. For the last option, the authorization server just returns the transaction code to the credential issuer.

Table 4. Channel claims
Claim name	Description	Valid value
type	Channel type to deliver transaction code to end-user.	Either 'email', 'sms' or 'issuer'
value	End-user email address (for `type` = email) or phone number (for type = `sms`).	Valid email address or phone number.

Pre-uthorized request payload example

{
  "iss": "https://www.credential-issuer.com",
  "sub": "user@idsource.com",
  "sub_type": "username",
  "aud": "https://sometenant.ice.com/oauth2",
  "exp": 1324298520,
  "jti": "araiov8werli2awerlj",
  "tx_code": {
    "input_mode": "text",
    "length": 6,
    "description": "Please provide this transaction code:",
    "channel": {
       "type": "email",
       "value": "bob@ibm.com"
    },
  },
  "issuer_state": "sa82jpawfagnns"
}

Supported algorithms

The pre-authorized request JWT can be signed using any of these algorithms RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, and PS512.

This JWT is validated based on the credential issuer's JWKS URI. Ensure that the signed JWT includes the kid header to uniquely identify the key that is used because the JWKS URI might publish multiple keys. The configuration of the credential issuer's JWKS URI is done at the federation settings. Ensure that the issuer's identifier matches with the iss claim in the request payload.

Request example

After the pre-authorized request JWT is created, a request can be submitted to the pre-authorized endpoint to generate pre-authorized code.

 curl -ki -X POST https://<tenantId>/oauth2/preauth --data "eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.eyJpc3Mi..." -H "Content-Type:application/jwt"