At the moment, Azure and Google are supported via Open ID Connect Protocol. It's possible to easily extend support to other authentication providers that work via Open ID Connect.
Once an authentication provider is configured, you'll see a corresponding button on the IDP login screen. Only login buttons for configured authentication providers are displayed.
To enable external authentication you'd need the following:
Follow "Setting up OAuth 2.0" section in https://developers.google.com/identity/protocols/OpenIDConnect#appsetup in order to create an app.
Set Redirect URL
to https://your-contiamo-platform.domain/auth/oauth/callbacks/google
. Note client_id
and client_secret
values that Google displayed to you, we'll need to put them into the configuration file later.
Follow https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app in order to create an app.
Follow https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-credentials-to-your-web-application in order to configure your app for a web access.
During the app configuration set Redirect URL
to https://your-contiamo-platform.domain/auth/oauth/callbacks/azure
(last path segment is different) and create a secret for your app. The secret value is shown only once, don't forget to take a note.
Write down Application (client) ID
, Application (tenant) ID
and the created secret value, we will need them later.
Enable email
claim https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims . Keep in mind, that if you're not using Outlook in Azure, your users won't have the email
claim which is required for the setup. As a fallback, it's possible (but not recommended) to use the preferred_username
claim instead for getting an email (see the "Configuration file" section). However, depending on your setup this claim might contain a non-email value which will result in error while login.
In order to configure external authentication providers, you need to create a JSON file with the configuration per organization. For example:
json{"<your-org-slug>": [{"kind": "azure","emailPattern": ".",*"parameters": {"clientId": "<here your client ID>","clientSecret": "<here you client secret>","discoveryEndpoint": "https://login.microsoftonline.com/<here your app tenant ID on Azure>/v2.0","scopes": ["openid","profile","email"],"claimMapping": {"email": "preferred_username"}}},{"kind": "google","emailPattern": "^[email protected]$",*"parameters": {"clientId": "<here your client ID>","clientSecret": "<here your client secret>","discoveryEndpoint": "https://accounts.google.com","scopes": ["openid","profile","email"]}}]}
Some of the values come from the "Create an OAuth 2.0 app" section but there are some additional parameters:
<your-org-slug>
is a "slug" name of your organization in Contiamo Platform (you can see it as the last segment of the URL path when you login).
emailPattern
is a regular expression that every user's email must match in order to be authenticated. .*
means any
, ^.*@contiamo.com$
means all emails in contiamo.com
domain.
parameters.discoveryEndpoint
is a provider-specific URL for the Open ID Connect protocol. Mind the presence of the tenant ID in the URL for Azure.
scopes
is a set of scopes that the provider requires in order to authenticate a user via Open ID Connect and get its email and name.
'claimMappingis a set of overrides for claim names used to extract the information about the user. By default,
emailclaim is used for getting an email and
nameclaim is used for getting the full name of the user. For reasons mentioned in the "Create an OAuth 2.0 app" section you might need to change
emailto
preferred_username` or depending on your configuration map the claims to something else.
This configuration file is strictly confidential and must be stored in a safe manner (e.g. as a Kubernetes secret) and must be never exposed to unauthorized staff.
The file is being read only on server startup, to apply a change you'd need to restart the server.
The final step is to enable the configuration using a server flag.
Set the --auth-providers-config-file
flag (empty string by default) to a full path to the configuration file from the previous section. If the file is missing required values or the path is wrong, the server will crash on startup and you'll see the error message in logs. This makes it easier to debug and troubleshoot the configuration problems before the users face them during login. It's safe to use an empty value which disables external authentication and runs the server normally.
At the moment external authentication providers are used only for user authentication, new users are not created in IDP. It means that the value from the email
claim must match the email of one of the users that already exist in IDP, otherwise users would see "This user is not allowed to login" error.
Invalid authentication state
— the state is an encoded string in the URL that an external authentication provider must return back to Contiamo after performing its checks on the user. The state is encrypted, signed and can expire. This error occurs when the state is either corrupted or expired which normally should not happen.
Failed to exchange the authorization code
— this error most likely occurs because of misconfiguration or when the external authentication provider is unavailable.
Failed to extract user's identity
— this error occurs when IDP is not able to verify and parse the identity token returned by the authentication provider. It should not happen if the authentication provider is running normally and the discovery URL is valid.
Failed to validate user's email
— this error occurs when it's not possible to extract an email or name of the user from the identity token. It can happen because of misconfiguration of your OAuth 2.0 app, you might want to check the granted scopes, enabled claims and claimMapping
in the IDP configuration file described in the "Configuration file" section.
This user is not allowed to login
— this error occurs when there is no existing user with such email in IDP or when the email didn't pass the emailPattern
check.
Failed to create user's session
— this error occurs when the IDP database is unavailable, the server is running in a faulty state.