In this article
NOTE: Some images may refer to Microsoft® Entra ID as 'Active Directory'
Objective
Sync users and user groups from Microsoft® Entra ID to Coconut for a more efficient staff creating/deleting/updating experience at your organization.
Before you begin
When Entra ID is connected prior to users existing in Coconut, the connection triggers an account invite to each user unless login by username/password is disabled. To connect Entra ID without triggering account invitations to users, Coconut recommends the following implementation flow:
- In Coconut, from Settings, connect SSO
- Once connected, edit the configuration to hide username and password
- Import users into Coconut
- Compare Coconut user details to Entra ID details to minimize the risk of duplicates
- Connect the Entra ID integration
Compare user details
Once users are imported into Coconut, compare user details between Coconut and Entra ID to ensure accurate matches and minimize the risk of duplicates.
How the integration matches users
The Entra ID (AD) integration matches users in Coconut with users in Entra ID if the user is in a selected AD group and one of the following conditions apply:
- The user’s First Name, Last Name, and Email fields in Coconut match the First Name, Last Name, and Email fields in Entra ID
- Hot Tip! Coconut also recommends that the user’s First Name and Last Name fields in Coconut match the Display Name field in Entra ID
- The user in Coconut was previously synced through the ME-ID integration
NOTE: Users in nested groups will only be synced if the nested group is selected.
In Coconut, ensure the following fields are up-to-date and reflect the information for the corresponding user in Entra ID:
- First Name
- Last Name
In addition, ensure the following fields in Coconut match the Display Name for the corresponding user in Entra ID:
- First Name
- Last Name
NOTE: For Coconut to match users based on Display Name in Entra ID, the value for Display Name in Entra ID must use the following format:
<first name> <last name>
If the Display Name in Entra ID is not formatted as first name, then last name (separated by a space and without any additional characters) the integration will match instead on the first name and last name fields in Entra ID.
Review a user’s info in Coconut
To review a user’s details in Coconut for comparison with their Entra ID info:
- From the navigation menu, click Staff
- Enter the name of the specific staff member in the search bar
- Click Profile
- Compare the info in the user’s First Name, Last Name, and Email fields to the info in Entra ID for the same user’s First Name, Last Name, Email, and Display Name
- Make any updates, if required
- Click Save
Ensure a user's First Name, Last Name, and Email in their Coconut profile match these details in Entra ID; also ensure that the First Name and Last Name in Coconut match the user's Display Name in Entra ID
Prepare users in Entra ID
Coconut recommends creating a group for the AD users your organization wants to sync with Coconut and adding these users to the Coconut group.
For more information on managing groups in Entra ID, please refer to this article.
For more information on using a group to manage access to integrated applications, please refer to this article.
For an introduction to groups and Entra ID, please refer to these resources.
Steps
Connecting the ME-ID integration requires setting up the integration and configuring settings. Once connected and configured, you can take additional actions, such as reviewing user details, performing a sync, refreshing groups, or disconnecting the integration.
Set up the integration
- From the navigation menu, click Settings
- From Integrations & API, click Entra ID
- Click Entra ID
- Enter your Microsoft Tenant ID
- NOTE: For more information on how to find your tenant ID, please refer to this article
- Click Continue
- An approval screen displays; click Have an admin account? Sign in with that account
- Do one of the following:
- Click the listed account (if the listed account has admin-level permissions)
- Click Use another account and enter the details for an admin account
- Enter the login credentials for the admin account
- Review the permissions request details and click Accept to proceed with the integration
The Entra ID Groups tab displays in Coconut, indicating a successful integration setup. All successfully integrated groups display in this view.
The Groups page displays once successfully connected
Configure integration settings
To configure how the integration behaves when syncing future users:
- From Settings>Integrations & API>Entra ID, click Configuration
- Select the default role users will have in Coconut when synced from Entra ID
- Hot Tip! For more information on different roles within Coconut, please refer to this article
- Select the default visibility users will have in Coconut when synced from Entra ID
- Hot Tip! For more information on visibility statuses, please refer to A note on access and visibility in this article
- Toggle on/off Use Microsoft ID as External ID depending on whether you want a Coconut user’s external ID to match the user’s Microsoft ID
Configure role mapping
Within settings, you can also map your organization's roles to Coconut roles using role mapping. This can be used in combination with Entra ID through relay states. For how to do this, please refer to this article.
Take additional actions
After the integration is connected and configured, you can take additional actions, such as reviewing user details, performing a sync, refreshing groups, or disconnecting the integration.
Review user details
To review user details:
- From Settings>Integrations & API>Entra ID, click Users
The Users tab displays. All active users in Coconut display in the users list. A checkmark displays for each user in the In Entra ID column that is in an Entra ID group connected through the integration.
Perform a sync
To perform a sync (import users from Entra ID into Coconut):
- From Settings>Integrations & API>Entra ID, click Groups
- Toggle on the Enabled setting corresponding to each group listed that you want to import into Coconut
- Click Apply Changes
The sync begins, and the process can take up to one hour to complete. The following actions happen during the sync:
- Users are created in Coconut if they are part of an Entra ID group but do not yet exist in Coconut
- NOTE: When a new user is created in Coconut, their email address as noted in Entra ID is used as the Username in Coconut
- User details are updated when they are successfully matched by First Name, Last Name, and Email to their corresponding Entra ID user
- NOTE: The following details are updated and cannot be edited in Coconut once synced:
- First Name
- Last Name
- Email Address
- Job Title
- Archived users in Coconut are reactivated if successfully matched by First Name, Last Name, and Email to their corresponding Entra ID user
- Users are archived in Coconut if they were previously synchronized, but are not in an AD group that was selected for the current sync process
Refresh groups
Click Refresh Groups to refresh the display list in Coconut of your groups in Entra ID.
Disconnect the integration
To disconnect the Entra ID integration:
- From the navigation menu, click Settings
- Click Entra ID
- Click Disconnect
- Select what happens to users in Coconut that have been imported from Entra ID
- Click Disconnect once more to confirm
A note on access and visibility
Admins can connect the Microsoft® Entra ID integration by accessing Settings. Please note you must also have admin access to Azure AD to complete preparation and connection steps.