Azure Active Directory (AAD) integration guide.
- Stan Dmitriev
Analytics
General principles
As of Ellie v3.7, user management with Microsoft Entra ID (Azure Active Directory) has been made possible. This is an opt-in functionality, which can be enabled and disabled by an admin of your organization.
Traditional user management in Ellie vs. Microsoft Entra ID -based user management
The default way of managing users in Ellie is, and has been, email- and password-based user accounts created into Ellie. These accounts can be managed by Ellie support or by the customer organization’s own Ellie administrators (i.e. those users of Ellie in the customer organization who have admin-level access to their Ellie). The “traditional” Ellie account is global, in the sense that with a given email address it is the same account and password for every Ellie environment where the user has been given access.
Even with ME-ID user management enabled, traditional accounts can still be used. This might be useful, e.g., in situations where short-term external consultants will never get a domain account in the customer’s ME-ID.
Default or “traditional” user management: users get their own Ellie accounts, which are given suitable access levels.
In contrast to that, ME-ID(AAD)-based user management works on the basis of ME-ID users being members of Microsoft Entra ID security groups. At the customer’s request, at the time of ME-ID enablement Ellie support links Ellie’s access levels (admin, write, contributor, read) to the security groups the customer has provided. The idea here is that access level in Ellie is determined by the user’s membership in a security group. After this setup has been done, management of individual users’ access levels no longer happens in Ellie at all.
ME-ID-based user management: users’ ME-ID identities are members of Security Groups, which are mapped to Ellie’s access levels. Users no longer have individual Ellie accounts.
Requirements
The customer willing to enable ME-ID user management for their Ellie needs to have the following:
Active customer account at Ellie Technologies
Trial users cannot enable ME-ID user management
Azure Active Directory tenant with all their Ellie users as Members
Guest-type accounts are not currently supported by Ellie
One or more Security Groups in their ME-ID that can be mapped to Ellie’s access levels
Note that more than one Security Groups can be given a certain access level
The customer must provide the following parameters when setting up the integration:
Object ID of the ME-ID tenant
Object IDs and names of the Security Groups they wish to use
Mapping of the Security Groups to Ellie’s access levels
An ME-ID administrator available to give admin consent to Ellie-ME-ID integration
How to setup the integration
To configure your Azure Active Directory SSO configuration login to your Ellie environment as an Admin user and go to Admin Tools → Metadata & SSO → Turn AAD ON, to start the AAD Setup. See the example bellow:
Technical implementation
Ellie’s ME-ID integration uses the OIDC protocol to authenticate users on login. This is Microsoft’s recommended protocol for handling authentication in a modern web app.
Login workflow
After ME-ID has been enabled and the necessary parameters configured by Ellie support, login workflow is as follows:
User navigates to the Ellie URL of their organization (e.g. company_name.ellie.ai ) and sees the login screen.
User clicks on “Login with Microsoft”.
Ellie checks whether ME-ID has been enabled for this particular customer
if not, the user is shown an error screen explaining that they do not have ME-ID enabled
if yes, the process continues
Ellie redirects the user to the customer’s ME-ID
User enters their Microsoft account credentials into their organization’s Microsoft login screen
ME-ID returns the authentication response to Ellie.
If the user is successfully authenticated, Ellie requests their group memberships from ME-ID via Microsoft Graph API and compares the response with the Security Group Object IDs defined by Ellie support based on the customer’s request
If the user doesn’t belong to any of the listed groups, they are shown an error screen explaining that they were authenticated successfully but don’t have the required permissions to access Ellie
If the user belongs to at least one of the listed groups, they will be granted access to Ellie according to the highest access level mapped to their groups (i.e. if a user belongs to two Security Groups with one being mapped to Ellie’s read access and one to write, they will gain write access).
The user is directed to Ellie’s normal app dashboard.
Permissions needed & admin consent
Ellie requires User.Read permissions in the customer’s ME-ID. Depending on the customer’s ME-ID setup, this might require admin consent, which in that case needs to be given before any user can proceed all the way through the login flow. However, if the customer’s ME-ID has been configured to not require admin consent for User.Read application permissions, then they will be able to give their personal consent during the login process.
Giving admin consent is possible either via Azure AD’s management portal at the customer’s end or simply by having the ME-ID admin log in to Ellie once the basic configuration from Ellie support is ready. Even though the admin user wasn’t a part of the Security Groups, they will be able to consent on behalf of their organization during the login process.
Data stored by Ellie
For all customers enabling the ME-ID user management functionality, Ellie will require the following data to be stored:
Object ID of their ME-ID tenant
Object IDs and names of the Security Groups the customer wishes to use to authorize their users into Ellie
No information relating to any other Security Groups will be stored
Basic user information of all authorized users from ME-ID that log in to Ellie, including their name, Object ID, membership status in the listed groups at the time of login, and contact email address if that has been filled in ME-ID
Other notes
Security
The OIDC protocol is a secure way of linking your Azure Active Directory to web applications, endorsed by Microsoft. Please refer to Microsoft’s documentation or Ellie’s Security Statement for details.
What happens to the existing “traditional” accounts?
When ME-ID is enabled for a customer, everything is configured, and the integration has been tested successfully, you can deactivate all the “traditional” accounts from your Ellie environment. These can be reactivated if necessary, but it is advised to maintain only one login method for end-users.
Note that this does not globally delete the accounts: if a user has access to two different Ellie environments with the same email-based Ellie account, they will maintain access to the one that didn’t enable ME-ID. This might be relevant for e.g. external consultants, who might have multiple Ellie environments where they use the same email-based Ellie account