.. _set-up-ldap-for-user-synchronization:
LDAP user sync
------------------
.. _19.1.2|VOSS-541:
.. _20.1.1|VOSS-551:
.. _19.3.4|VOSS-704:
.. _21.3-PB2|EKB-13265:
.. _25.4|EKB-27139:
.. tip::
:ref:`use-action-search-to-navigate-automate`
Overview
..........
You'll need to set up an LDAP user sync in order to sync in users from a specified LDAP directory into Automate.
Users synced in from LDAP appear at the hierarchy node where the LDAP user sync object exists. Once
synced in, you can manage these users in Automate (via the User Management menu). For example,
you may want to move users to other hierarchies, or to push users to CUCM.
When syncing in from LDAP, some fields are always imported into Automate, while others are excluded. For
details, see :ref:`ldap-integration`
Delete or retain associated accounts at user sync
...................................................
You can configure (via :ref:`global-settings`) the LDAP user sync to
delete or retain Cisco (CUCM) subscriber voicemail and Webex accounts when running syncs after deleting a subscriber.
* On the **Webex App** tab of the Global Settings, choose whether to retain or delete the Webex app account
* On the **Voicemail** tab of the Global Settings, choose whether to retain or delete the voicemail account.
.. rubric:: Related Topics
* For details around LDAP server setup and authentication settings, see :ref:`set-up-an-ldap-server`
* :ref:`global-settings`
Add LDAP sync
.................
This procedure adds a LDAP sync to prepare for syncing users in from LDAP to Automate.
1. Log in as Provider, Reseller, or Customer administrator.
2. Set the hierarchy path to the node of the LDAP server you want to
sync users from.
3. Go to the **LDAP User Sync**.
4. Click **Add**.
5. Fill out details for the sync:
.. tabularcolumns:: |p{4cm}|p{11cm}|
+---------------------+-------------------------------------------------------------+
| Field | Description |
+=====================+=============================================================+
| LDAP Server | Mandatory. The LDAP server you're syncing from. |
+---------------------+-------------------------------------------------------------+
| | This setting is available only in Automate, and |
| | is disabled by default. |
| | |
| LDAP Authentication | Leave unchecked (clear) to sync in users from LDAP |
| Only | (from a predefined LDAP directory). In this case, |
| | the user passwords are authenticated against this |
| | LDAP directory. |
| | |
| | Select this checkbox (enable) to prevent user sync |
| | from the predefined LDAP directory. In this case: |
| | |
| | * Only the users passwords are authenticated against |
| | the LDAP directory |
| | * You can add users manually via the GUI, API, bulk |
| | load, or sync users in from CUCM. |
+---------------------+-------------------------------------------------------------+
| | Defines the LDAP object (from the configured LDAP |
| | server), and is used to import and authenticate |
| | users. |
| | |
| | * When LDAP server is Microsoft Active Directory, |
| | the default is ``device/ldap/user``. |
| | * When LDAP server is AD LDS (ADAM), set to |
| | ``device/ldap/userProxy``. |
| User Model Type | * When LDAP server is OpenLDAP, the default |
| | is ``device/ldap/inetOrgPerson``. |
| | |
| | Contact the LDAP server administrator if you need to |
| | identify a non-default User Model Type to use. |
+---------------------+-------------------------------------------------------------+
| LDAP Authentication | The attribute used for creating an LDAP user. |
| Attribute | |
| | When Server Type is Microsoft Active Directory, |
| | options are: ``employeeNumber``, ``mail``, |
| | ``sAMAccountName``, ``telephoneNumber``, |
| | ``userPrincipalName``. |
| | |
| | When Server Type is OpenLDAP, options are: |
| | ``employeeNumber``, ``mail``, ``telephoneNumber``, ``uid``. |
| | |
| | Custom values for a deployment are also allowed. |
+---------------------+-------------------------------------------------------------+
| Attribute | This value is used for LDAP authentication |
| | against LDAP when **LDAP Authentication Only** |
| | is enabled. |
+---------------------+-------------------------------------------------------------+
.. tabularcolumns:: |p{4cm}|p{11cm}|
+------------------+-------------------------------------------------------+
| | Choose the User Entitlement Profile that specifies |
| | the devices and services to which users synced in |
| | from the LDAP server are entitled. |
| User Entitlement | |
| Profile | The chosen entitlement profile is assigned to each |
| | synced in user. It is checked during user |
| | provisioning to ensure the user's configuration does |
| | not exceed the allowed services and devices specified |
| | in the entitlement profile. |
+------------------+-------------------------------------------------------+
| | The default role to assign to the synced user (if no |
| User Role | other LDAP custom role mappings are applicable for |
| (default)\* | the synced user, then this fallback/default role will |
| | be applied). Mandatory. |
+------------------+-------------------------------------------------------+
| | Defines whether users are automatically |
| User Move Mode | moved to sites based on the filters and |
| | filter order defined in **Manage Filters** |
+------------------+-------------------------------------------------------+
| | Defines whether users are automatically |
| | deleted from Automate if they are deleted |
| User Delete Mode | from the LDAP directory. If set to automatic, |
| | all subscriber resources associated with the |
| | user, such as a phone, are also deleted. |
| | |
| | .. warning:: |
| | |
| | Setting this option to *Automatic* will delete |
| | *all* users from the LDAP server (in Automate |
| | and in the UC apps, phones, services, and so on). |
+------------------+-------------------------------------------------------+
| | Defines whether users are automatically |
| | deleted from Automate if they are purged |
| User Purge Mode | from the LDAP device model. An administrator |
| | can remove the LDAP user from the device |
| | layer even if the user has not been removed |
| | from the LDAP directory. |
| | |
| | .. warning:: |
| | |
| | Setting this option to *Automatic* will delete |
| | *all* users from the LDAP server (in Automate |
| | and in the UC apps, phones, services, and so on). |
+------------------+-------------------------------------------------------+
6. Inspect the default mappings and modify if required, see :ref:`user-field-mapping`.
7. Click **Save** to add the LDAP sync.
.. note::
By default, the new LDAP sync is initially inactive. See :ref:`synchronize-users-from-ldap`.
8. In the Global Settings, define whether to retain or delete associated webex and/or voicemail accounts in
the user sync that runs after deleting a subscriber. See topic Global Settings (Webex App tab, Voicemail tab)
.. rubric:: Related Topics
*
.. raw:: latex
Global Settings in the Core Feature Guide
.. raw:: html
Global Settings (Phones tab)
LDAP sync scenarios (top-down and bottom-up)
.............................................
The table summarizes the two LDAP user sync scenarios that Automate supports:
* Top-down
* Bottom-up
.. note::
Although you can have different LDAP sync types at different parts of the hierarchy, it
is recommended that you run either top-down or bottom-up LDAP syncs.
.. tabularcolumns:: |p{5cm}|p{10cm}|
+----------------+------------------------------------------------------+
| Sync scenario | Description |
+================+======================================================+
| Top-down | Users are synced *directly* from the LDAP directory. |
| | |
| | User data is sourced from one or more |
| | LDAP directories. |
| | |
| | This setup defines how users are matched to be |
| | pulled in (for example, OU definition, LDAP filter, |
| | field filters, etc). Recommended for flow-through |
| | provisioning. |
+----------------+------------------------------------------------------+
| Bottom-up | Users are synced *indirectly* from the LDAP |
| | directory, that is, where applications are |
| | integrated and syncing the users from the LDAP |
| | directory. For example, the system syncs via the |
| | CUCM, which is syncing to LDAP. |
+----------------+------------------------------------------------------+
.. note::
In a top-down or bottom-up LDAP sync, a system configuration template sets the CUCM (LDAP)
user's identity field (``userIdentity``) to the user principal name (UPN), ``userPrincipalName``,
if it exists; otherwise it uses the email address. This is useful where a user has a
different email address to the UPN and needs to be correctly mapped following a LDAP sync, and then
the user is moved to a site.
Impact of Webex Control Hub directory sync on LDAP updates
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
In top-down LDAP sync scenarios, VOSS may selectively skip updating application-specific user records when
external systems are configured as the authoritative source.
**Webex Control Hub directory-synced behavior**
If Cisco Webex Control Hub is configured for LDAP Directory Sync (DirSync), VOSS treats Control Hub as the
source of truth for Webex user data when processing updates originating from LDAP synchronization.
During updates to ``data/User`` triggered by LDAP synchronization, VOSS skips updating the Webex user record
(``device/spark/User``) only when all of the following conditions are true:
* The user has been synced top-down from LDAP (a ``device/ldap/User`` record exists)
* The user is a Webex user
* Webex Control Hub is directory-synced
In this case, the Webex user update step is intentionally skipped to prevent LDAP data from overwriting
Control Hub-managed Webex user attributes.
.. important::
This behavior applies only to updates triggered by LDAP synchronization (that is, updates originating from
``data/User`` via LDAP sync).
Updates triggered from other sources, such as administrator actions, ``relation/User`` updates, or
subscriber workflows, continue to update the Webex user record as normal, even when Control Hub is
directory-synced.
**When Webex users are updated**
Webex user updates proceed as normal when:
* The user is not LDAP synced, or
* Webex Control Hub is not directory-synced, or
* The update is triggered by a non-LDAP source (for example, an administrator action or another workflow)
.. _ldap-sync-lists:
LDAP sync lists
................
The table describes, for LDAP sync, LDAP sync lists, arranged in override order:
========================================= =================================================================
1. *Always synced list* Fields required to list LDAP Users on the GUI
2. *Drop Field List* Fields never imported from LDAP
3. *Data Sync Blacklist* (denylist) A change in these fields does not trigger an update
4. *Model Type List* From the LDAP data sync. Set up and used in scheduled syncs
5. *LDAP Sync List* (manual or from CFT) Fields to be imported from LDAP as set up with the LDAP server
========================================= =================================================================
Always synced list
''''''''''''''''''
The following fields are always synced in an LDAP sync as their values are required to
list LDAP users on the GUI:
=================== ===========================
Column Name Field Name
=================== ===========================
Cn ``cn``
Uid ``uid``
Description ``description``
Mail ``mail``
User Principal Name ``userPrincipalName``
SAM Account Name ``sAMAccountName``
=================== ===========================
Drop field list
''''''''''''''''
Any items in the LDAP Sync List from ``DROP_FIELD_LIST`` are excluded from the sync. This
list is read-only.
::
DROP_FIELD_LIST=[
'photo',
'jpegPhoto',
'audio',
'thumbnailLogo',
'thumbnailPhoto',
'userCertificate',
'logonCount',
'adminCount',
'lastLogonTimestamp',
'whenCreated',
'uSNCreated',
'badPasswordTime',
'pwdLastSet',
'lastLogon',
'whenChanged',
'badPwdCount',
'accountExpires',
'uSNChanged',
'lastLogoff',
'dSCorePropagationData'
]
Data sync denylist
'''''''''''''''''''''
.. raw:: latex
See Settings (Data Sync Workflow Execution Control) in the Advanced Configuration Guide.
.. raw:: html
See Settings (Data Sync Workflow Execution Control)
An LDAP sync list won't override any of the Data Sync Denylist attributes (default or custom) in
``data/Settings``. That is, for fields that appear in both the LDAP Sync List and in the
Data Sync Denylist, where the field value is different on the LDAP server, the LDAP sync won't trigger
any update for the LDAP entity during a sync.
Model type list
''''''''''''''''''
Given an existing LDAP server with a LDAP Sync List configured, when executing a data sync against
the LDAP server, the *existing Model Type List functionality* from the LDAP data sync
is maintained and takes precedence over the LDAP Sync List.
See:
* :ref:`create-a-targeted-model-type-list`
* :ref:`model-type-lists`
LDAP sync list
''''''''''''''''
A new LDAP server or one that existed in the system prior to release 19.3.4
allows you to choose the **LDAP Sync List Option**:
* No sync list
* Create sync list manually
* Create sync list from template
The configuration template (CFT) can also be created and applied to a
server. See :ref:`LDAP-sync-cft`.
.. important::
Besides the sync override order indicated above, manual or template sync lists
are bound by the following considerations:
* If no sync list is set up, LDAP sync is not affected by this list.
* When updating the default sync list (or any sync list you choose), a full sync is
required (during the next scheduled, or a manual sync). See the **Sync and Purge** menu, and
for more information about data sync and data sync cache, see :ref:`data-sync-types`.
Until a full LDAP user import is performed, user details are updated in the local cache
(when opening a management page).
For these reasons, it is recommended that such updates and syncs should be scheduled
for off-peak times, particularly where a large number of users requires a large sync.
* For users targeted for Cisco-based services, a field must be mapped to the
surname field for users. It is therefore important to
include a field in the Sync List that is mapped to the 'surname' field,
typically ``sn``.
For details on the LDAP Sync List on the LDAP server, see: :ref:`set-up-an-ldap-server`.
.. note::
By default LDAP user details shown on the GUI display all ``device/ldap/user``
fields. It is recommended that you create a FDP
for ``device/ldap/user`` to contain *only* the fields
from your LDAP Sync List in order to view LDAP user details
according to your configuration.
.. _LDAP-sync-cft:
LDAP sync list configuration templates
.......................................
Administrators can clone the default sync list Configuration Templates (CFTs)
to a hierarchy, and modify them for use during initial LDAP server setup.
Modified CFTs are available at the hierarchy on the
**Sync List** tab (from the **LDAP Sync List Template** drop-down).
Two default CFTs are provided. Both can be cloned:
* **Ldap Sync List Microsoft Active Directory**
* **Ldap Sync List Open Ldap**
The table describes the default CFT fields:
========================================= =========================================
Ldap Sync List Microsoft Active Directory Ldap Sync List Open Ldap
----------------------------------------- -----------------------------------------
Model Type: ``device/ldap/user`` Model Type: ``device/ldap/InetOrgPerson``
========================================= =========================================
``sAMAccountName`` ``uid``
``mail`` ``mail``
``givenName`` ``givenName``
``sn`` ``sn``
``title`` ``title``
``department`` ``departmentNumber``
``displayName`` ``displayName``
``employeeNumber`` ``employeeNumber``
``employeeType`` ``employeeType``
``homePhone`` ``homePhone``
``ipPhone``
``telephoneNumber`` ``telephoneNumber``
``mobile`` ``mobile``
``otherMailbox``
``facsimileTelephoneNumber`` ``facsimileTelephoneNumber``
``l`` ``l``
``c``
``streetAddress``
``st`` ``street``
``postalCode`` ``postalCode``
``physicalDeliveryOfficeName`` ``physicalDeliveryOfficeName``
``manager`` ``manager``
``memberOf`` ``memberOf``
``objectClass`` ``objectClass``
``o`` ``o``
``ou`` ``ou``
========================================= =========================================
If new LDAP attribute names are added to the cloned CFT and modified
on the GUI, type the names in. Initially, all attribute names are imported.
The full attribute list and naming is available on the
GUI **Sync List** tab from the default sync list for
the server. See: :ref:`set-up-an-ldap-server`.
Enter a descriptive name for the cloned CFT,
which will then show in the hierarchy on the drop-down list
of **Sync List** CFTs that are available when you modify an LDAP server
or create a new server.
Multiple LDAP organization units per hierarchy
...................................................
Large corporations and institutions with multiple domains or agencies may require
more than one LDAP Organizational Unit (OU) to be configured at a hierarchy.
Automate allows for multiple LDAP OUs at a hierarchy by providing
for a *unique combination* of the following LDAP server properties
at the hierarchy:
* IP address
* Port
* search base DN
Multiple search base DNs can therefore be configured at the *same hierarchy*
for different organizations within the same company, so
that administrators and self-service users can successfully authenticate.
For example:
LDAP server setup:
+---------+------+---------------------------------------+-------------------+
| IP | Port | Search base DN | Hierarchy |
+=========+======+=======================================+===================+
| 1.2.3.4 | 389 | ou=SharedOUA,dc=voss-solutions,dc=com | Provider.Customer |
+---------+------+---------------------------------------+-------------------+
| 1.2.3.4 | 389 | ou=SharedOUB,dc=voss-solutions,dc=com | Provider.Customer |
+---------+------+---------------------------------------+-------------------+
Users:
* userA: ou=SharedOUA,dc=voss-solutions,dc=com
* userB: ou=SharedOUB,dc=voss-solutions,dc=com