Synchronize Contacts with Microsoft Entra ID

What is Microsoft Entra ID ?

Microsoft Entra ID is a multi-tenant, cloud-based directory and identity management service. It is an enterprise identity service that provides single sign-on and multi-factor authentication to help protect users from cybersecurity attacks.

How HappyFox - Microsoft Entra ID  Synchronization works?

HappyFox's Microsoft Entra ID contact sync integration lets you automatically sync, 

• Users from Microsoft Entra ID to HappyFox as contacts. 

• Additional fields of a user from Microsoft Entra ID to HappyFox as contact custom fields. 

Note: The automatic sync is initiated by HappyFox every day at 00:00 hrs in your help desk account timezone. The first sync happens instantaneously.

Integration Setup Prerequisites

• Your HappyFox agent role must have the Manage Apps permission.
• Ensure that the Microsoft Entra ID account has relevant admin privileges. HappyFox also does not support integrating a personal Microsoft Entra ID account. Please ensure you have an organizational Microsoft Entra ID account.

Steps to configure Microsoft Entra ID  sync:

• Navigate to Apps > SSO Sync (Category) > Microsoft Entra ID > Install. 
• Microsoft Entra ID has the concept of multi-tenant. You can choose you to sync users from either one or all the tenants you have configured in the Microsoft Entra ID You can view the tenants in your directory and get their IDs from your overview page as shown below: 

 Tenant authorization 

• Default tenant authorization: Clicking on default tenant will redirect you to the Microsoft Entra ID login page to enter your credentials. 
• Custom tenant authorization: Enter the tenant ID of the custom tenant from which you would like to sync users. Click Authorize.
  • Authorize your Microsoft Entra ID account by signing in (As an administrator).

• Once the authorization is complete, HappyFox will open the Sync settings form. 

Note: The integration should be authorized by a Global Admin.

Sync Settings

• Map contact fields: Map the user fields to HappyFox contact fields. Contacts created in HappyFox will sync values according to the field mapping done here. 
• Default Fields: Map the Email and Name fields of a HappyFox contact with the corresponding AD entity. HappyFox Email field should be mapped to Entra ID's User Principal Name.

• Phones: You can also choose to sync phone numbers of users from Entra ID to HappyFox contacts. Use the field mapping to map HappyFox and Entra ID phone numbers fields. 
• Custom fields: This section lets you sync Entra ID user’s fields to be mapped to any contact custom fields in HappyFox. 
  • Note: Multiple select and date fields contact custom field types are currently not supported for custom field mapping.
  • Turn ON the "Overwrite Existing Custom Field Values" toggle to update HappyFox contact custom field values whenever Entra ID Field value changes (During Sync). Turn this toggle OFF to prevent any overwrite of contact custom field values resulting from changes in Entra ID Field values.

Select Users

• All Users: This option will sync all the users from the selected tenants to HappyFox as contacts. 
• Specific Groups: Lets you choose the groups from which the Entra ID users should be synced to HappyFox as contacts. 

Send account information email to contacts imported: Enabling this will send an email to the newly synced contacts with information on the credentials and account URL to be used for logging in to their contact portal=

Enable Contact Sync: Enable this toggle for the synchronization to be active.

Once Contact Sync is enabled and saved,

• Contact sync will be initiated IMMEDIATELY post the initial setup.
• Post the initial sync, automatic user sync will be scheduled to occur every day at 12:00 AM account timezone. 
• Any changes made to the sync settings will be reflected in the next sync scheduled.

Contacts that are created from Entra ID sync, will have the Entra ID Logo adjacent to the contact name as shown in the screenshot below.

Contact Sync Log

Once the contact sync is complete, you will be able to see the following details of the sync in the table (refer below screenshot)

1. The date and timestamp at which the contact sync was complete.
2. The number of records (both successfully synced and failed records count will be displayed)
3. Download Report - This is a .csv file which can be downloaded to see the list of contacts which were synced and their respective sync status

Contents of the CSV Log file are explained below

• Email - Contacts email address (unique)
• Type 
  • Existing - If it is an existing contact record which was already present in HappyFox and was updated during sync. 
  • New - If it is a new contact record which was synced to HappyFox
• Sync Status 
  • Success - If a contact record synced successfully.
  • Failed - If a contact record failed to sync.
• Result
  • If a contact record failed to sync due to any reason it will be displayed here. Based on the reason the admin can correct any data inconsistencies in Entra ID. 

Notes:

Only the last contact sync status and its log file will be available for download. No historical contact sync logs will be available. Automatic contact sync from Entra ID to HappyFox will happen every day at 12:00 AM (based on account timezone)

The name attribute of contacts already present in HappyFox will not be auto-synced from Entra ID

Below are some of the possible cases due to which a contact record may fail during the sync,

1. Datatype mismatch:  If the datatype of mapped field(s) is different between Entra ID and HappyFox.

For example - If Entra ID field is Text which is mapped to a Number field in HappyFox this will cause a contact record to fail during sync.

2. Phone number field is Empty: If the phone number field is empty for a contact record during sync it will fail.

3. Mandatory or Required field is Empty: If a Contact custom field is configured as required in HappyFox, but the respective field is empty during Entra ID - contact sync then that contact record will fail during sync.

Disable, Modify and Troubleshoot the Integration:

Options to disable, re-authorize and delete the synced tenants are available under the more actions menu. If the status is disabled for some reason, it is recommended to reauthrozie the tenant as the first step in troubleshooting. If issue persists, please contact your help desk administrator. Active Tenants that are currently synchronized are represented with ✅.

Frequently Asked Questions

Q. Does changes made in HappyFox contacts reflect in Entra ID?

A: No. HappyFox - Entra ID contact sync integration is one way synchronization. Only changes made in Entra ID is kept in sync with HappyFox contacts and not vice-versa.

Q. If a contact is deleted in Entra ID is it automatically deleted in HappyFox?

A: No. Contacts deleted in Entra ID are not automatically deleted in HappyFox.

Q: If a user fields for a Entra ID Contact Field is modified, will it correspondingly reflect in HappyFox in the next sync?

A: This behavior is controlled by a toggle setting. If set ON, then all subsequent changes to Entra ID Contact fields will reflect changes in HappyFox Contact Custom Fields.