What is Azure Active Directory?
Azure Active Directory is Microsoft's 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 - Azure Active Directory Synchronization works?
HappyFox's Azure active directory contact sync integration lets you automatically sync,
Users from Azure active directory to HappyFox as contacts.
- Additional fields of a user from Azure 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 Azure AD account has relevant admin privileges. HappyFox also does not support integrating a personal azure account. Please ensure you have an organizational azure active directory account.
Steps to configure Azure active directory sync:
- Navigate to Apps > SSO Sync (Category) > Azure Active Directory > Install.
- Azure 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 azure active directory. You can view the tenants in your directory and get their IDs from your overview page as shown below:
- Default tenant authorization: Clicking on default tenant will redirect you to the Azure 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 Azure AD account by signing in (As an administrator).
- Once the authorization is complete, HappyFox will open the Sync settings form.
- 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 Azure's User Principal Name.
- Phones: You can also choose to sync phone numbers of users from azure to HappyFox contacts. Use the field mapping to map HappyFox and azure phone numbers fields.
- Custom fields: This section lets you sync azure 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 Azure Field value changes (During Sync). Turn this toggle OFF to prevent any overwrite of contact custom field values resulting from changes in Azure Field values.
- 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 azure 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 synchronized from Azure AD will have a Azure 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)
- The date and timestamp at which the contact sync was complete.
- The number of records (both successfully synced and failed records count will be displayed)
- 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)
- 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.
- 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 Azure AD.
Note: 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 Azure AD to HappyFox will happen every day at 12:00 AM (based on account timezone)
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 Azure AD and HappyFox.
For example - If Azure AD 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 Azure AD - 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 Azure AD?
A: No. HappyFox - Azure AD contact sync integration is one way synchronization. Only changes made in Azure AD is kept in sync with HappyFox contacts and not vice-versa.
Q. If a contact is deleted in Azure AD is it automatically deleted in HappyFox?
A: No. Contacts deleted in Azure AD are not automatically deleted in HappyFox.
Q: If a user fields for a Azure 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 Azure Contact fields will reflect changes in HappyFox Contact Custom Fields.