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.

Configuration

To enable external authentication you'd need the following:

Create an OAuth 2.0 app

For Google:

1. Follow "Setting up OAuth 2.0" section in https://developers.google.com/identity/protocols/OpenIDConnect#appsetup in order to create an app.

2. 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.

For Azure:

1. Follow https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app in order to create an app.

2. 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.

3. 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.

4. Write down Application (client) ID, Application (tenant) ID and the created secret value, we will need them later.

5. 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.

For either app make sure you have openid, profile and email scopes granted to the app.

Configuration file

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": "^.@contiamo.com$",*
"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 andnameclaim 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 changeemailtopreferred_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.

Server flag

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.

Authentication without user provisioning

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.

List of possible errors during authentication

• 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.