Single Sign On (SSO) for Brightmetrics

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

1. 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:

   

2. 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. For Redirect URI enter https://auth.brightmetrics.com/oauthlogin.cshtml:

   

3. 3

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

   

4. 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:

   

5. 5

   The client secret value will then be displayed. Copy the secret value to a temporary location (such as Notepad) for later entering into the Brightmetrics SSO configuration:

   

Brightmetrics

1. 1

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

2. 2

   Choose the SSO tab on top.

3. 3

   Choose Configure Single Sign-On.

   

4. 4

   Once you choose Configure, you'll need to specify if you are using OpenID Connect (OAuth2) or SAML 2.0 Provider. If you are unsure, this information would come from your IT department. For our example using Azure AD, select OpenID Connect (OAuth2) Provider:

   

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

   

   

6. 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:

   

   

7. 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, then click Next to proceed.

8. 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 the 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

1. 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:

   

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

1. 1

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

2. 2

   Choose the SSO tab on top.

3. 3

   Choose Configure Single Sign-On:

   

4. 4

   Choose SAML 2.0 Provider:

   

5. 5

   Copy the 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:

   

6. 6

   See steps 7 and 8 in the OpenID Connect section above 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 Connect instructions above 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 vary. In general, there will always be some kind of application ID and secret that you will create in your identity provider to enter into Brightmetrics, and there will be some kind of authentication endpoint and token endpoint URLs that will need to be entered into 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 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 (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.

If you are specifically using Okta, the steps below will walk you through the setup:

1. 1

   Log in to your Okta Admin Console, go to Applications > Applications > Create App Integration.

2. 2

   Select SAML 2.0:

   

3. 3

   Give it an app name like "Brightmetrics." You may also choose to upload a logo if desired — reach out to support@brightmetrics.com for the logo. Walk through the steps here on creating your new App Integration:

   

   

   

4. 4

   Log in to Brightmetrics and choose Admin Tools, then the SSO tab, and choose SAML 2.0 Provider:

   

5. 5

   Enter the Redirect URI, Issuer URI, and the signing certificate (either pasted into the "By Text" input area or uploaded via "By File Upload") from the new SAML integration settings in Okta. Specify if Metadata URI should be used (optional):

   

6. 6

   Enter the domains and specify auto creation of users, and whether SSO should be required for these domains:

   

7. 7

   Review settings and choose Save.

8. 8

   Go to the Okta application > Assignments and assign to people or groups that should have access.

9. 9

   Test the integration by logging in via the Okta Portal.

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