Skip to main content

Secure token

The secure token provides to Qualifio customers a standardised and secured way to pass external information about members of the reward program in order to display them the member portal in a context where a classic SSO flow is not an option.

  • the portal is to be displayed within a native app
  • the database used to identify the customer base doesn’t include SSO flows.

In this flow, the customer is in charge of generating a secure JWT/JWE token, containing enough information to identify the participant. This means the customer has the responsibility to instantiate the portal URL adding a query param containing the JWT/JWE token, each time someone wants to login.

Secure token structure​

Headers​

{
  "alg": "RS256", // We support RSxxx/HSxxx/ESxxx with xxx = 256 | 384 | 512
  "typ": "JWT",
  "kid": "aKeyId" // Mandatory for JWKS. Not to be provided in other scenarios
}

Content​

{
  "sub": "1234", // Mandatory
  "exp": 1671100377, // Recommended
  "iat": 1671096777, // Optional
  "iss": "yourCompany", // A unique string identifying your company
  "profile": { // Mandatory
    "firstname": "John", // Optional
    "lastname": "Doe", // Optional
    "email": "test@test.com" // Mandatory
    "birthdate": "2000-12-24T12:00:00.000Z" // Optional
  },
  "custom": { // Optional
    "registeredUser": "", // Optional - Custom attributes applicable to the profile
  }

Usual fields​

sub: The sub is the unique identifier for the user (mandatory). Must be one of the identity of the user known in Qualifio and provided during member profile creation (email or customerId)

exp: The expiration date time for this token (recommended). If not provided token will be infinitely valid. Seconds since Unix epoch.

iat: The date time which the token was issued at (optional). Emission time of the token. Seconds since Unix epoch.

iss: The name of the token issuer (optional). Ideally a reverse notation of internet domain such as "com.google”.

profile: Data to prefill the member profile in Qualifio. Each key must be the technical name of a Qualifio variable.

custom: Data to be used in Qualifio, for instance to be used in an earning rule. Each key must be the technical name of a Qualifio variable.

Validation methods and algorithms​

Token signature​

Qualifio supports different methods for securing the JSON Web Signature (JWS) exchange functionality. Tokens can be validated using the following methods:

  • JWKS Endpoint
    • Choosing this adds a requirement on your side. You will need to add the kid field in the header of each JWS you generate. We need this field in order to know which key to use.
  • Public key (in PKCS#8 format - note that you can easily convert PKCS#1 to PKCS#8 using openssl with the following command: openssl rsa -RSAPublicKey_in -in <filename> -pubout)
    • RS256, RS384 or RS512
    • ES256, ES384 or ES512
  • Symmetric key
    • HS256, HS384 or HS512

Token encryption​

For most use cases, the JWS signature is enough to guarantee that a 3rd party hasn't modified a token or forged a new one during the transfer from the client to Qualifio. But, in some specific cases, customers might need to hide data contained in the token and therefore need encryption options (e.g. to hide a potential gift provided to Qualifio via the token).

To do so, we expect the encryption to be on the whole signed JWS described above. The following alg and enc are expected:

  • alg: dir
  • enc: A128GCM, A192GCM, A256GCM, A128CBC-HS256, A192CBC-HS384 or A256CBC-HS512

This means that we only decrypt with a shared secret. We will store this shared secret as well in order to decrypt, and then use the configuration of the "classic JWS" to decode and verify the signature.

In order to build your JWE, you can make use of our crypto API decribed in the following documentation: Crypto API.

Lastly, you might ask yourself why we ask to have a JWS within a JWE. This ensures, in the case of asymmetric signature algorithms, that the information is hidden to the end user, and that us, Qualifio, cannot forge new tokens (thanks to the public/private key pair).

Retrieve information passed via the secure token​

You can retrieve the information sent via the secure token by using the Qualifio webhooks. All information passed via the secure token are located in the profile object of the webhook structure. Our webhooks are described in the following documentation : webhooks.

This connection allow you to reconcile the information and make use of it in an external application after certain events; for instance, when members earn points .

Additional ressources​