T.V
- In Qualifio, secure tokens were introduced as an integration that allows you to securely transmit information and identify participants. In this support article, we will find out information about secure tokens and review how to use them with Qualifio.
What does secure token actually mean?
The idea behind the secure token feature is to provide a standardised and secure way of passing external information to a Qualifio campaign.
From a technical perspective, external information is shared through a signed JSON Web Token (JWS) you generate following the standard structure defined by Qualifio.
The secure token can either be added as a parameter in the URL of the campaign, or part of its page (JavaScript). When the campaign gets loaded, the token and its content are retrieved and used by Qualifio.
A JWT is not usually encrypted, just signed (JWS). By ensuring that each request is accompanied by a signed token, we can validate the token and only then serve the campaign. If you need to encrypt the JWS, there’s a dedicated section for that.
The secure token is the recommended method for sending external information to a Qualifio campaign. You generate secure tokens with an expiration time based on your own security requirements.
Generate the secure token
First of all, you need to generate a secure token for each participation and share it with Qualifio. The secure token will be required when the page loads.
The token comprises three different sections, separated from each other by a dot character:
header.payload.signature
In this section, we will focus on the payload. It contains a series of statements (“claims”, which are basically name/value pairs) about an entity (the user).
In accordance with RFC-7519, here is what the payload of the JWT received by Qualifio should look like:
{
“sub”: “298776628”,
“iat”: 1619102989,
“exp”: 1619101489 ,
“iss”: “ABC Company”,
“campaignId”: "123456"
}
Note: You have the responsibility to share all necessary information. Need help? We explain this below.
JSON Web Token structure
The JWS contains statements (“claims”) about an entity (the user). Let’s break down the different parts:
Standard claims
Qualifio requires the following claim fields. They may appear in any order.
sub (subject)
The sub represents the participant’s unique identifier on your side, like their loyalty card number, a user ID or anything else allowing identification of the participant. This claim is required.
iat (issued at)
The iat identifies the time at which the token was issued. Its value must be a numeric date (timestamp). This claim is optional.
exp (expiration time)
The exp claim identifies the expiration time on or after which the JWT must not be accepted for processing. Again, the value must be a numeric date (timestamp). This claim is optional but it is highly recommended to set it for security reasons.
iss (issuer)
The iss claim identifies who issued the token. This claim is optional.
campaignId
This piece of information represents the unique ID of the campaign in which the token is used. This claim is required. Find your campaign ID
If you’re having any issues using this library, please create a support request.
Additional claims
Depending on your use case, you can provide additional claims to include in the token payload. When used by Qualifio, these optional claims can serve different purposes. For more information, see
Use the secure token in Qualifio
Once the secure token is generated, you can use it in Qualifio to limit participations, for instance.
Note: The secure token feature isn’t automatically enabled for your account. If this is your first time using this integration, you will have to enable it and set it up – or contact your account Admin so they can do so. You will only need to do this once.
Step 1: First, log in to your account and go to the Settings tab > Integrations > Secure token and then activate it.
Step 2: Click Configure.
Step 3: From the drop-down list, select a token validation method:
Qualifio supports different methods for securing the JWS. Tokens can be validated using the following methods:
- With the JWKS endpoint method, you expose a read-only endpoint that allows us to retrieve the secret used to sign the token (based on the key id (kid) header claim).
- Public key using algorithms
- RS256, RS384, RS512;
- or ES256, ES384, ES512.
- Symmetric key using the HMAC algorithm (with JOSE alg identifiers HS256, HS384 or HS512).
Step 4: Enter your endpoint or key in the corresponding field.
Step 5: When your configuration looks the way you want it, click Save.
Share the token with Qualifio
You should be able to share the token with Qualifio on page load. This can be done either by passing the JWT in the URL or by sharing it via JavaScript.
Pass the token as part of the webview URL this way:
https://interact.qualifioapp.com/20/.../v1.cfm?id=12345678&qual_token=yourToken
or as part of the minisite URL, this way:
https://interact.qualifioapp.com/xmas?qual_token=yourToken
or in the JavaScript iframe that is added to your site:
<div id="qualifio_insert_place_123456" 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','//interact.qualifioapp.com/kit/qualp.2.min.js');
_qual_async.push(['createIframe', 'qualifio_insert_place_123456', 'interact.qualifioapp.com', '20', 'A1B23C45-6789-01DE-2F34-567890123G45', '100%', '1200', 'qual_token=yourToken', '', '', 'max-width:810px;margin:0 auto;']);
</script>
Common questions about Qualifio secure tokens
How secure is the token? Should it be encrypted?
Given the sensitivity of the data stored in Qualifio, security is always on our minds.
JWTs can be either signed (a JWS), encrypted (a JWE) or both. A signature allows a JWT to be protected against modifications and to have strong certainty of the identity of the issuer of the token. Encryption, on the other hand, makes sure the content of the JWS is confidential and only readable by Qualifio.
Although signed tokens are usually sufficient to verify the integrity of the claims, you might want to encrypt JWS to also provide secrecy between parties (e.g. to hide a potential prize passed to Qualifio via the token).
If the token is encrypted, you will have to fill this field: