Authenticating requests with JSON Web Tokens (JWT)

JSON Web Tokens (JWT) can be used to authenticate JS SDK requests from recognized customers. This provides a way to identify customers before authorizing requests that modify personal data.

By default, the form.submit and client.createOrUpdate events require JWT authentication. If you want to enable this for other events, see Event authentication settings.

The tokens are generated by your backend.

Synerise requires a JWT encoded with the RS256 algorithm (this is not the default algorithm used by the jwt.io debugger).

Prerequisites:

A public RSA key must be added to Synerise.

Implementation overview

This flowchart is a high-level overview of the JWT creation logic. Your implementation must cover all of these scenarios.

The details are described in this section.

Implementation details

When a customer provides their email (for example, when logging in), generate a JWT for the customer.

The provided email is used as customer_email everywhere in this process.

Check if identity hash exists

1. Initialize the JS SDK.
2. Check the current identity hash by calling the SR.client.getIdentityHash() method.
3. Depending on the result, continue to one of these procedures:
   1. If the method returns an empty string, the hash does not exist. Follow this instruction.
   2. If the method returns a non-empty string, a hash exists. Follow this instruction.

If an identity hash does NOT exist

1. Generate an identity hash by calling the SR.client.hashIdentity("customer_email") method.
2. From the _snrs_uuid cookie, retrieve the customer’s UUID.
3. Generate a JWT. In the payload, provide the customer_email and the UUID retrieved from the cookie.
   For details, see this section.
4. Call the SR.client.setUuidAndIdentityHash("email_hash", "customer_uuid") method, where:

• email_hash is the hash you generated earlier with SR.client.hashIdentity("customer_email")
• customer_uuid is the customer UUID retrieved from the _snrs_uuid cookie and encoded in the JWT

Result:
The customer can now send events that require JWT authentication.

If an identity hash exists

1. Call the SR.client.getIdentityHash() method.
2. Call the SR.client.hashIdentity("customer_email") method.
3. Compare the returned values.
   • If the values are identical, the identity matches the current customer. Follow this this instruction.
   • If the values are different, the identity does not match the current customer. Follow this this instruction.

If the identity matches the current customer

1. From the _snrs_uuid cookie, retrieve the customer’s UUID.
2. Generate a JWT. In the payload, provide the customer_email and the UUID retrieved from the cookie.
   For details, see this section.

Result:
The customer can now send events that require JWT authentication.

If the identity does not match the current customer:

1. Generate a new UUIDv5 using the customer_email.
   For details, see this section.
2. Generate an identity hash by calling the SR.client.hashIdentity("customer_email") method.
3. Generate a JWT. In the payload, provide the customer_email and the UUID you generated. For details, see this section.
4. Call the SR.client.setUuidAndIdentityHash("email_hash", "customer_uuid") method, where:

• email_hash is the hash you generated earlier with SR.client.hashIdentity("customer_email")
• customer_uuid is the customer UUID retrieved from the _snrs_uuid cookie and encoded in the JWT

Result:
The customer can now send events that require JWT authentication.

Generating JSON Web Tokens (JWT)

1. In the header, include the following data:
   

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

2. In the payload, include the following data:
   

   {
   "exp": 1599737564, // expiry time as a UNIX timestamp, less than 7 days away
   "uuid": "af0a5e16-dc1f-5242-8b22-daf62c3cb78d", // customer's UUID
   "email": "customer.email@domain.com" // customer's email
   }

   Important: The token lifetime cannot be longer than 7 days.

3. Sign the token with the public and private keys.

4. Encode the token.

5. Apply the encoded token in one of the following ways:

   • Store the token in the _snrs_token cookie.
   • Call the SR.client.setAccessToken("token-as-a-string") JS SDK method.

   Result:
   The JWT is stored as snr-token in local storage. If you applied the token by using a cookie, the cookie is deleted.

You may want to return to:

• The identity hash does not exist
• The identity hash matched the current customer
• The identity hash did not match the current customer