Introduction
Canary Console users can be assigned permissions such as their access levels for Flocks, and whether a user is a Global Admin. By default these permissions are managed directly on the Console under the Flock or Global Settings.
Customers whose Consoles rely on SAML for Single Sign-On can instead choose to manage user permissions via the SAML IdP. In this scenario, the single source of truth for user accounts and user permissions is the SAML IdP, which simplifies Canary Console user management.
This page describes how to enable SAML IdP-managed permissions for your Console. It requires changes at your SAML IdP configuration only (you won't need to make any changes on your Canary Console.)
Quick Sketch of the IdP configuration
The Canary Console will look for SAML attribute statements to manage user permissions. To enable this feature, you will log in to your SAML IdP and edit the configuration there for the Canary Console application. You'll modify the configuration to include SAML attribute statements in the login request (sometimes you might see references to "claims" instead of "attributes", IdPs are not consistent with the naming.)
When the Canary Console sees the correctly formated SAML attributes in an authentication request, it will use them to configure the user's permissions at login time.
Setup Process
Add the following three SAML attribute statements to the users on the Thinkst Canary application on your IdP to manage user permissions from the IdP instead of on the Console. All three of these need to be present for IdP-managed permissions to work.
is_global_adminwatched_flocksmanaged_flocks
Global Admin
The is_global_admin attribute must have a string value of either false or true. If the value is true then the user will be assigned Global Admin permissions in the Canary Console.
Note: Users with is_global_admin set to true must still have empty watched_flocks and managed_flocks attributes.
Watched Flocks
The watched_flocks attribute is a string value that specifies which flocks the user will be able to watch (more info here).
The value must either be an empty string, or a CSV list of flock IDs (with no spaces).
Managed Flocks
The managed_flocks attribute is a string value that specifies which flocks the user will be able to manage (more info here).
The value must either be an empty string, or a CSV list of flock IDs (with no spaces).
Checking the permissions management source
The current permissions management source is shown in the SAML section on the Global Settings page on the Console. After the first user logged in via SAML with the three permissions attributes configured and the console switched to IdP-managed permissions, the "User permissions managed by" value should be "SAML IdP" as shown below.
Can these attributes be updated after creation?
The Console will process the attributes on each SAML login and update the user permissions if there are any changes (adding or revoking permissions as required).
Any changes to permissions attributes will therefore be reflected after the user's next login via SAML.
Instructions for particular SAML Identity Providers
Switching a Console to IdP-managed permissions
Once a user with the three valid attributes logs in via SAML, the Console will automatically switch over to using IdP-managed permissions for all SAML logins. This means that all subsequent SAML logins must include the three attributes, or those logins will fail. It's important to configure the attributes on all users at the same time.
Switching back to Console-managed permissions
If your Console has been switched to using IdP-managed permissions and you would like to switch back to managing user permissions on the Console our support team will gladly assist you.
Simply download the permissions snapshot file from the Console (in the SAML section on Global Settings as shown below) and attach it to your support request and we will restore your user permissions to the state they were in just before the Console switched to IdP-managed permissions.
Troubleshooting
If the attributes are incorrectly configured on the IdP, the user will be presented with an error when logging in through SAML. The different types of errors, as well as the instructions to fix them, are listed below.
Console uses IdP-managed permissions but user has no permissions attributes
The Console has been switched over to using IdP-managed permissions (by a user previously logging in with the three permissions attributes configured) but the user in question doesn't have any permissions attributes configured.
Fix: Add the three permissions attributes to the user on the SAML IdP.
Permissions attributes are missing
Some of the permissions attributes are present, but not all three.
Fix: Add the missing permissions attributes to the user on the SAML IdP.
Overlap between managed and watched Flocks
One or more Flock IDs appear in both the managed_flocks attribute and the watched_flocks attribute.
Fix: Ensure that each Flock ID only appears in one of these attributes.
Global Admin has Flock assignments
The user's is_global_admin attribute is true and there are Flock IDs in the managed_flocks or watched_flocks attributes.
Fix: Remove the Flock IDs from the managed_flocks and watched_flocks attributes and make them both empty strings.
Duplicate attribute
One or more of the attributes was included in the SAML response sent to the Console more than once.
Fix: Make sure that each attribute is only configured once on the IdP.
Invalid Flock ID format
One or more of the Flock IDs specified in the managed_flocks or watched_flocks attributes has an invalid format.
Fix: Make sure that all Flock IDs specified in the attributes are valid by copying them from the Console, or comparing them to the values on the Console.