Azure AD SSO

Microsoft Azure Active Directory (AD) Single Sign On (SSO) Configuration

This integration was developed to allow customers who leverage Azure AD to use its SSO capabilities to provide authentication services for RegScale. For most large organizations, they manage their accounts and access within Microsoft's Active Directory product. If they have moved or integrated with Azure AD cloud services, Microsoft has opened up modern authentication use cases with OAuth to allow for a seamless SSO experience that is secure and scalable. RegScale has built an integration to allow our Enterprise Edition customers to use Azure AD SSO as an authentication mechanism for the RegScale platform.

Features and Benefits

There are multiple benefits to leveraging Azure AD SSO with RegScale:

• Improved Security - Multi-Factor Authentication (MFA), Adaptive Authentication, and other security tools are often integrated with Azure AD to provide a modern and secure identity management solution that implements best practices in Zero Trust. By leveraging Azure AD SSO for authentication, RegScale customers can take advantage of these security tools while also allowing our customers to centrally manage their identities.
• User Experience - RegScale users do not need to manage and provision separate accounts and passwords to use the platform. In addition, they can sign in with a single click without the need to enter a username and password.
• Centralization - by outsourcing authentication, customers can centralize their identity management and logging for ease of onboarding/offboarding and security reviews of logs.

Azure Application Registration

The steps for configuring Azure AD SSO are shown below:

1. Log into the Azure Portal with the appropriate permissions
2. Click or search for Azure Active Directory
3. On the left panel, click App Registrations under the Manage header
4. Click the + New Registration button to create a new application to leverage SSO
5. Give the application a name (i.e. RegScale)
6. Pick the Supported Account Type - this is typically set to "Accounts in this organizational directory only"
7. Under Redirect URI, set the following:
   • Select Single-page application (SPA) from the pulldown
   • Enter the redirect URI - this should be your domain name plus the /login route (i.e. https://sandbox.regscale.com/login); NOTE 1: The redirect must return to the RegScale login page for the round trip to succeed; NOTE 2: Redirect url is case sensitive - highly recommend all lower case
8. Click the Register button to complete the application registration
9. You should be redirected to a new Overview screen that contains three pieces of information that you will need to configure RegScale:
   • Application (client) ID
   • Directory (tenant) ID
   • Redirect URI (what you setup in the previous step)
   • NOTE: Copy these values to Notepad or another convenient place for future RegScale configuration
10. The next step is to configure the attributes that AD will pass back to RegScale in the token.
11. Click Token Configuration
12. Click + Add Optional Claim
13. Select ID as the token type
14. Click the following checkboxes:
    • family_name - maps to RegScale Last Name
    • given_name - maps to RegScale First Name
    • email - maps to RegScale Email
15. Click Add button to complete this step. If prompted, turn on Microsoft Graph to allow some of these attributes to be read.

At this point, configuration in Azure AD is complete and RegScale must be configured using this information.

RegScale Configuration

The steps for configuring Azure AD SSO are shown below:

1. Login with any account that has the Administrator role in RegScale
2. Click your name in the top right and select Setup from the dropdown menu
3. Click Integrations on the left menu
4. Search for and click on the button for Azure AD SSO
5. Click the checkbox to Enable Azure Active Directory (AD) Single Sign On (SSO)
6. For Client ID - enter the Application (client) ID from Azure
7. For Authority, enter this string https://login.microsoftonline.com/ + the Directory (tenant) ID (standard link for commercial)
8. If a Government customer, you may need to use an alternate link such as https://login.microsoftonline.us/ + the Directory (tenant) ID (standard link for US Government). For a complete list of government links, view the Microsoft National Clouds Guide
9. For Redirect URI, enter the redirect URI entered in Azure AD.
10. Click Save to update the configuration.
11. Logout of the application and you should now see the new SSO option for login.
12. Click Azure AD SSO button
13. For the first login, you may need consent on behalf of your organization to allow login. If so, click the checkbox and hit the Accept button
14. You should now be logged into RegScale using Azure AD SSO. NOTE: The new account will have no permissions. An administrator will need to assign the appropriate role(s) in RegScale before you have access to restricted pages or any data.

If you have any issues logging, verify that Azure info was copied into the RegScale configuration correctly. If that does not work, contact your technical support representative at RegScale for additional troubleshooting.

Azure AD SSO Authentication/Authorization Flow

The chart below shows the general flow for authenticating an RegScale user using Azure AD SSO:

This authentication flow works as follows:

1. RegScale user navigates to the login URL for the application (i.e. https://RegScale.mydomain.com/login)
2. If Azure AD SSO is enabled, the SSO option will show up as a button below the standard login.
3. The user can click the SSO button to attempt to authenticate to Azure AD via SSO.
4. NOTE: If the user has never logged in before, they may need to select the appropriate tenant to login. If there is only one tenant, it will default to that tenant and not prompt for the tenant.
5. If the user has logged in before, it will store the username and use it to look up the user's tenant. The tenant holds the AD SSO configuration used to login. Each tenant may have its own Azure AD SSO configured.
6. RegScale sends the request to Azure AD to perform authentication.
7. If the user is already logged into Azure/Office 365/etc., the login will be seamless with some back and forth routing in the browser but no user prompt.
8. If the user is not logged into a Microsoft service, the login prompt will be thrown to allow the user to sign in.
9. If the customer wishes to implement Multi-Factor Authentication (MFA), adaptive authentication, or other Zero-Trust style controls for identity management, they can leverage Azure AD SSO to perform that function for RegScale.
10. If authentication fails, an error message is thrown in RegScale and they cannot proceed past the login screen.
11. If authentication succeeds, the next step is to perform authorization in RegScale to implement Role-Based Access Control (RBAC).
12. Once Azure AD SSO logs in the user, it passes back a token showing authentication was successful along with some basic metadata (username, email, first name, and last name).
13. RegScale looks up the user name in its directory to see if it exists.
14. If the account does not exist, RegScale will thin provision a new account into the directory based on the Azure AD metadata. This new account will have no permissions so an RegScale admin will need to assign the appropriate role in the application before the new user has access to any data in the system. NOTE: If thin provisioning results in having two of the same users in the directory, deactivate/disable the account you do not want to use to remove them from the directory list. You may also need to reassign any records assigned to the old account.
15. RegScale then issues a JSON Web Token (JWT) that is good for 24 hours that assigns the roles for the user. This token is then used to authorize access to specific pages/functionality in the application and to data within the APIs.
16. The user may then interact with RegScale until the token expires, at which point, they must repeat this process over again.