Auth0 offers a way to add authentication services to your applications. With it integrated into your Sonar instance, users would select Continue With Single Sign On as opposed to inputting their Sonar credentials.
This feature is currently available to work with Google and Microsoft only, with SAML and Active Directory following shortly.
Configuring Auth0
Before fully configuring Auth0 with your Sonar instance, you must first integrate it with your Google or Microsoft system. Following this, you'll be provided a Client ID and Client Secret, which will be used during the integration with your instance.
For both options, the following information will be utilized:
sonar.software and auth0.com will be required for the authorized domains
/auth/userinfo.email and /auth/userinfo.profile will be the options selected when choosing from the list of scopes
https://sonarsoftware-prod.eu.auth0.com/login/callback is to be used as the application home page
During the setup process, you'll be given the option of whether you want to restrict use to your domain or include external domains too. Which option you select depends on your business use, but any will work with the Sonar integration.
Setting Up Auth0 with Google
For details on integrating Auth0 with your Google dashboard, click here.
Setting Up Auth0 with Microsoft
For details on integrating Auth0 with Microsoft Azure, click here.
Permissions
In order to make use of the Auth0 feature, the corresponding role permissions must be enabled first. Please take a moment to review these new permissions, and ensure that the relevant roles have them added before proceeding with any walkthrough steps below.
If you're a Super-Admin of your Sonar instance, no permission changes are required for your account. For more information on Roles and Permissions overall, please review this linked article.
Navigate to Settings > Security > Roles and either choose to edit an existing Role or create a new Role. When the next page populates, locate the permissions reflected in the screenshots below and enable whichever ones are applicable to that Role.
The above permissions must be enabled to view the Identity Provider settings page.
Configuring Auth0 in your Instance
Before your users are able to take advantage of SSO (Single Sign On) with Auth0, you must enable and configure the feature within your instance. You are able to add up to 5 IDPs (identity providers) at a time, but for our example, we'll just be adding one:
Navigate to Settings > Security > Identity Providers, toggle the Auth0 option, and then click on Save.
Once Auth0 is enabled, click on Create Identity Provider and select either Google or Microsoft.
SAML and Active Directory will be options at a later date.
A modal will appear where you will input the configuration settings. For our example below, we've selected Create Google Identity Provider:1. Enabled allows you to toggle the IDP on and off. If you were to disable an active one, it would prevent users from logging in via that method. 2. The Display Name must be unique to your instance. 3. The Client ID field is where you'll input the one provided by your identity provider host. 4. Similarly, the Client Secret section is for the secret provided by your identity provider host.
There is no validation for the Client ID and Client Secret you add here; if the information is incorrect then users will be unable to sign in via SSO.
When all the fields are filled out, click Create.
Deleting or disabling an Identity Provider will not log out users utilizing that login method; if you want to prevent users from accessing your instance via SSO then you must either disable Auth0 or disable their individual users.
Configuring Auth0 for your Users
Any email addresses intended to be used via Auth0 must be associated with an existing user in their Sonar instance. If someone were to attempt to log in when a user does not yet exist, they'll be met with the following error message:
Our Users: Overview article details how you can create a user. Once the user is set up, it must remain “enabled” for that person to continue to be able to log in.
If a user is ever “disabled” and they attempt to use SSO, they'll be met with a 401 error. Likewise, if a user is already logged in and their user is disabled, they'll be kicked following the next input request they make.
If a new user is created with the intention of solely utilizing the Auth0 feature, they will not have to follow through with the initial setup email that is automatically sent out via the instance. Instead, once they've successfully logged in for the first time using Auth0, you'll notice “Yes” underneath the “Completed Setup” column header.
Auth0 in Use
Once Auth0 has been set up and enabled, existing users are able to take advantage of the Auth0 feature. This option is visible on the login screen to access their instance.
When a user clicks Continue With Single Sign On, a new page will populate that lists the options available to log in with. In our example, we've set up an instance to utilize Google only, and therefore we see the following page:
From here, we will select Continue with Google IDP and be directed to the Google login page, then we'll be prompted to accept permission to pair the app.
If you are using Google Chrome and logged in with a Google account already, SSO will continue with those credentials automatically. If you intend to utilize an alternate account, you must either sign out of your account or open a new window with an alternate Google profile and continue from there.
If a user unintentionally clicks on Decline, the option will be presented again the next time they attempt to access the instance via the Auth0 feature.
As long as an account exists —and is enabled— with the email address you are attempting to log in with, you'll be able to successfully access the instance.
If you are logging in on a shared device, it is recommended that you use a browser that does not save your cache data, such as Chrome Incognito.
Field Tech App Consideration
SSO is not possible via the Sonar Field Tech App; any user intending to use the app will need to ensure they have a password set within their Sonar instance. Existing users should already have a password attached to their login that can be used, and new users should either continue with the initial account setup email they received or alternatively, can request a password reset on their login screen.
Updated
by Kristen Fiddes
