Single Sign On (SSO) for Brightmetrics

Required Subscription: MiVC + Brightmetrics Enterprise, MiCC, Genesys

Required Permission Level for Setup: Company Admin

 

Setting up SSO login for Brightmetrics should be a simple setup process and we'll walk you through those steps here below using Azure AD as an example identity provider for OpenID Connect, and Google Workspace as an example identity provider for SAML.  Any provider that supports OpenID Connect (aka OIDC) or SAML 2.0 should work, although the terminology varies and the steps on the identity provider's side may be different.

 

OpenID Connect (OAuth2)

This example uses Microsoft Azure Active Directory.  In the screenshots the directory name is "Brightmetrics Azure" but in your environment it will show your directory name in the corresponding place.

 

Identity Provider

Step 1: First, the application must be created in your identity provider.  For Azure AD this means going to the Active Directory section of the Azure Portal, clicking on App Registrations, and clicking New registration:

Step 2: The name of the application is for your own reference, we will call it "Brightmetrics" here.  Since you are creating this application for your organizational use choose Single Tenant, and for Redirect URI enter https://auth.brightmetrics.com/oauthlogin.cshtml:

Step 3: With the application registered, click on Certificates & Secrets, and on the Client Secrets tab click "New client secret":

Step 4: In the pop-out dialog enter a name to identify the client secret and select the length of time for which it will be valid, then click Add:

Step 5: The client secret value will then be displayed.  Copy the secret value to a temporary location for later entering into the Brightmetrics SSO configuration.  Notepad, for example.

 

Brightmetrics

Step 1: Log into Brightmetrics and choose Admin Tools on the left sidebar menu.

Step 2: Choose the SSO tab on top.

Step 3: Choose Configure Single Sign-On.

Step 4: Once you choose Configure, you'll need to specify if you are using Open ID(OAuth2) or SAML 2.0 Provider.  This information if you are unsure would come from your IT department, but for our example using Azure AD the OpenID Connect (OAuth2) Provider should be selected.

Step 5: On the next page, check the box for "Use metadata URI" and copy and paste the "OpenID Connect metadata document" URI from the "Endpoints" section of your Azure App registration into Brightmetrics:

Step 6: Copy and paste the Application (client) ID from the overview into the Client ID field in Brightmetrics, and the client secret obtained earlier into the Client Secret field.

Step 7: Next, you can associate one or more email domains with your SSO profile, so that whenever an email address is entered on the login page that matches your registered email domain, the user will be prompted to log in via SSO.  You can also require that users with matching domains only log in via SSO, which may be useful if you wish to enforce password policies or other endpoint security via your identity provider.  Enter an email domain and an email address at that domain that can be used to verify ownership of the domain and click Next to proceed.

Step 8: On the next screen you can choose to enable automatic user provisioning.  With automatic user provisioning enabled when a new user logs in for the first time via SSO they will automatically have a user account created for them.  Once an administrator approves their request they will be able to log in.

 

Logging in

Once your domain registration is approved, you will be able to enter an email address associated with that domain on login page, and the login form will change to a "Log in with <your SSO configuration>".

The first time you log in, if either automatic user provisioning is not enabled, or if the email address obtained from your identity provider matches an existing account, you will be prompted to link your SSO identity to an existing Brightmetrics login via username and password:

Once you log in via username and password, the link will be established and from that point on you will be able to log in via SSO.

If the SSO email address does not match any existing user and automatic user provisioning is enabled, an account will be created.

 

SAML 2.0

This example uses Google Workspace, which allows you to configure SAML applications for your users that will appear in their apps launcher throughout the Google Apps UI.

 

Identity Provider

Step 1: In Google Admin, click on Apps, then Web and mobile apps, and click the drop-down for Add App, selecting "Add custom SAML app":

Step 2: Keep the next window open for copying and pasting data into Brightmetrics.  Items 1, 2, and 3 will be referenced in the steps below.

Brightmetrics

Step 1: Log into Brightmetrics and choose Admin Tools on the left sidebar menu.

Step 2: Choose the SSO tab on top.

Step 3: Choose Configure Single Sign-On.

Step 4: Choose SAML 2.0 Provider

Step 5: Copy "SSO Url" from Google to the "Redirect URI" in Brightmetrics (1).  Copy the "Entity ID" from Google to the "Issuer URI" in Brightmetrics (2).  Copy the Certificate from Google to the Certificate (by text) in Brightmetrics (3), and click Next

Step 6: See items 7 and 8 in the previous section for a description of email domains and automatic user provisioning.  One difference with SAML is that since the login can be initiated from the identity provider, associating an email domain with the SSO profile is less important.

Logging In

In the Google Admin section for the newly created app, you can click Test SAML Login to make sure it is working.  If you have not made the app available yet it will prompt you to do so:

It will also appear in the apps launcher for users to whom it has been made available

See the "Logging In" section of the OpenID instructions for a description of the first-time login experience for new or existing users.

 

For automatic provisioning of users to work correctly, the first and last name must be mapped to SAML attributes.  In Google these should be mapped from the first name and last name directory attributes to the "user.firstName" and "user.lastName" app attributes.  Please note letter casing as it must be an exact match.

 

Other identity providers

Most other OpenID Connect (OAuth2) providers have a similar setup, but the steps on the identity provider side may be different, and some terms may be different.  In general, there will always be some kind of application id and secret that you will create in your identity provider that you will have to enter in to Brightmetrics, and there will be some kind of authentication endpoint and token endpoint URLs that will need to be entered in to Brightmetrics.  If your provider supports OpenID Connect Discovery as Microsoft does, then that metadata URI can be used instead to discover those values automatically.

If your identity provider instead supports SAML, the information you will need from your identity provider is the URL to send users to in order to authenticate, sometimes called a redirect URL or sign-on URL.  You will also need the Issuer URI, which is an identifier for your identity provider, and an X.509 certificate that the provider uses to sign SAML assertions.  As with OpenID Connect, if the provider supports SAML discovery you can enter the federation metadata document URL instead to have it find that information automatically.

On the identity provider's side you will need to enter the assertion consumer URL for Brightmetrics, which is https://auth.brightmetrics.com/saml.cshtml, and the Brightmetrics consumer URI, sometimes called audience URI, which is https://auth.brightmetrics.com.  You may also need to map SAML assertions (or claims) to user properties.  Specifically the identity provider will need to provide the user's email address, either as the user's NameId or via the user.email claim, and also the user.firstName and user.lastName claims.

 

Questions or feedback? Please email us at support@brightmetrics.com.