Build authentication token

Overview

The digital wallet backend must build an authentication token in the following cases:

• To support green flow enrollment.

• To provide additional wallet data (issuer risk scoring).

The digital wallet backend signs the authentication token with its private key.

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

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

Green flow enrollment

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

Additional wallet data

The authentication token lets the digital wallet provide additional data securely. It helps ensure that no intermediary alters the additional data.

See Provide additional wallet data.

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	Required	Description
iss	Required	Issuer identifier. Use the issuerId assigned during onboarding.
sub	Conditional	Required 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.
wallet	Optional	Additional wallet data in JSON payload format. See Provide additional wallet data.

Payload example:

JWT payload

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

In the example above, sub is b776ce1e1b00be3f03c7fff59d872c32cfd65cc4377766f47af84f48ea8925f2. It is 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.