Blendr.io knowledge base

SSO integration for SaaS partners

The Blendr.io 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.

🚧

Activate SSO

Please contact Blendr.io support, in order to activate SSO for your Hub. This must be done before you can start testing the SSO integration.

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 of Blendr.io, 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 for Blendr.io.

Blendr.io 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 whitelabel Blendr.io 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.

📘

User email

The parameter useremail is optional, and it does not have to be unique. If you would like to receive alert emails from failed Blends from all your end-customers, in one central mailbox, simply hardcode your email address as an SSO parameter (e.g. [email protected]).

SSO integration methods

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 Blends
    "template_prevent_duplicates": true, //optional, only for /sso/templates/{guid}/install link
    "template_redirect_url": "" //optional, only for /sso/templates/{guid}/install link
  }
}

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 by Blendr.io)
  • 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 a Blend.
    • 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/{guid}/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.
  • inputs.template_redirect_url (optional, only for /sso/templates/{guid}/install link): redirect the user after completion of the setup.

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 Blendr.io instance with a simple SSO URL, and Blendr.io will complete a "silent" oAuth flow to authenticate the user.

Please create a Blendr.io app on your oAuth2 server, contact Blendr.io 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 authorise, get tokens and refresh tokens.

SSO URL to open Blendr.io in an iframe or popup from within your application (note: no parameters needed):

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

Blendr.io will immediately redirect the user to your oAuth2 authorise 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 of Blendr.io:

https://auth.blendr.io/callback

Blendr.io 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). Blendr.io 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) in Blendr.io, 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 of Blendr.io. 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" in Blendr.io.

Send the credentials as extra parameters (e.g. "apikey"). The naming should be identical to the parameter names that are displayed in Blendr.io when the user connects manually. Please note that spaces are replaced with an underscore and parameters are case sensitive. Contact Blendr.io 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}

{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

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}

{guid} is the unique GUID of the integration (Blend). You can use the SaaS Partner API to retrieve a list of active integrations (Blends) from one customer account.

Direct link to run an integration instance

Use this link to run an integration (Blend) 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 "Setup complete" event

You can listen to a "setup complete" event in the parent webpage that embeds the Hub, in order to take action if a setup was completed 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 !')
  }
}, false)
</script>

Updated 9 days ago

SSO integration for SaaS partners


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.