Azure Active Directory for User Authentication in Enterprise

<< Click to Display Table of Contents >>

Navigation:  Enterprise > Installation and Configuration > Configuration > Authentication Methods > Login Screen >

Azure Active Directory for User Authentication in Enterprise

If configured, Enterprise users may be authenticated with Azure Active Directory (AAD). A "Sign in with Microsoft" button will be visible on the EQuIS Enterprise Login Screen. Clicking that button will redirect the browser to https://login.microsoftonline.com/, where the user can login with an AAD account. Upon successful login, the user will be automatically redirected back to Enterprise as an authenticated user.

 

Note: Having a valid AAD account does not automatically grant a user access to Enterprise. Their Enterprise user account (with email address that matches their AAD account email address) must exist and be assigned to the proper role(s). For AAD requirements specific to EQuIS Professional, see the Sign in with Microsoft page.

 

 

Ent-Microsoft_Login

 

If an administrator wants all EQuIS users to use only AAD user authentication, basic user authentication (i.e., EQuIS username and password) can be disabled. The EQuIS username and password text boxes and the Sign In button will no longer be displayed on the Login Screen. See the Configure Login Screen article.

 

Configuration for AAD

 

Azure Active Directory will only allow authentication from a known, registered application. EarthSoft has registered “EarthSoft EQuIS” as a known application with Microsoft. The Application ID (sometimes called “Client ID”) that Microsoft assigned is 4d627659-bb7b-428b-aa0a-32d1b6e77e1a. This value must be used exactly as-is in the steps outlined below. The first time a user for your AAD directory authenticates from EQuIS, s/he will be prompted to accept “EarthSoft EQuIS” as an application in your directory.

 

The following steps must be completed before end users will see the “Sign in with Microsoft” button and successfully login to Enterprise using AAD.

1.For security purposes, AAD will only send ID tokens to known sites. For AAD authentication to work, EarthSoft must register your site URL as a known URL for the “EarthSoft EQuIS” application. Send your fully qualified site URL (e.g., https://sub.domain.com/dir/default.aspx or https://sub.domain.com/default.aspx) and the EQuIS Enterprise build number of this site to support@earthsoft.com explaining that you are enabling AAD authentication for your site.

AAD will only redirect to approved URLs upon successful authentication, and it only allows a limited number of URLs. Microsoft recommends creating a "shared" redirect target to workaround the limited number of URLs. Starting with the 7.20.2 Build, successful AAD authentication will redirect to https://aad.equisonline.com target where the actual target URI will be validated (to avoid CSRF vulnerabilities). Upon validation, the user will be further redirected back to their Enterprise site.

2.Upon receiving confirmation from EarthSoft Support that your site URL is registered, determine your AAD “Directory ID” (sometimes called “Tenant ID”). This ID is a globally unique identifier (GUID) that is assigned by Microsoft and looks some like 13fa23a6-890b-4833-95e2-3e09d52aa512. The AAD/network administrator can find this ID as follows:

a.Login to https://portal.azure.com.

b.Browse to the Azure Active Directory blade.

c.Ensure that you are viewing the correct directory (if necessary, switch directories).

d.Click on Properties.

e.Copy the Directory ID.

3.Insert the following records into your ST_CONFIG table:

 

CONFIG_SECTION

CONFIG_KEY

OBJECT_TYPE

OBJECT_VALUE

STRING_VALUE

Authorization

AzureActiveDirectory

authority

https://login.microsoftonline.com/{directoryId}/

(null)

Authorization

AzureActiveDirectory

clientId

4d627659-bb7b-428b-aa0a-32d1b6e77e1a

(null)

Authorization

Token

iss

https://login.microsoftonline.com/{directoryId}/v2.0

~/openid

 

 

Note: For certain Enterprise sites, you may wish to authenticate users from multiple Azure Active Directory tenants (e.g. your own corporate AAD tenant for internal users and a different AAD tenant for subcontractors). When configuring multiple Azure Active Directory tenants for authentication, each separate tenant must be added as a token issuer (i.e., CONFIG_KEY = ‘Token’ and OBJECT_TYPE = ‘iss’), but the ST_CONFIG table should always only contain a single "authority" record (i.e., OBJECT_TYPE = ‘authority’). To support multiple AAD tenants, the "authority" OBJECT_VALUE should be changed to:

https://login.microsoftonline.com/common

That site is a generic AAD login page that allows the user to enter their email address, and will then redirect them to the specific AAD tenant to complete the authentication process. See the following link for more information: https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-convert-app-to-be-multi-tenant

 

 

The following records will be added automatically the first time Enterprise validates a token (i.e., when a user attempts to authenticate using AAD). These records are used by Enterprise to issue/validate tokens. EarthSoft recommends you backup both the {baseUri} and {SigningKey} values in a safe off line place for Disaster Recovery purposes.

 

CONFIG_SECTION

CONFIG_KEY

OBJECT_TYPE

OBJECT_VALUE

STRING_VALUE

Authorization

Token

aud

4d627659-bb7b-428b-aa0a-32d1b6e77e1a

(null)

Authorization

Token

iss

{baseUri}

{signingKey}

 

 

Note: For EQuIS Online customers, EarthSoft IT will assist with this configuration, but you must provide your AAD directory ID as explained in Step 2 above. Please send your directory ID (and site URL) to support@earthsoft.com and request that AAD authentication be enabled.

 

When integrating any application with Azure Active Directory, that application defines what permissions are expected/required. The first time any user within an AAD directory attempts to login to that application, AAD will require either user consent or admin consent based on the permissions that the application requests. The "EarthSoft EQuIS" application (i.e., 4d627659-bb7b-428b-aa0a-32d1b6e77e1a) requests the following Microsoft Graph permissions:

User.Read

User.ReadBasic.All

 

These permissions are defined by Microsoft here:

https://docs.microsoft.com/en-us/graph/permissions-reference#user-permissions

 

As noted the link above, both User.Read and User.ReadBasicAll do not require admin consent. Because these specific permissions do not require admin consent, the user can grant consent.

 

 

Note: If a client wishes to use their own custom ClientId, the redirect URL should be as explained in this Microsoft documentation article. Without that redirect URL, EQuIS Professional will not work with the client's Azure Active Directory.