Manage User Authentication

The Loyalty widget uses a JSON Web Token signed with an RS256 key pair to verify users. Your back end signs a token using a private key and a corresponding public key validates it. This ensures that only authorised users can access the loyalty widget.

Upload the Public Key

Generate an RSA public and private key pair. To upload the public key, go to the Authentication tab in the Loyalty Hub and do the following:

1. Click Add Key
2. Enter a description
3. Paste your public key and turn on the enabled toggle
4. Click Add Key

The public key is used to verify the authenticity of every token sent from your application.

📘

Generating an RSA Key Pair

The following example shows how to generate your RSA public and private key pair using OpenSSL:

1. Generate the private key
   Shell

   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.key

   
   
2. Extract the public key
   Shell

   openssl pkey -in private.key -pubout -out public.key

   
   

JWT Token and Payload

Every request the loyalty widget makes must include a signed JWT to identify the user and confirm their session is valid.

The JWT must be generated on your secure back end server using your Private Key. Once generated, your back end should pass the token to your front end, which then provides it to the Xtremepush SDK.

• Header: The header defines the algorithm and the type of token.
  • alg: This must be set to RS256.
  • typ: This must be set to JWT.
  • kid(optional): Identifies which public key to use to verify the token. If you have multiple public keys uploaded, this avoids checking the token against every key and matches the correct one directly. This option is recommended for production environments where you may rotate keys over time.
• Payload: The payload contains the specific user data required for the session.
  • sub(required): This represents the User ID of your user which is recorded in the User Profiles tab in Data Manager.
  • exp (required): Specifies the token expiration time as a Unix timestamp in seconds. This value determines how long the session is valid.

Example JWT Structure (Standard)

{
  "alg": "RS256",
  "typ": "JWT"
}
{
  "sub": "user_88421",
  "exp": 1741436048
}

Example JWT Structure with Key ID

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "primary"
}
{
  "sub": "user_88421",
  "exp": 1741436048
}

👍

Security Best Practices

• Private key: Never hardcode or expose your private key in frontend code, mobile applications, or version control. The private key grants access to generate tokens for any user. Always generate tokens on your secure back end server.
• Key rotation: Upload multiple public keys in the Authentication tab to support key rotation. Use the kid header field to identify which key signed each token.
• Token expiry: Set appropriate expiration times and implement token refresh logic to prevent session disruption.
• Testing: Use a JWT tool to decode and verify test tokens during development. Paste your public key in the verification section to validate signatures.

User Profile Mapping

When your user opens the loyalty widget, the platform uses the User ID from the token to identify their profile. This profile is then added to the All Users tab within the loyalty Hub with the same user ID.

To complete this mapping, you must finish the SDK configuration. The SDK setup is required to load the widget and pass the token.

📘

Users are only mapped to the All Users tab once you have made your widget publicly available.