In this article we will first take a deep dive into how Integrations, Suborganizations and SSO users all come together to control access to your dashboards and datasets.

Then we will look at some examples examples of how to set up Integrations, Suborganizations and SSO users for different scales and use cases, and the pros and cons of each.

What are Integrations?

Integrations in Luzmo are a way of encapsulating access rights for a group of data sets and dashboards. When creating an Integration, access rights for each shared dashboard and dataset are specified, and dataset filters are defined.

There are several ways to structure Integrations, each with their pros and cons. From a maintenance and scalability point of view, we recommend choosing the most simple solution that fits your needs, i.e. the solution requiring the least amount of resources to manage.

What are Groups and Suborganizations?

Groups in Luzmo are used to organize users and their access to datasets as well as dashboards. When datasets and dashboards are shared with a group, you can set an appropriate access right and optionally specify some dataset filter(s), similar to sharing them with an Integration. Users added or removed from the group will gain or lose access to the group’s accessible datasets and dashboards.

Suborganizations in Luzmo are like silos for your clients. By assigning a client to a Suborganization, you ensure that they can only see resources from that suborganization (e.g. users, comments, custom datasets, etc.). Each time a new Suborganization is specified in the SSO authorization request, a new "suborganization group" is automatically created with the same name. Based on the specified username property, a SSO user will be automatically created and added to this group. Dashboards and datasets can then be shared and managed like with any other group, facilitating more granular access to specific resources.

How do Integrations, groups and SSO Authorization Tokens work together?

When a SSO token is generated for a user, an Integration and Suborganization must be specified via the integration_id and suborganization property. The bootstrapped SSO user inherits the access rights and filters set on either the Integration, (suborganization) group, or user access itself. If the user has access to a dashboard or dataset via more than one way (Integration, group or user share), the following rules are used:

• The highest level rights (can view, can use, can edit, owner) among all given are applied
• The filters of a specific share are respected in following order of priority: User > (suborganization) group > Integration.

For example a dataset is accessible:

• with 'can use' rights via the Integration and a filter client_id = 1 defined there
• with 'can view' rights via a share to the user and no filter defined on that share

The SSO user will have 'can use' rights (the highest of the two) and no dataset filter (User share is prioritized over Integration).

All filters from the dashboard (interactivity filters, dashboard filters, chart filters) are merged with the access filter(s) using "AND" relations.

Getting the accessible dashboards

A complete list of dashboards and datasets available to an individual user can be found in the front end of your application by calling the getAccessableDashboards method.

You can generate a similar list by using user’s SSO token and the following curl code:

curl https://api.luzmo.com/0.1.0/securable -H "Content-Type: application/json" -d @- << EOF
{
    "action": "get",
    "version": "0.1.0",
    "key": "{{LUZMO_SSO_KEY}}",
    "token": "{{LUZMO_SSO_TOKEN}}",
    "find": {
        "where": { "type": "dashboard", "derived": false },
        "attributes": ["id", "name", "modified_at"],
        "order": [["modified_at", "desc"]],
        "include": [
            { "model": "Tag", "attributes": ["tag"] },
            { "model": "User", "attributes": ["id", "name"] },
            { "model": "Group", "attributes": ["id", "name", "public"] },
            { "model": "Integration", "attributes": ["id", "name"] }
        ]
    }
}
EOF

Integration Examples

As mentioned above, we recommend to set up your access granularity controls with the least amount of resources to manage, as this will be the most scalable and maintenance friendly way. Below we dive into some example recommended setups per use case.

Types of dashboards

When talking about dashboards, it’s useful to separate them into a few categories:

• Organization dashboards are dashboards that are relevant to all of your clients.
• Role dashboards are dashboards that many clients might need in the same role (e.g. A marketing manager at one client will need the same dashboards as a marketing manager at another client).
• Client dashboards are dashboards that should only be shown to one or more clients.
• User dashboards are dashboards that should only be shown to one or more users.

Organization level dashboards only - A single Integration solution

The most simple setup to achieve is using the same Organizational dashboards for all of their clients. Your use case may look like this:

With only Organization level dashboards, i.e. all dashboards are relevant to all of your clients, a single Integration is an excellent solution that can be easily set up and maintained.

• Pros:
  • Low maintenance - only one Integration to maintain.
  • Everything can be managed from the Integrations tab in Luzmo where you have a clear overview of all accessible dashboards.
• Cons:
  • Any clients or users needing Role, Client or User dashboards will need to have them shared with their Suborganization, Group or User, as appropriate (See Complex Scenarios, Option 3).

Multiple Integration Solutions

In more varied use cases, multiple Integrations are a better solution to enable finer granularity to manage dashboard/dataset access. Multiple Integration patterns can be set up in many different ways and are best illustrated by examples:

Organization & Client dashboards

A slightly more granular control access to your dashboards, e.g. based on the client’s license in your application, may look like this:

The Overview dashboard is an Organization dashboard (it gets shared with all clients) and Specifics is a Client dashboard (it gets shared with one or more clients). In this case, it makes the most sense to create two Integrations which we will call Basic and Premium.

This is useful if your clients all fall under standard licensing scenarios.

• Pros:
  • Low maintenance - only need to add new Integrations when creating new licensing options.
  • Everything can be managed from the Integrations tab in Luzmo where you have a clear overview of all accessible dashboards.
• Cons:
  • Any clients or users needing Role, Client or User dashboards will need to have them shared with their Suborganization, Group or User, as appropriate (See Complex Scenarios, Option 3).

Role dashboards

Similarly, you might want to support different roles that are common across many of your clients. For example, your clients may all be in sales & marketing, and their users and executives each have their specific dashboarding needs:

In this case, the Company Overview dashboard is an Organization level dashboard. We have no Client level dashboards, as different users within the same client need to see different dashboards based on their role. All of the other dashboards are Role dashboards. To achieve this setup, we will use three Integrations:

This is useful if you have relatively few clients with many Client or Role-specific dashboards.

• Pros:
  • Everything can be managed from the Integrations tab in Luzmo where you have a clear overview of all accessible dashboards.
• Cons:
  • Any clients or users needing Client or User dashboards will need to have them shared with their Suborganization, Group or User, as appropriate (See Complex Scenarios, Option 3).

Complex Scenarios

It might be that your access use-case is more complex to handle compared to the ones mentioned above. For example:

In this case, we have no Organization level dashboards, and the rest are a mixture of Client and Role level dashboards. To support this setup, there are some options:

Option 1: One Integration per unique Role

Looking at our example above, we can see that this scenario would almost be a perfect fit for a Role dashboard setup, the only problem is Client 2 needs custom dashboards for their sales role.

First, let’s ignore the variations. In that case, we only have Role level dashboards, and we can create three Integrations to serve those roles (see Role dashboards above).

Next, we can look at any variations from these roles and create a new Integration for each variation. In the example above we will need 4 Integrations; three for the common roles, and one variation:

• Pros:
  • Everything can be managed from the Integrations tab in Luzmo where you have a clear overview of all accessible dashboards.
• Cons:
  • High maintenance - as your number of unique roles increase, your number of Integrations increases 1:1

Option 2: Integrations with commonly shared dashboards, and Suborganization dashboards for customization

In this option we will only create an Integration for each of the most commonly shared dashboards. If a client needs additional dashboards they are shared with that client's specific suborganization group. These shared dashboards could be organized by license, role or client, whichever makes the most sense for your use case.

In the example above it makes the most sense to create Integrations by roles, so we will need 3 Integrations:

Custom Sales Dashboard and any dependent datasets will then be shared with the Client 2 suborganization. A SSO user generated using the Sales Integration and the Client 2 suborganization would therefore have access to the Sales Overview, Sales by Region (from the Integration) and Custom Sales Dashboard (from the suborganization).

• Pros:
  • Integrations are created based on the most common shared dashboards, which keeps the number of Integrations lower for ease of maintenance.
  • Very efficient if most clients require access to some shared dashboards and some custom dashboards.
• Cons:
  • You cannot easily see in the Luzmo UI what dashboards and datasets are available to a specific user, and you have to manage sharing access to dashboards and datasets (and their appropriate filters) by suborganization or group.

Option 3: One Integration + suborganizations and groups

In this option, we will use a single Integration that only contains Organization level dashboards. In general, Client dashboards will be shared by suborganization, and Role dashboards will be shared by group. We will need only one Integration:

• Pros:
  • Low maintenance - only ever have one Integration
• Cons:
  • You cannot easily see in the Luzmo UI what dashboards and datasets are available to a specific user, and you have to manage sharing access to dashboards and datasets (and their appropriate filters) by suborganization or group.

Note that in the simple example above, users from different clients are within the same group: this means that those users can e.g. share their dashboards with each other (i.e. possibly accross your suborganizations). To avoid this behavior, you could e.g. create one group per role-client combination!

Integrations per environment.

In order to track embedded dashboards from development to production, it may be advantageous to organize your Integrations by environment.

For example, this allows dashboards and datasets to be created and tested in a development environment Integration first, then tested and evaluated in a QA environment Integration before being shared with a production facing Integration.

The pros and cons of using one or multiple Integrations still apply - now they will need to be evaluated on a per-environment basis. Often a single Integration may be sufficient for development and QA, with a more sophisticated multiple Integration solution necessary for production.

Next to controlling which dashboard shows in which environment, there is also the publishing functionality with which you can control which version of that dashboard shows in which environment. You can read all about this in this article.

If you are interested to know how you can make sure that user-generated dashboards fit seamlessly in your application, the the next article will help out!