Login – Azure Active Directory

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.

Azure Admin Consent

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. If using your own clientID, it is necessary to manually add the additional record below to ST_CONFIG for EarthSoft's clientId:

CONFIG_SECTION	CONFIG_KEY	OBJECT_TYPE	OBJECT_VALUE	STRING_VALUE
Authorization	Token	aud	4d627659-bb7b-428b-aa0a-32d1b6e77e1a	(null)

To enable blanket admin permission so that users do not need to request admin permission when logging onto their AAD sites, follow these instructions:

1.Select the Directory ID as documented in the previous section.

2.Input the into the following link in place of "{directoryId}":
https://login.microsoftonline.com/{directoryId}/v2.0/adminconsent?client_id=4d627659-bb7b-428b-aa0a-32d1b6e77e1a&state=12345&redirect_uri=https://aad.equisonline.com/redirect.html&scope=https://graph.microsoft.com/user.read%20https://graph.microsoft.com/user.readbasic.all [doc note - keep as text-only, not as a link]

This endpoint allows the global admin to provide consent for the user administrator.

3.Select the Microsoft AAD login account for your company.

4.A "Permissions Requested" page will appear for User.Read and User.Basic All permissions. This is admin consent so that individual users do not have to consent.

5.Select Accept, and the EarthSoft Validating redirect... page will appear.

To check the organization's EQuIS permissions, an AAD admin follow these instructions:

1.Navigate to the Azure Portal and select for the "Enterprise Applications" blade.

2.Select the EarthSoft EQuIS application.

3.Under Security, click on Permissions.

4.Review permissions.

5.Have users log onto the site to confirm they can log on using AAD without getting a consent prompt.

Use a Specific ID_TOKEN Claim to Identify the User

Azure AD ID_TOKENS may contain multiple claims that contain different user attributes. In the EQuIS Enterprise 7.20.2 Build and earlier builds, the "preferred_username" claim was used to identify the user. In EQuIS Enterprise 7.20.3 through 7.21.2 Builds, any of the following claims will be used (whichever is found first in the AAD ID_TOKEN): "preferred_username", "unique_name", "email", "upn". This creates a problem when the EQuIS ST_USER table record contains specific values, but the ID_TOKEN contains different values in those other claims—as whichever claim is found first in the token is used, and that may not match the value in the EQuIS ST_USER record. In this situation, users may want to specify exactly which claim (from the ID_TOKEN) should be used to identify the user when comparing to the EQuIS ST_USER record. This may be done by modifying the ST_CONFIG table record for the issuer such that the STRING_VALUE is a JSON object containing a "jti_claim" property with a value that is the exact (case sensitive) claim name that should be used (the "key" property with value of "~/openid" is also required).

CONFIG_SECTION	CONFIG_KEY	OBJECT_TYPE	OBJECT_VALUE	STRING_VALUE
Authorization	Token	iss	https://login.microsoftonline.com/{directoryId}/v2.0	{"key":"~/openid","jti_claim":"<claim>"}

For example, create the ST_CONFIG record as follows to use "preferred_username" as the ID_TOKEN claim that identifies the user in EQuIS:

CONFIG_SECTION	CONFIG_KEY	OBJECT_TYPE	OBJECT_VALUE	STRING_VALUE
Authorization	Token	iss	https://login.microsoftonline.com/{directoryId}/v2.0	{"key":"~/openid","jti_claim":"preferred_username”}