[JSON Web Tokens (JWT)](https://jwt.io/) 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.
See implementation of event authorization with JWT in [Event authorization in JS SDK with Flask](/use-cases/anonymous-profile-to-recognized).
By default, the `form.submit` events require JWT authentication. If you want to enable this for other events, see [Event authentication settings](/docs/assets/events/event-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](https://jwt.io/)).
JWTs created for use with Web SDK can't be used to authenticate API requests. This is a different type of authentication.
## 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 Data Modeling Hub icon Data Modeling Hub > Events.

  2. On the JS SDK 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.

    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 with the header and footer.
      The header and footer are: -----BEGIN PUBLIC KEY-----; -----END PUBLIC KEY-----

    The pasted certificate cannot contain line breaks or spaces.

    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](#implementation-details).
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. 1. Check the current identity hash by calling the `SR.client.getIdentityHash()` method. 2. 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](#if-an-identity-hash-does-not-exist). 2. If the method returns a non-empty string, a hash exists. Follow [this instruction](#if-an-identity-hash-exists). ### 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](#generating-json-web-tokens-jwt). 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-identity-matches-the-current-customer). - If the values are different, the identity does not match the current customer. Follow this [this instruction](#if-the-identity-does-not-match-the-current-customer). #### If the identity matches the current customer 1. 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](#generating-json-web-tokens-jwt). **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](/developers/web/uuids#generating-uuidv5). 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](#generating-json-web-tokens-jwt). 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)
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
   }
The token lifetime cannot be longer than 7 days.
1. Sign the token with the public and private keys. 2. Encode the token. 2. 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](/developers/web/methods-reference#authentication-by-json-web-token-jwt). **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](#if-an-identity-hash-does-not-exist) - [The identity hash matched the current customer](#if-the-identity-matches-the-current-customer) - [The identity hash did not match the current customer](#if-the-identity-does-not-match-the-current-customer)