Skip to main content

Secure token

The idea behind the token flow functionality is to provide to Qualifio customers a standardized and secured way to pass external information to a Qualifio campaign, at its launch.

This external information is shared through a JWS/JWE token.

Secure token structure​

Headers​

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "aKeyId" // Mandatory for JWKS. Useless for others signature methods
}

Content​

{
  "sub": "1234", // Mandatory
  "exp": 112421541, // Recommended
    "iat": 12214214,
  "iss": "yourCompany",
  "campaignId": "", // Mandatory
  "limit": { // Optional
    "nb": 1,
    "canPlay": true / false // sub can participate or not
  },
  "gift": { // Optional
   // Information about the prize associated with winner status//
            "label": "",
            "cw": true / false // sub can win or not
  },
  "custom": { // Optional
        // Custom data provided by the client
  },
    "form": { // Optional
        // Data to prefill the form where each key must be a Qualifio variable:
        // - mapping variable
        // - crm variable
    },
    "optin": { // Optional
        // Data to prefill optins where each key must be a Qualifio variable:
        // - mapping variable
    }
}

Usual fields​

sub: The sub is the unique identifier for the user (mandatory)

exp: The expiration date time for this token (recommended)

nbf: The not before date time for this token the token will get rejected if the clock of servers are too much out of sync, we recommended to set this field a few minutes before the iat (recommended)

iat: The date time which the token was issued at (optional)

iss: The name of the token issuer (optional)

Qualifio mandatory field​

campaignId: The technical ID of the campaign in Qualifio, used to define for which campaign the limitation, the technical information and or gift has to be applied/used (String format)

Qualifio optional fields - Functionalities​

Access limitation​

limit: The object containing information about custom limitation. Customer can provide any of the two following keys, or both of them, but at least one (canPlay)

  • nb: The number of participations allowed for a sub
  • canPlay: The flag indicating if the user can play or not (Boolean format)
    • Always mandatory (except when specifying the "nb"), even when only used to pass technical information via the token.

If canPlay and nb are both provided in the token, the rules are the followings:

  • If canPlay is true, nb is checked and used as limitation information by Qualifio
  • If canPlay is false, the user can't participate and nb isn't checked by Qualifio
 "limit": { // Optional
    "nb": 1, // number of time sub can participate
    "canPlay": true / false // sub can participate
  },

Winner and gift definition​

gift: The object containing information related to the prize/winner status

  • label: The name of the gift, display to the participant during the campaign (welcome screen and exit screen) and added to the webhook payload or custom push. This represents the gift actually won by the participant (mandatory)
  • cw: The flag indicating if the user can win or not (Boolean format: true/false)
    • The value true is not mandatory, as long as (1) the label is filled in and (2) there is a placeholder available in the campaign. In this case, the gift will be granted during the participation
    • The value false is mandatory when the participation is not a winning one and the label is filled in.
"gift": { // Optional
    "label": "", // Information about the prize associated with winner status
    "cw": {true || false} // sub can win
},

Pre-filling​

Form​

Data to prefill the form where each key must be the technical name of Qualifio variable (Mapping or CRM variables)

"form": { // Optional
    "myVariableName":"Value1"
}

For the checkbox and drop down fields, the value is not the label displayed in the form but it must be exactly the same as the value put behind the field. The value is case sensitive.

Optins​

Data to prefill the optin where each key must be the technical name of Qualifio variable (Mapping variables)

"optin": { // Optional
    "myOptinVariable":((0|1) | ("1"|"0") | (true|false) | ("on"|"off"))
}

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 described 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 Webhook 2.0. This connection allow you to reconcile the information and make use of it in an external application after a campaign participation. All information passed via the secure token are located in the metadata object of the webhook structure, within the securetoken child objet.

Integrate the secure token in a Qualifio campaign​

The secure token can be added to your campaign by using the campaign minisite link, the webview link of by integrating the campaign via a JS tag.

https://qualifio-testing.qualifioapp.com/20/E7A93D81-7378-42EC-9C65-784684888D51/v1.cfm?id=E7A93D81-7378-42EC-9C65-784684888D51&qual_token={YOUR_SECURE_TOKEN}

JS Tag​

<div id="qualifio_insert_place_896863" class="qualifio_iframe_wrapper"></div>
<script type="text/javascript">
(function(b,o,n,u,s){var a,t;a=b.createElement(u);a.async=1;a.src=s;t=b.getElementsByTagName(u)[0];t.parentNode.insertBefore(a,t);o[n]=o[n]||[]}) (document,window,'_qual_async','script','//qualifio-testing.qualifioapp.com/kit/qualp.2.min.js');
_qual_async.push(['createIframe', 'qualifio_insert_place_896863', 'qualifio-testing.qualifioapp.com', '20', 'E7A93D81-7378-42EC-9C65-784684888D51', '100%', '1200', 'qual_token={YOUR_SECURE_TOKEN}', '', '', 'max-width:810px;margin:0 auto;']);
</script>
https://qualifio-testing.qualifioapp.com/quiz/902139_963/Oauth2-Healthcheck.html?qual_token={YOUR_SECURE_TOKEN}

Additional ressources​