Request a SSO token in your backend

In the previous articles, we showed you how to associate dashboards and (filtered) datasets with an Integration. To securely access an embedded Luzmo dashboard in your platform, you will first need to retrieve a SSO authorization token granting temporary access to a specific Integration containing the desired dashboard.
This request for a SSO authorization token should occur in your backend (server-side code). Within this request, you can specify the necessary properties to ensure a multi-tenant setup of your dashboards integration (all multi-tenant setups are discussed in this Academy article). Note the importance of specifying the role for your end-users when creating their SSO tokens: more information on that, below.
After successfully creating your Integration, you will be presented an overview of the necessary backend code in our supported SDK's (more on this below). Copying this code and filling in the necessary fields will make this step effortless!

Server-side SDK's

We provide SDK's for different backend libraries reduce the burden of having to code all the API calls yourself. All SDK's can be found here in our Developer documentation, and you can see the corresponding code examples by using the selectors on the top right of the Developer documentation page.

If we currently don't provide an SDK for your backend library, don't worry: Luzmo's API's all use REST calls with default HTTP verbs and JSON content, and so you should be able to write these calls yourself 😉

• Curl
• Node.js
• PHP
• Java
• .NET

SSO Authorization request

In its simplest form (i.e. not providing any properties for a multitenant dashboard setup) you should specify:

1. The type of the authorization you want to create: "sso", in this case.
2. The following properties are required when requesting a SSO authorization token:
   • username: identifies the end-user uniquely and immutably. This should correspond to eg. the primary key for the end-user on your end. If it changes, the end-user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform!
   • email, name: basic info on the end-user, to show eg. who is the dashboard author. The full name (i.e. first name and last name) is expected.
   • suborganization: each SSO token should be in a suborganization. The suborganization determines which other users they can see & interact with. It is required to avoid accidentally forgetting to set it which would cause all users to see each other! If you want totally isolated users, set it to the unique username. More info about suborganizations can be found here.
   • integration_id: the UUID of the Integration
   • role: "viewer". A planned feature is our embeddable dashboard editor, for which you can specify the role "designer" to grant a SSO user access to this!
3. The moment at which the SSO authorization should be invalidated, by filling the property expiry. You can either provide this as a specific timestamp or as an interval, e.g. "1 day" which will be translated to a specific timestamp by Luzmo (this translated timestamp will be available in the response from Luzmo). SSO tokens have a default maximum expiry date of 1 year enforced to promote better security practices, we recommend setting it to e.g. 1 day.
4. With the property inactivity_interval, you can specify an inactivity interval (e.g. "10 minutes") after which a SSO token should be prematurely invalidated if there has been no activity. We enforce a minimum inactivity interval of at least 2 minutes if specified, to avoid accidental invalidation for a dashboard that is still open, eg. when a heartbeat signal sent from the server is missed. It is however still optional to set an inactivity interval, although we do advise to specify it for security reasons.

There is no limit on the number of SSO tokens that you can request, and so we recommend requesting a SSO token each time the user performs an action in your platform that would require a SSO token (e.g. navigating to another embedded dashboard). This prevents end users running into errors because of tokens that expired due to inactivity!

Code example (Node.js)

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'sso',
  username: '12345678',
  suborganization: 'Burrito Co.',
  name: 'SSO user',
  email : 'sso_user@example.com',
  expiry: '24 hours',
  inactivity_interval: '10 minutes',
  integration_id: '<integration_id>',
  role: 'viewer'
});

promise.then(function(result){
  // return result.id and result.token to the client
})

As a result, you will receive a temporary SSO authorization token from Luzmo. This is a JSON object with an id/token combination:

{ 
  "type": "sso",
  "id": "< the authorization key >",
  "token": "< the authorization token >",
  "user_id": "< the SSO user id >," // This will stay the same for consecutive SSO authorization requests, 
                                    // and it is used on our end to manage user-specific content such as alerts
  ...
}

The second step is to use this SSO token to embed the dashboard in your frontend, which is explained in our next article.