Authorization code (JWT format)

The authorization code is a JSON Web Token (JWT) generated by the issuer. It follows the RFC 7519 specification and provides identity and integrity protection for the TSH server.

JWT is widely used to manage authorization and propagate identity. For implementations, see the libraries listed on jwt.io.

A JSON Web Token has three parts: header, claims, and signature. Each part is a JSON object that is base64url-encoded.

Part 1: the header

The header defines the signing algorithm used for the token.

These are the supported fields and values:

Field	Description
typ	static value 'JWT'
alg	'RS256' where RSA 2048 is used for signature computation and SHA256 for hashing.
kid	Identifier of the key used for the signature of the JWT. It is shared during the onboarding process between the issuer and TSH server. RFU for the management of key rotation. Value which is basically can be whatever value you want, as long as it uniquely identify your key. Can be thumbprint, random ...

Example:

// S{ "typ": "JWT", "alg": "RS256" }

{ "typ": "JWT", "alg": "RS256" }

header (in base64) is:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9

Part 2: the claims

The authorization code contains claims about the authenticated user. It also defines the token validity period. These are the supported claim fields and values:

field	description
iss	The issuerId value provided during the onboarding process.
sub	It shall be either the issuerCardRefId value (already provided in JWE payload) that identifies the authorized PAN for push provisioning request or the tokenId for LCM operation.
aud	The ‘audience’ is the token requestor, so the tokenRequestorId is provided in this field. values as: GOOGLE_PAY / APPLE_PAY / SAMSUNG_PAY
exp	The JWT expiration date, date format is defined in the RFC 7519 specification. Recommended maximum value is current date/time + 5 minutes.
iat	The time at which the JWT was issued.
jti	The JWT's unique identifier. This is an optional field but if set it MUST be unique for each request.

Part 3: the signature

The signature is computed using RSA-2048 and SHA-256 over the concatenated header and claims, using the issuer private key PRIVATE_KEY. The TSH server validates the signature using the certificate provided by the issuer during the onboarding process.

The following Node.js example shows how to generate a JWT:

const jwt = require('jsonwebtoken');
const { v4: uuidv4 } = require('uuid');
const privateKey = fs.readFileSync('private.key');

var JWT = jwt.sign(
  { 
    iss: 'acmebank', 
    sub: panId,
    aud: 'APPLE_PAY',
    exp: Math.floor(Date.now() / 1000) + (2 * 60), // JWT with 2 minutes expiration
    jti: uuidv4(),
  }, 
  privateKey, 
  { algorithm: 'RS256'}
);

Authorization code example:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhY21lYmFuayIsInN1YiI6IjEyMyIsImF1ZCI6IkFQUExFX1BBWSIsImp0aSI6IjE4ODU5NTIxLTFmNTQtNGIxNy1hNjA0LWU0MDFmZTAzMjllZCIsImV4cCI6MTcyMzQ3NDIwNywiaWF0IjoxNzIzNDc0MDg3fQ.GGUfe8o8Uw6wl70bnO0tRgrflLAY63gLU_G_ssqBIP6-mQLO0NSgu8OGmKn2fxD91POfSS1W8aifxZMRnFQ721GBwD8UM9eDjXmglHN-l_ILYv4zEgy9ghZ7j0cif9sGObt2Zz35-21SXccK1twtvjrzAODl7XJ4KfFl8VT2OHhwsB2WT6HKYAw1uB8kPc6S3sOqB6eM3NJ6hw6mBCfSOkEp0KXeipiYmChiylCKWSM6Wv3o5YVn9_9oCi1O6Cw7Tk-F9YqU8GtGrFWNfYRL3VbgUPqIqWbzb88hbuZPC485rfiK56TxIJBbqmdQtqBHcoGWAhywCLD4zbOU3viCzQ