Audience: System Administrators
Pre-requisites: A subscription which supports SSO via Azure AD, specifically Elite or Ultimate plan (or legacy plans “Professional” or “Enterprise”).
Introduction
Auto-enrolment of users is a feature provided by Contract Eagle to minimise the effort to manage user accounts for a large user-base, especially where a high proportion of users will rarely, if ever, make use of Contract Eagle.
How does it work?
Instead of adding a user to Contract Eagle in-advance, your IT team can set a custom property on the user profile in Azure Active Directory, so that their user account can be created automatically the first time they sign-on to Contract Eagle.
All that is set up in Contract Eagle in advance is the "model user". This defines all the business units and security groups to be assigned to the user the first time they log in.
The first time the user attempts to sign in, Contract Eagle will see that they aren't an existing user by searching for their email address in the Contract Eagle database. Then Contract Eagle will automatically create a new user-account within Contract Eagle by copying their name and email address from Contract Eagle, and their security/access settings from the model user, as specified in the custom property within Active Directory.
NOTE: Auto-enrol only applies to the first-time login.After that the user's permissions are controlled within Contract Eagle itself.
How to configure
Step 1 – Activate SSO with Azure Active Directory.
Go to Admin menu > System Preferences > Integrations tab.
Click the Activate SSO via Azure AD button.
Follow the prompts to complete the activation.
Step 2 – Define your Auto-Enrolment Domains
Go to Admin menu > System Preferences > Integrations tab.
Enter the domain names of users who will be signing in for auto-enrolment. Only users belonging to the domains specified here can be auto-enrolled into Contract Eagle.
Eg. If your user's email address is Layla.Stone@acme.com you should put "acme.com" in the field. You may specify multiple domains separated by commas. It is recommended that you only include domains which you control via Azure Active Directory.
Step 3 – Set up the model user(s) in Contract Eagle
Go to the Admin menu > Maintain Users screen and create a new user, which will become the model account for users who sign in using the auto-enrol capability.
3.1 Set up the User Profile
Firstly, choose a name and email address. Both the name and email address are arbitrary, but the email address will be used later as a custom property value in Azure Active Directory.
3.2 Set up the permissions
The permissions are the important part. They are what will be assigned to the enrolling user.
In this case we'll assign the "Read Only" role for all business units:
3.3 Save the user
OK > Save
3.4 Deactivate the user account
Deactivate the user account so that they don't show up in drop-down lists throughout the system:
Edit > Uncheck the Active checkbox > Save
Step 4 – Set up the Custom Property In Active Directory
Open the Azure AD Graph Explorer within your web browser:
Click the Login option at the top-right to sign-in to your Azure Active Directory.
Enter the URI for the user you wish to auto-enrol. The Graph Explorer PATCH is in the format below, where you substitute the domain and email address of the user below, and the email address of the Contract Eagle model account:
PATCH
https://graph.windows.net/yourdomain/users/useremail@yourdomain
{
"extension_baa3026ea84d41bbb1b4d3cf7e484ed6_ceModelAccount": "modeluseremailaddress"
}
Eg. If you wish to allow Layla Stone to auto-enrol via our “Read Only” model account from above, you would make the following patch:
PATCH https://graph.windows.net/acme.com/users/layla.stone@acme.com
{
"extension_baa3026ea84d41bbb1b4d3cf7e484ed6_ceModelAccount": "readonly@autoenrol.com"
}
Using Powershell Instead
Rather than using Graph Explorer, you may prefer to script these steps, and this can be performed easily using PowerShell. For example, the equivalent PowerShell command to execute step [d], above, is:
$UserId = (Get-AzureADUser -Searchstring layla.stone@acme.com).ObjectId
Set-AzureADUserExtension -ObjectId $UserId -ExtensionName "extension_baa3026ea84d41bbb1b4d3cf7e484ed6_ceModelAccount" -ExtensionValue "readonly@autoenrol.com"
Step 5 – Test the process
Test logging in to Contract Eagle via the specified user (eg. "Layla Stone") and you should see that the account is created under the user's own name and email address, but using the access privileges defined in the Model account.
Troubleshooting
If you get this Access Denied message when attempting to sign-in:
You may want to check the following:
That the domain of the user attempting to sign-on is defined as a Domain accepted for auto-enrolment. This is defined within the System Preferences screen under the Integrations tab.
That the extension property is visible within Graph Explorer. Login to Graph explorer and "GET" the user's properties, eg:
GET
https://graph.windows.net/acme.com/users/layla.stone@acme.com
"extension_baa3026ea84d41bbb1b4d3cf7e484ed6_ceModelAccount":
readonly@autoenrol.com"
That a user account (active or inactive) exists within Contract Eagle with the same email address as the extension property. Copy the email address from the extension property above (eg. readonly@autoenrol.com), then paste it into the Keyword search field under the Maintain Users option in Contract Eagle, check the Include Inactive Users option, then click Search. If nothing is found then the Auto-enrol process will not find it either, and will simply Deny access.