Blendr.io for Developers

Blendr.io for Developers

Welcome to the Blendr.io documentation for developers.

SSO integration for SaaS partners

The Blendr.io platform is available as a white-labeled embedded platform for SaaS partners, called the SaaS Partner "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 instance 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.

Example SSO link:

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

Replace 'saaspartner' in the above URL with the correct subdomain of your whitelabel Blendr.io instance (and remove the spaces, that were added for readability).

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 "saaspartner.ca.admin.blendr.io" for Canada.

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 (useful for e.g. alert emails sent out by Blendr.io)
  • timestamp: required, current timestamp in epoch
  • hash: required, see below
  • optional: credentials of this account to the API of the SaaS partner (e.g. "apikey", see below)
    Parameters can be sent in the querystring using GET, but POST is preferred.

Calculation of hash

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()

Sending credentials as part of SSO

It is possible to send credentials as part of the SSO request, e.g. an API key of that user to access your API from out of Blendr.io. If credentials are transmitted using SSO, the full request should be encrypted by using a JWT (JSON Web tokens, see below).

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.

Direct SSO link to one specific integration

Depending on your embedding scenario, you may want to link directly to individual integrations, instead of using the above general SSO link (which links to the home screen of your Hub).

Following SSO links can be used to link directly to one integration (with the same parameters as above):

Link to a "template" (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.

Link to an existing integration (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 account.

SSO integration with JWT (JSON web tokens)

Build a JWT using your favorite library. Use your SaaS Partner API key as shared secret to encrypt the JWT.

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

{
  "accountid": 123,
  "accountname": "ACME",
  "iat": 1565706663,
  "api_key": "abcde12345"
}

Available parameters for the JWT payload:

  • 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 (useful for e.g. alert emails sent out by Blendr.io)
  • iat: required, current timestamp in epoch ("issued at")
  • optional: credentials of this account to the API of the SaaS partner (e.g. "api_key")

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 integration with 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.

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.