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.

If keys were not added before, expand and follow the procedure before you continue

  1. Go to https://app.synerise.com/spa/modules/params-translator/params-translator/events.
  2. On the Event settings tab, in the Certificate section, click Define.
  3. If a certificate is already added, perform one of the following actions
    • Keep using the existing certificate, no further actions are required.
    • Overwrite the existing certificate by continuing to step 4.
      WARNING: Overwriting a certificate requires providing the new certificate in your backend implementation! JWT tokens signed with the old certificate are rejected!
  4. Open the terminal.
  5. Generate public and private RSA keys by using these commands:
    1. openssl genpkey -out private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048
    2. openssl pkcs8 -topk8 -inform pem -in private.pem -outform DER -nocrypt -out private.der
    3. openssl rsa -pubout < private.pem > public.pem
  6. Perform one of the following actions:
    • To enter the certificate as text, in the Certificate code field paste the certificate without the header and footer.
      The header and footer are: -----BEGIN PUBLIC KEY-----; -----END PUBLIC KEY-----
      Important: The pasted certificate cannot contain line breaks or spaces.
      Tip: To open the certificate in the terminal, you can usually use cat public.pem in the root directory.
    • To upload the certificate as a file, click Upload Certificate > Upload certificate code and select a file from your computer.
  7. Click Apply.

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.

Diagram that shows the logic of JWT authentication
Overview of JWT implementation logic

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)

Note: For details on how to implement token creation and encoding, refer to the documentation of the language or framework you are using.
  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:

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.