How to :: use authentification providers

External identity providers (called IdP in this doc) can be configured for your instance. To do so please contact Toucan Toco Support Team.

Toucan Toco supports three authentication means

  • Local Authentication: connect with username/password
  • SAML v2: We support the SAMLv2 authentication protocol.
  • OpenID Connect: We also support the OpenID Connect authentication protocol.

All available types of IdP can be used together and multiple times.

Common properties

  • id: a unique ID for the provider, used to build redirect and metadata urls (we refer to this as provider id in the examples below)
  • name: display name
  • icon: name of an icon representing the provider (we use font awesome)
  • discrete: (boolean) when set to true the provider will be available below other options as a simple html link

SAML2 configuration

In roder to implement SAML2 for your instance Toucan Toco needs information from your IdP called IdP configuration:

The metadata file to use when configuring your IdP will now be available here:

https://<backend url>/auth/provider/<provider id>/metadata

IdP configuration

In order to configure the IdP part, we need to set the values of:

  • entityId
  • singleSignOnService url
  • singleSignOnService binding
  • x509 certificate

These values can be found in the metadata XML of your Identity Provider.

Other settings

  • user_provisioning: (bool) when set to false, users won’t be able to log in unless they already exist in Toucan Toco’s internal database. Default is true, which means that they will be created on-the-fly.
  • mapping:
  • nameId: (string) filter used to override the username of the connected user with a value found in the metadata sent by the IdP.
  • userTemplate: allows to override default rights of users who connect via the SSO (applied each time they log in)
  • privileges:
    • SmallAppName: an arrays of privileges (i.e. ['view'] or ['contribute']). By default, users won’t have any privilege (they will see an empty store).


Why do I get a “redirect_uri_mismatch” error after login?

→ most probably because you didn’t allow the URL in your app configuration on the identity provider

Do I need to care about the “authorized_origins” parameter on my identity provider server?

→ No. This parameter is only useful for full JavaScript applications.

OpenID Connect

A lot of services act as OpenID Connect identity providers (Google, Yahoo, Azure, etc.). In order to use one of them, you’ll typically have to follow the following setup steps:

  • on the identity provider server:
    • register your ToucanToco app (e.g. If the registration is successful, you should be given a couple client_id, client_secret that will be used as credentials for you app,
    • configure your application permissions (e.g. what kind of information about an user your application will be allowed to ask for),
    • you’ll generally have to authorize the URL that the identity provider will call after a successful login. The exact name of the configuration field you’ll have to set will vary depending on your identity provider: for instance, on auth0, it’s called Allowed Callback URLs, on google, it’s called Allowed redirect URIs. The URL you have to set is always https://<backend-hostname>/auth/provider/<auth-provider-id>/auth_callback, for instance:
  • on the toucantoco application Contact Toucan Toco support team :
    • and provide the identity provider information, as generally provided trough a specific endpoint (e.g. Those endpoints are sometimes discoverable automatically but we don’t support this feature for now,and your app credentials
    • Provide your app’s credentials,
    • Provide the front-end’s URL, the backend will need it to send you back to your application after the authenication process is over,
    • Provide the required scopes (i.e. what information the Toucan will ask for). The default is ['openid', 'email'] if you don’t specify it but you can ask for anything the identity provider claims to support. Unsupported scopes will eventually be ignored anyway.
    • optionally, we can customize the userinfo request. The default behavior is to perform a POST request and send the access_token in the message body. We can override this by specifying a userInfoRequest property and specify its method, behavior and headers subproperties. For instance: javascript   'userInfoRequest': { 'method': 'GET', 'behavior': {   'use_authorization_header': True, }, 'headers': {   'X-Whatever': 'hola',   } The python library that we use will parse and check the response sent by the IdP. If the response doesn’t strictly conform with the expected openid schema, the authentication will fail. For instance, it will fail if the email_verified property is returned as a string (e.g "true") instead of a boolean (e.g. true). Since you probably won’t be able to change your IdP’s behavior, you can tweak the list of properties to check using the user_info_schema.ignore (blacklist-mode) or user_info_schema.validate_only (whitelist-mode). For example, the following settings will ignore email_verified validation: "userInfoRequest": { "user_info_schema": {   "ignore": ["email_verified"] }   }

After Toucan Toco support team updated the instance settings, the new auth provider will be listed on https://api-[name-of-toucan-branch] and the Service Provider’s metadata are available to download at https://api-[name-of-toucan-branch][name-of-your-idp].

User rights and permissions

User rights and permissions can be entirely controlled by a third party SSO IdP. This is configured first at the instance level (in instance settings) for users rights (control access to small app and assign groups) ; and second at each small app level for permissions (control access to reports and dashboard, or at row level).

User rights: authentication provider rules

When a user logs in using a SSO mechanism Toucan Toco can process it in order to give him relevant user rights and groups, based on the attributes sent by the IdP.

This can be configured thanks to “Authentication Provider Rules”, located at the bottom of the “Settings” page of your instance.

These rules are expressed as a function that take a User object as input, and return a User object to be created or modified.

The relevant properties of the User object are:

  • attributes an object storing the user’s attributes as sent by the IdP
  • groups an array of strings for each of the user’s groups
  • privileges.smallApp which stores an object where each property is a small app id and the values are arrays of privileges i.e. ['view'] or ['contribute']

If you are interested in setting up the operation described above. Please contact Toucan Toco support.

Customizing user identifiers

It so happens that identity providers don’t return a user identifier suitable for Toucan. For instance, it may be an internal ID that we need to map onto a valid Toucan account (i.e. an email address).

This can be handled by defining a compute_username function in the Authentication Provider Rules module. This function takes the user identifier as returned by the IdP and returns the corresponding user in the Toucan database. In the SAML case, if a custom nameId mapping is defined, it is applied first and the result of this mapping is then passed to the compute_username function.

If your IdP cannot send users emails to be used as usernames. Please contact the Toucan Toco support team to implement this feature.