Synchronize Users against Active Directory Sources
All the applications included in the Imagicle UCX Suite share the same users list. This list can be edited manually through the web interface, adding users one by one, or automatically, importing the user list from a CSV file. If you have a large number of users, you might want to keep the user list in sync with an external directory.
The Synchronization Service lets you import users from an external source such as Active Directory, MS-Azure or the PBX. Once synchronization is enabled, the service aligns the list of users once a day. When a new user is added to the external source, it is inserted into the UCX Suite users list too. When the properties of a user are updated, the changes are written to UCX Suite users' list. Data transfer is optimized and only the differences are written to the database.
You could also use the synchronization service to import users once, then disable it and manually adjust the list.
Supported operations and matching criteria
The user synchronization service can perform three types of operation:
Insert, i.e. adding a new user
Update, i.e. changing one or more properties of an existing user
Delete, i.e. removing the user from the list
An UCX Suite User is considered to be the same as an Active Directory User when the "Active directory username" field, combined with the "Domain" field value, matches the Active directory account. E.g.
Active directory account = John.Smith@yourdomain.com
Active directory username field in User Management = John.Smith
Domain field in User Management = yourdomain.com
By default users which are deleted from the external source are automatically removed from UCX Suite too. This is the main difference between one-shot importing users from CSV and a synchronization. CSV import does not remove users, while the synchronization does.
If you want to create additional local users, please make sure that Active directory username and Domain fields are left blank, otherwise they are deleted during next synch.
How to enable Users Synchronization
You can access user synchronization through the web interface by selecting "User Management", then clicking the link "Synchronize users with an external data source" on the top of the page.
On the Welcome screen press the "Begin" button. This will enable the service.
Configuring the Data Source
Click the "Configure Data Source" link and select Active Directory from pull-down menu.
Enter a name for the source, e.g. MyCompanyDC, and press the "Add new source" button. The name must be unique, al least three characters long, and must contain no blanks.
Fill the form fields with these values:
Server: Active Directory server FQDN or IP address. If you use the FQDN, please make sure the name is resolved by Imagicle UCX instance.
LDAP object path: the subtree from which the accounts user will be imported. Basics of LDAP queries can be found on Microsoft web site.
LDAP Filter: Optional filter to narrow the imported users. We strongly suggest to apply a filter to avoid importing users without a phone number. I.e. (telephoneNumber=*)
Username: you must enter the credentials of an AD service account, with a password that never expires.
Password: tick the checkbox to the right to show or hide the entered password.
Note: If you leave the "LDAP object path" field blank, the "Users" branch is retrieved.
Press "Add" and "Back". When the new source has been added, enable it through the checkbox. Once enabled, the service tests the connection parameters and eventually turns the spot indicator to green.
Active Directory Secure Connection
Microsoft has updated security requirements for LDAP connections to Active Directory. After this update, Secure LDAP (LDAPS) has became mandatory for all LDAP connections to Active Directory. LDAP connections to Active Directory do not work unless Secure LDAP is configured.
Imagicle follows above Microsoft statement and Secure LDAP using SSL on port 636 is automatically enabled for both authentication and users' synchronization.
If you are upgrading an existing UCX Suite to Spring 2020 or above, the connection is automatically migrated to Secure LDAP and a test is performed to verify AD server reachability. If reachability is granted, then it means Microsoft statement has been respected. If AD can't be reached, then we just leave the connection as it is.
It is also possible to manually change the LDAP authentication settings:
access to Imagicle server via RDP and edit file C:\Program Files (x86)\StonevoiceAS\Apps\Fw\Settings\FW.Profile.Api.config.xml
add a new line, or update the existing one, for the preference Authentication.UseSecureLDAPConnection (see below sample)
<?xml version="1.0" encoding="utf-8"?>
<configuration>
...
<preference key="Authentication.UseSecureLDAPConnection" value="SecureThenUnsecure" />
<!-- OR -->
<preference key="Authentication.UseSecureLDAPConnection" value="SecureOnly" />
<!-- OR -->
<preference key="Authentication.UseSecureLDAPConnection" value="UnSecureOnly" />
...
</configuration>possible values are:
SecureThenUnsecure: authentication is tried to be granted using Secure LDAP (LDAPS), if connection failes, authentication is tried again using unsecure LDAP;
SecureOnly: authentication is tried to be granted using ONLY Secure LDAP (LDAPS);
UnSecureOnly: authentication is tried to be granted using ONLY unsecure LDAP
Configuring Synchronization Rules
Active Directory does not contain all the information needed to properly fill the Users properties. You have to provide the missing values through the web interface.
From main menu, go to Admin ⇒ Users Management ⇒ Synchronize users with an external data source ⇒ Configure Synch Rules
On the top of this page, select the type of source you want to configure the rules for (Active Directory).
For each field you have the various choices including the following.
Only when adding a new user set this value (followed by a textbox): this option applies only to insert operations. You can specify a default value for the field, which you could modify later from the User Management page, since it will not be overwritten if the user already exists.
Only when adding a new user set this value (followed by a checkbox): the same as the previous option for boolean fields. Boolean fields can only be set to true (checked) or false (unchecked).
Import every time from source: applies both to insert and update operations. You decided to manage this property from the remote data source, so the value will be synchronized at each cycle.
Keep existing value: the property will not be synchronized. You'll manage the value from the UCX Suite web interface. When the user is created (insert operation) the field will be set to blank. During next cycles (update operation) the value will remain unchanged.
Other options may involve specifying a prefix to be added to another field value. For instance the First extension number may be imported from the Telephone Number or IP Phone or Microsoft SIP URI Active Directory fields.
Not all the choices may be available for all the fields. E.g. there is no point in assigning the same default value to a user's personal address.
The Save button saves the changes. The Reload button undoes the changes. The Default button resets to the default values.
Press "Next" or "Back" to continue.
Synchronizing Users against Active Directory - Supported Attributes List
This table list the Active Directory user attributes and shows the UC Suite fields they are mapped to.
Active Directory Display Name: label displayed in the Active Directory user interface
LDAP Attribute Name: name to be used in LDAP queries, reported for reference but not required to configure UC Suite
UC Suite Field: Label displayed in the adapter's rule configuration UC Suite web page
UC Suite Database name: this is never displayed to the user
General Tab | ||||
Active Directory Display Name | LDAP Attribute Name | UC Suite Label | UCSuite Database name | Example Value |
First Name | givenName | First Name | user_nome | John |
Initials | initials | - | - | JS |
Last Name | sn | Last Name | user_cognome | Smith |
Display Name | displayName | - | - | "John, Smith" |
Description | description | - | - | Sales Manager |
Office | physicalDeliveryOfficeName | - | user_office_location | London Office |
Telephone Number | telephoneNumber | First Extension Number* | user_telnum, user_amnum | 0123 456 789 |
Telephone Number (Other) | otherTelephone | - | - | 0123 4457 89 |
Email, "Voicemail Address", "Fax to Email Address", "Single Sign-on Id" | user_mail, user_voicemailaddr, user_pref_fax_mailinaddr, ssoid | |||
Web Page | wWWHomePage | - | - | |
Web Page (Other) | url | - | - | |
Password | password | - | - | JohnsPass321 |
Destination OU | destinationOU | - | - | OU=Sales,DC=Domain,DC=Com |
Common Name | CN | - | - | John Smith or %lastname% %firstname% |
Modify User if already exists | Modify | - | - | True or False |
Delete User | Delete | - | - | True or False |
Address Tab | ||||
Active Directory Display Name | LDAP Attribute Name | UCSuite Label | UCSuite Database name | Example Value |
Street | streetAddress | User address | user_address | 10 Downing St;London |
PO Box | postOfficeBox | - | - | Po Box 1 |
City | l (Lowercase L) | - | - | London |
State/Province | st | - | - | New York |
Zip/Postal Code | postalCode | - | - | 20013 |
Country | c | - | - | GB |
Account Tab | ||||
Active Directory Display Name | LDAP Attribute Name | UCSuite Label | UCSuite Database name | Example Value |
User Logon Name | userPrincipalName | Active Directory username, Domain, Single Sign-on Id*** | userPrincipalName, user_ad (without domain), user_domain (without the username), user_authname, ssoid | |
User Logon Name (Pre W2K) | sAMAccountName | PBX username | user_ccmname | JSmith |
Telephones Tab | ||||
Active Directory Display Name | LDAP Attribute Name | UCSuite Label | UCSuite Database name | Example Value |
Home | homePhone | Home phone | user_telcasa | 123 123 123 |
Home (Other) | otherHomePhone | - | - | 0123 123 123 |
Pager | pager | - | - | 1234 |
Pager (Other) | otherPager | - | - | 123 |
Mobile | mobile | Mobile business number | user_mobileBusinessNumber | 123 456 789 |
Mobile (Other) | otherMobile | - | - | 123 456 789 |
Fax | facsimileTelephoneNumber | Fax number | user_faxNumber | 123 456 789 |
Fax (Other) | otherFacsimile | - | - | 0123 456 789 |
IP Phone | ipPhone | First Extension Number* | user_telnum, user_amnum | 750 |
IP Phone (Other) | otherIpPhone | - | - | 330750 |
Notes | info | - | - | General information (Use a semi-colon for carriage return) |
Organization Tab | ||||
Active Directory Display Name | LDAP Attribute Name | UCSuite Label | UCSuite Database name | Example Value |
Title | title | - | - | Manager |
Department | department | Department | user_department | Sales |
Company | company | - | - | Big Corp |
Manager | manager | - | - | CN=Ste Jobs,OU=Managers,DC=Domain,DC=Com |
Employee ID | employeeID | - | - | |
Employee Type | employeeType | - | - | |
Employee Number | employeeNumber | - | - | |
Car License | carLicense | - | - | |
Division | division | - | - | |
Middle Name | middleName | - | - | |
Room Number | roomNumber | - | - | |
Assistant | assistant | - | - | CN=Joe Blog,OU=Managers,DC=Domain,DC=Com |
User's Picture** | jpegPhoto / thumbnailPhoto | - | Pictures are saved in SQL DB | JPEG pictures supported. Max 200KB size |
Recording Group name |
| Recording Group name | - | Sales |
Fax Group username |
| Fax Group username | - | Sales |
*Either telephoneNumber or ipPhone attributes can be imported based on synch rules configuration
** Feature supported from Imagicle 2020.Winter.1 release. Either jpegPhoto or thumbnailPhoto attributes can be imported, based on synch rules configuration
*** Single Sign-On feature, based on SAML or OpenID Connect protocols, is supported from Imagicle 2022.Winter.1 release.
Extension Number Alias Synchronization
This field is by default left empty, If required, you can synch this user's field from the following AD attributes:
otherTelephone
otherIpPhone
telephoneNumber
ipPhone
Site Name synchronization
Starting from Imagicle UCX Suite Summer 2021, we can import Site Name from Active Directory or LDAP, to enable overlapping dial plan across multiple gateways or PBXs.
Depending on the users repository source, the Site Name can be synchronized from one of the following attributes (selectable in the synch rules page):
Active Directory:
department (default)
physicalDeliveryOfficeName
company
LDAP:
departmentNumber (default)
o
ou
l
Users' pictures synchronization
Starting from Imagicle UCX Suite Winter 2020, users' pictures can be synchronized with Active Directory LDAP, to enable two UC Suite features:
Viewing the user photo in the 'Colleagues' tab of the Imagicle Attendant Console.
Providing a users' picture repository for Cisco Jabber clients. Please see here.
Depending on the users repository source, the picture can be synchronized from one of the following attributes (selectable in the synch rules page):
Active Directory:
jpegPhoto
thumbnailPhoto
LDAP:
jpegPhoto
The default maximum picture size is 200 KB, bigger pictures will be discarded. If you need to adjust such size threshold, please contact Imagicle Support.
Pictures are saved in the Imagicle database.
Alarms
The Synchronization service is able to send alarms and warnings should a problem occur during or after synchronization. A brief report is included. The options are pretty self-explanatory. The global SMTP settings are used.
Testing user Synchronization
Once the configuration is complete, you can test it live by pressing the "Run now" button.
Warning: the synchronization process can take a long time if you have a large number of users, depending on the data source type.
To setup the daily schedule, use the "Enable Auto mode" checkbox. Set the hour of the day when you want the service to run, and press save the changes. A countdown will tell you the time left to the beginning of the process.
Reports
Every time the synchronization process is completed, a text report is generated. You can download the report through the web interface. Reports older than 15 days will be automatically removed.
If the synchronization operation is successful, the report contains only statistics. If a user is skipped, details are included so you can edit the user in the data source and try again.
Should an unexpected error be raised, debug information is included in the report. In this case, please send the file to Imagicle Support.