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:

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:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

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

NOTE:

JWT field names are case sensitive and should be entered as lowercase in the following tables.

Header

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

Field Type Value Required Description
alg String HS256 Yes The algorithm used to encrypt the signature. For example, the string value “HS256”, specifies that the JWT is a JSON Web Signature (JWS) that is message authentication coded (MACed) using the HMAC-SHA256 algorithm.
typ String JWT Yes The token type. Set this to the string value “JWT”, to specify that the encoded object is a JSON Web Token (JWT).

Claims

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

Field Type Value Required Description
iss String Customer ID Yes The issuer’s identity. This identifies that the organization is the source of the web token.
iat Integer IntDate Yes The time that the token is issued. The value must be a Unix timestamp in seconds in IntDate format (a JSON numeric value representing the number of seconds from 1970-01-01T0:0:0Z UTC until the specified UTC date/time).
exp Integer IntDate Yes The time at which the token expires. This is the time after which the token is considered invalid and is therefore no longer usable. The time specified by iat must be earlier than exp. The value must be a Unix timestamp in seconds in IntDate format.
xid String 36 CHAR UUID4 Yes A character string up to 36 characters (UUID4 format) to keep track of a transaction’s status.

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.

Resources

The App Verify SDKs include sample code for a JWT service to help you implement your own token service. Access to the code is restricted based on whether you purchased the product or not. You should be able to follow the links provided to the code samples associated with the product you purchased: