SSO integration for SaaS partners

The Qlik Application Automation for OEM front-end for end-customers of SaaS companies can be embedded inside the UI of your own SaaS platform as a white-labeled integration Hub.

SSO (single-sign on) can be implemented to offer a seamless integration to users of the SaaS platform.

SSO link to Hub

You (the SaaS partner) can add e.g. a link My integrations inside your platform, which opens your white-labeled front-end ofQlik Application Automation for OEM, e.g. in an iframe or popup. Inside the URL you can add SSO information so that the user is automatically logged in, and does not need separate credentials forQlik Application Automation for OEM.

Qlik Application Automation for OEM offers 3 different SSO methods. Each method is described below:

• JWT (preferred method)
• Hash
• oAuth2

Example SSO link using a JWT:

https://saaspartner.admin.[ca|us|au].blendr.io/sso?jwt=xxx

Example SSO link using a hash:

https://saaspartner.admin.[ca|us|au].blendr.io/sso?accountid=123&userid=456&timestamp=xxx&hash=xxx&...

Example SSO link using oAuth2:

https://saaspartner.admin.[ca|us|au].blendr.io/sso

Replace "saaspartner" in the above URL's with the correct subdomain of your white-label Qlik Application Automation for OEM instance.

Make sure to use the correct region in the URL, e.g. saaspartner.admin.blendr.io for Europe (default, no region specified in URL), and e.g. saaspartner.ca.admin.blendr.io for Canada.

SSO integration methods

The three SSO integration methods are explained in detail below.

SSO using a JWT

Build a JWT (JSON web token) using your favorite library. Use your SaaS Partner API key as shared secret to encrypt the JWT. Use HS256 as the signing algorithm.

Add all the SSO parameters as claims in the JWT payload. Example:

{
  "iat": 1565706663, // required (issued at)
  "exp": 1597414609, // required (expires at)
  "nbf": 1565706663, // optional (not valid before)
  "account": {
    "external_id": "123", // required
    "name": "ACME" //optional
  },
  "user": { //optional
    "external_id": "123",
    "name": "username",
    "email": "useremail",
    "locale": "fr-FR" //supported values: en-GB, it-IT, nl-NL, fr-FR, fr-BE, nl-BE
  },
  "datasource": { //optional, credentials for this account to SaaS partner API
    "datasource-param-1": "value-1", //e.g. "api_key": "xxx"
    "datasource-param-2": "value-2"
  },
  "inputs": { //optional
    "phonebook_id": "123", //top inputs for setup/settings flow of automations
    "template_prevent_duplicates": true, //optional, only for /sso/templates/{guid}/install link
  },
  "embed": {
    "mode": "redirect|event", //choose between a redirect or listening to events in the parent
    "target": "parent|current", //only for mode=redirect, where to redirect
    "redirect_url": "https://some-url.com/callback" //only for mode=redirect
  }
}

Available parameters for the JWT payload:

• iat: required, current timestamp in epoch (issued at)
• exp: required, expiry timestamp in epoch (expires at)
• nbf: optional, not valid before timestamp in epoch (not valid before)
• account.external_id: required, your unique identifier for an account (company)
• account.name: optional, name for the account
• user.external_id: optional, your unique identifier for a user within the above account
• user.name: optional, name of the user
• user.email: optional, user email (useful for e.g. alert emails sent out byQlik Application Automation for OEM)
• user.locale: optional, country and language of the account, e.g. en-GB, it-IT etc.
• datasource.paramname: optional, credentials of this account to the API of the SaaS partner (e.g. api_key)
• inputs.paramname (e.g. phonebook_id): optional, preset top inputs from a Setup/Settings flow in an automation.
  • The input parameter must be defined in a top input block of a Setup or Settings flow.
  • The input parameter name in the JWT should be identical to the input label in the Blend, and it should not contain spaces
  • If the input is in a Setup flow, it will be hidden for the user in the Setup Wizard.
  • If the input is in a Settings flow, it will be preset and visible to the user in the Setup & Settings Wizard.
• inputs.template_prevent_duplicates (optional, only for /sso/templates//install link): if set to true, no duplicate instance will be created for the same template. If this install URL is loaded a second time, the user will be redirected to the existing instance. Note that the input parameters are taken into account to determine duplicates. An instance with other input parameters will not be considered a duplicate. This allows installing e.g. an instance where project=A and a second instance where project=B.
• embed.mode: set to redirect if you want to redirect the user to your custom URL after a completed or failed install of a template and after completing a Settings flow; set to event if you want to listen to events in the parent on setup completed, failed and canceled (see below for more info on events).
• embed.target: only when mode=redirect; choose to redirect in the current iframe (current) or replace the parent webpage (parent).
• embed.redirect_url: only when mode=redirect; destination URL for the redirect. Following querystring parameter will be added to the URL to indicate the final status of the install: ?state=setup-complete|setup-failed|setup-canceled.

Finally, put the JWT in the querystring or send it as POST body. Example:

https://saaspartner.admin.[ca | us | au].blendr.io/sso?jwt=xxxxxxxxxxxxx

SSO using a hash

Parameters can be sent in the querystring using GET, but POST is preferred. Available parameters:

• accountid: required, your unique identifier for an account (company)
• accountname: optional, name for the account
• userid: optional, your unique identifier for a user within the above account
• username: optional, name of the user
• useremail: optional, user email (see remark below)
• locale: optional, country and language of the account, e.g. en-GB, it-IT etc.
• timestamp: required, current timestamp in epoch
• hash: required, see below
• credentials of this account to the API of the SaaS partner: optional, see below, e.g. apikey

The hash is calculated by applying SHA256 on the full URL encoded querystring (except the hash parameter), and using your API key as key:

Example in PHP

$hash = hash_hmac('sha256', 'url_encoded_querystring_without_hash', 'saaspartner_api_key')

Example in Java

hash = Hashing.hmacSha256( "saas_partner_api_key".getBytes(UTF_8) ).hashString( querystring.toString(), UTF_8 ).toString();

Example in Python

querystring_dict = {
    'accountid': 123,
    'accountname': 'John',
    'userid': 456,
    'timestamp': timestamp
}

querystring = urllib.parse.urlencode(querystring_dict)

hash = hmac.new("saaspartner_api_key".encode(), querystring.encode(), hashlib.sha256).hexdigest()

SSO using oAuth2

Instead of using a shared secret and sending all SSO parameters in the request, it is also possible to use oAuth2. In this case you can link to your white-label Qlik Application Automation for OEM instance with a simple SSO URL, and Qlik Application Automation for OEM will complete a silent oAuth flow to authenticate the user.

Please create a Qlik Application Automation for OEM app on your oAuth2 server, contact Qlik Application Automation for OEM support to have the oAuth2 flow enabled and provide the client_id and client_secret as well as the oAuth2 endpoints from your server to authorize, get tokens and refresh tokens.

SSO URL to open Qlik Application Automation for OEM in an iframe or popup from within your application (note: no parameters needed):

https://saaspartner.admin.[ca|us|au].blendr.io/sso

Qlik Application Automation for OEM will immediately redirect the user to your oAuth2 authorize URL with parameter prompt=none (and of course client_id, state etc.). This means the flow is silent, since the user is already logged in to your application. Your oAuth2 authorization screen will redirect to the oAuth redirect URL ofQlik Application Automation for OEM:

https://auth.blendr.io/callback

Qlik Application Automation for OEM will exchange the code from the call-back for an access_token, refresh_token and we also expect a JWT token that provides information on the current user (e.g. an id and name). Qlik Application Automation for OEM will store these credentials and make sure the user is automatically logged in. Further more, your application will already be linked as a datasource (Connector) inQlik Application Automation for OEM, so that when the user activates an integration, your application no longer needs to be connected.

Sending credentials as part of SSO

It is possible to send credentials as part of the SSO request, for example an API key of that user to access your API from out ofQlik Application Automation for OEM. If credentials are transmitted using SSO, the JWT method should be used (and not the hash method).

The result of sending credentials is that your platform will already be in status Connected inQlik Application Automation for OEM.

Send the credentials as extra parameters (e.g. apikey). The naming should be identical to the parameter names that are displayed in Qlik Application Automation for OEM when the user connects manually. Please note that spaces are replaced with an underscore and parameters are case sensitive. Contact Qlik Application Automation for OEM support to know the exact naming of the parameters of your connector.

Various SSO links

Depending on your Embedding scenario, you may want to link directly to a list of integrations or to an individual integrations, instead of using the general SSO link which links to the home screen of your Hub.

This paragraph describes the various SSO links that can be used, each with the same parameters as above (e.g. a JWT):

Link to your Hub homepage

https://saaspartner.admin.[ca|us|au].blendr.io/sso

Link to the list of available integrations

https://saaspartner.admin.[ca|us|au].blendr.io/sso/templates

Direct link to a template

Link to a template homepage. A template is an integration that a user can activate by going through the Setup Flow:

https://saaspartner.admin.[ca|us|au].blendr.io/sso/templates/{guid}

is the unique GUID of the template. You can use the SaaS Partner API to retrieve a template list.

Direct link that starts a template install

Link that starts the install of a template, this will start the Setup flow:

https://saaspartner.admin.[ca|us|au].blendr.io/sso/templates/{guid}/install

The following optional parameters can be used to customize the behaviour of the setup flow. These parameters can be added in the JWT or added to the querystring or in the POST body, depending on the SSO integration method that you use:

• param1=value1: send inputs to the Setup flow. This requires a top Inputs block in the Setup flow. Make sure to use the exact same names for the inputs.
• template_prevent_duplicates=true: if set to true, no duplicate instance will be created for the same template. If this install URL is loaded a second time, the user will be redirected to the existing instance. Note that the below input parameters are taken into account to determine duplicates. An instance with other input parameters will not be considered a duplicate. This allows installing e.g. an instance where project=A and a second instance where project=B.
• template_redirect_url=https://saasprovider.com/somepage: redirect the user after completion of the setup.

Direct link to an integration instance

Link to the homepage of an existing integration, meaning an instance of a template which is installed in a customer account. Use this link to allow access to the Settings of an active integration:

https://saaspartner.admin.[ca|us|au].blendr.io/sso/widgets/{guid}

is the unique GUID of the integration (automation). You can use the SaaS Partner API to retrieve a list of active integrations (automations) from one customer account.

Direct link to run an integration instance

Use this link to run an integration (automation) in a customer account. Note that a new run (job) will be started on each load of this URL. Use this link to allow customers to manually run an integration:

https://saaspartner.admin.[ca|us|au].blendr.io/sso/widgets/{guid}/run

Direct link to the Settings flow of an instance

https://saaspartner.admin.[ca|us|au].blendr.io/sso/widgets/{guid}/settings

Listening to events on setup complete, failed or canceled

You can listen to events in the parent webpage that embeds the Hub in order to take action if a setup was completed, failed or canceled by the user, e.g. to redirect to another page:

<iframe
  style="width:100%;height:100%"
  id ="sso-iframe"
  src="https://admin.blendr.io/sso/templates/{guid}/install?...">
</iframe>
<script>
window.addEventListener('message', (event) => {
  if (event.data.event === 'setup-complete') {
    console.log('The setup has completed')
  }
  if (event.data.event === 'setup-failed') {
    console.log('The setup failed')
  }
  if (event.data.event === 'setup-canceled') { //note: canceled with one L (not two)
    console.log('The setup was canceled by the user')
  }
}, false)
</script>

Please note that you have to enable these events with the option embed.mode="event" in the JWT, see above.

Similar events are sent out when a user completes the Settings flow of an existing instance: settings-complete and settings-failed. The event settings-canceled does not currently exist.