Build authentication token (old)

Overview

To support green flow enrollment, the issuer backend must build an authentication token.

The token proves that the issuer previously authenticated the end user and approved the Tokenization request.

Sign the authentication token with the issuer backend private key.

NFC Wallet backend validates the token with the corresponding public key provided during onboarding.

Build the authentication token on the issuer backend. Then pass it to the issuer application.

Authentication token requirements

The authentication token is a JWT (RFC 7519).

JWT is a standard format for transmitting signed claims between systems.

Supported algorithms

NFC Wallet backend supports these signature algorithms:

• RS256

• PS256

• PS512

JWT format

A JWT contains three Base64URL-encoded parts separated by dots (.):

• Header

• Payload

• Signature

The compact format is:

<header>.<payload>.<signature>

Header

The header defines the token type and signature algorithm.

kid is required. NFC Wallet backend uses it to select the correct public key.

Header example:

JWT header

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "12345abcde"
}

Base64URL-encode the header as a single line before generating the signature.

Payload

The payload supports these claims:

Field	Requirement	Description
iss	Required	Issuer identifier. Use the issuerId assigned during onboarding.
sub	Conditional	Provide this claim only if nonce is present in the encrypted card data. Set the value to the SHA-256 hash of the nonce.
iat	Required	Token issuance time, formatted as defined in RFC 7519.
exp	Required	Token expiration time, formatted as defined in RFC 7519.

Payload example:

JWT payload

{
  "iat": 1456815010,
  "exp": 1456851010,
  "iss": "acmeBank",
  "sub": "b776ce1e1b00be3f03c7fff59d872c32cfd65cc4377766f47af84f48ea8925f2"
}

In this example, sub contains the SHA-256 hash of the nonce value abdda9cfbe2fdce335290773ba6f56a9c5ebe64910.

Signature

Compute the signature over the Base64URL-encoded header and payload with the issuer backend private key.

NFC Wallet backend validates the signature with the public key provided during onboarding.

The final JWT is the concatenation of the encoded header, payload, and signature, separated by dots.

Generate the JWT

You can use any JWT library that supports RSA signatures and custom headers.

This example uses the jose4j Java library:

GenerateJwt.java

private static String generateJwt() throws Exception {
    JwtClaims claims = new JwtClaims();
    claims.setIssuer(issuerId);
    claims.setExpirationTimeMinutesInTheFuture(5);
    claims.setIssuedAtToNow();

    if (subject != null) {
        claims.setSubject(subject);
    }

    JsonWebSignature jws = new JsonWebSignature();
    jws.setPayload(claims.toJson());
    jws.setKey(privateKey);
    jws.setHeader("typ", "JWT");
    jws.setHeader("kid", keyId);
    jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256);

    return jws.getCompactSerialization();
}

See JWT libraries by language for supported implementations.