JWT Service for App Verify

In order to use App Verify, you must set up and host a JSON Web Token (JWT) service that your mobile application can communicate with. Your mobile application calls the JWT service to request a security token. TeleSign’s verification server then uses the security token to validate your customer ID and determine whether the token is associated with you.

NOTE:

You must have a JWT service if you are working with App Verify.

This document provides general information about how to use JSON Web Tokens (JWT) to authenticate with the App Verify service. If you want to see a complete walkthrough for how to create a JWT service, check out Implement a JWT Service.

Requirements

This section provides details about requirements for setting up your JWT service.

  • You need to be able to store the XID, a unique reference ID you generate and associate with each transaction. The XID is discussed below in section External ID (XID) Token Parameter
  • Follow the JWT formatting requirements presented in the JSON Web Tokens (JWT) section:
  • Header
  • Claims
  • JWT Signature
  • External ID (XID) Token Parameter
  • Decide whether you will use a TeleSign SDK or write your own code to retrieve a JWT token from your server. Using one of TeleSign’s SDKs is recommended as it is easier and more secure.

JSON Web Tokens (JWT)

The App Verify service requires a JWT for authentication. Using JWTs mitigates the risk involved with storing sensitive TeleSign API credentials in mobile applications.

A JWT has the following generic structure:

<base64-encoded header>.<base64-encoded claims>.<base64-encoded signature>

The following is an example of a typical JWT:

Example of a Typical JWT
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

TeleSign requires that you implement JWTs that contain headers, claims, signatures, and the XID parameter as described in the sections below.

Header

This section describes how to implement the JWT header for your JWT token.

Field Type Value
alg String HS256
typ String JWT

Claims

This section describes how to set up claims for your JWT token.

Field Type Value
iss String Customer ID
iat Integer IntDate
exp Integer IntDate
xid String 36 CHAR UUID4

JWT Signature

The JWT signature is produced by concatenating the Base64url encoded header with the Base64url encoded claims, and then signing the string using HMAC with SHA-256. The TeleSign API key is Base64-encoded, so it needs to be decoded before signing it.

The following example shows an assigned TeleSign API key:

TeleSign API Key
Base64url encoded {HMAC-SHA256 of {Base64url encoded(Header) + "." + Base64url encoded(Claims)} using TeleSign issued API key}

For more information, see Requirements.

External ID (XID) Token Parameter

You pass a unique parameter called the External ID (xid) using the JWT in order to keep track of a transaction’s status. It can be any character string up to 36 characters and must be in UUID4 format.

The recommended XID format is a 36 CHAR UUID4 value; for example:

XID Format Example
d01c6dbb-99d3-4335-8e22-11a50a2868f2

For more information, see the UUID4 definition on Wikipedia.