.. _set_up_an_ldap_server:
.. rst-class:: chapter-with-expand
Set up an LDAP Server
---------------------
.. _19.3.4|VOSS-704:
.. _20.1.1|VOSS-551|EKB-7380:
.. _20.1.1|EKB-6059:
Use this procedure to set up an LDAP server for integration with VOSS-4-UC.
**Procedure**
1. Log in as provider, reseller, or customer administrator.
2. Set the hierarchy node to the desired node where you want the users synchronized.
3. Choose **LDAP Management > LDAP Server**.
4. Click **Add**.
5. Complete, at minimum, the mandatory LDAP Server fields - see *LDAP Server Fields* below.
6. On the **Sync List** tab, optionally select a **LDAP Sync List Template** according to the
server type. By default, the following templates are available:
* **Ldap Sync List Microsoft Active Directory**
* **Ldap Sync List Open Ldap**
The selection can optionally be modified on the **Sync List** tab *after saving* the
server - see *LDAP Sync List Fields* below. If no template is selected, LDAP
sync will not be affected by this list. See:
* :ref:`set_up_ldap_for_user_synchronization`
* :ref:`synchronize_users_from_ldap`
7. Click **Save** to save the LDAP server.
**What to Do Next**
Perform a test connection to ensure the LDAP server is configured correctly.
If the authentication credentials or search base DN are invalid, an error message
pops up on the GUI, for example:
*Error encountered while processing your request*
*caught exception: [Helper] validation failed; Invalid search base db.*
LDAP Server Fields
..................
.. tabularcolumns:: |p{4cm}|p{10cm}|
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Fields | Description |
+=========================+===============================================================================================================================================================================================================================================================================================================================+
| Description | Defaults to the current hierarchy level. |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Host Name \* | Hostname or IP address of the LDAP server. This field is required. |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Port | Port number for LDAP traffic. Defaults to 389. |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | The User Distinguished Name of an administrative user who has access rights to |
| | the Base DN on the LDAP server. This field is required. |
| User DN \* | |
| | Examples: |
| | |
| | * Administrator@stb.com |
| | * OU=LDAP0,DC=stb,DC=com |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Admin | Admin password associated with the user. This field is required. |
| Password \* | |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | Base Distinguished Name for LDAP search. This should be a container or |
| Search Base | directory on the LDAP server where the LDAP users exist, such as an |
| DN \* | Organization Unit or OU. As an example, to search within an Organizational Unit |
| | called CUS01 under a domain called GCLAB.COM, the Search Base DN would be |
| | OU=CUS01,DC=GCLAB,DC=COM. This field is required. |
| | |
| | Note that the search will traverse the directory tree from this point down and will include |
| | any sub OU's which have been added within the OU. |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Search Filter | An RFC 2254 conformant string used to restrict the results returned by list |
| | operations on the LDAP server. |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Server Type \* | Choose between **Microsoft Active Directory** or **OpenLDAP**. For AD LDS (ADAM), choose **Microsoft Active Directory**. |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| AD Sync Mode \* | Defaults to Direct. |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Enable Write Operations | This check box is only shown for Microsoft Active Directory servers (**Server Type** is **Microsoft Active Directory**) when **Encryption Method** is "Use SSL Encryption (ldaps://)" (port is ``636``). When enabled, VOSS-4-UC user management allows for the management of users on the LDAP server (add, modify, delete). |
+-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. tabularcolumns:: |p{4cm}|p{10cm}|
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Fields | Description |
+========================+===============================================================================================================================================================================================================================================================================================================================================================================================================================================================+
| CUCM LDAP | The name of the LDAP Directory configured on CUCM that we want this user to be considered synced from. |
| Directory | The LDAP Directory must be configured on CUCM already. |
| Name | This is an optional parameter but the following should be considered: |
| | For top down sync scenario, Users will be added to CUCM as Local Users if this parameter is not set. |
| | For bottom up sync scenario, Users will not be able to log on to CUCDM if this parameter is not set. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Encryption | Choose between **No Encryption**, **Use SSL Encryption (ldaps://)**, or **Use StartTLS Extension**. |
| Method | |
| | * No Encryption - default port for LDAP is port 389 |
| | * Use SSL Encryption (ldaps://)a - uses port 636 and establishes TLS/SSL upon connecting with a client. |
| | * Use StartTLS Extension - to transition to a TLS connection after connecting on port 389 |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | If **Trust All** is Cleared, the LDAP server's SSL certificate is validated |
| Server Root | against this root certificate. If no **Server Root Certificate** is specified, |
| Certificate | validation is done against any existing trusted CA certificates. Use this |
| | option for custom root certificates in .pem format. See "SSO Certificate |
| | Management" for more information. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Trust All | Select this check box to disable certificate validation. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Primary Key Attribute | The attribute value used to uniquely identify and search for records on an LDAP server. For example, ``uid`` is the attribute when using a 389-Directory Server and ``entryUUID`` when using an OpenLDAP server. The attribute must be unique, should not change over time and should not be location specific. If no attribute is entered, ``entryUUID`` is used for an OpenLDAP server and ``ObjectGUID`` if the LDAP server is Microsoft Active Directory. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Authentication Scope | Hierarchical scope this server applies to: Local authentication or Full tree authentication. [#]_ |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| User sync type | Type of users that can authenticate against this server: All users or Synced users only |
| | |
| | * All users: All users can authenticate against this server. |
| | * Synced users only (Default): Only users synced in from LDAP can authenticate against this server. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Authentication enabled | Indicate whether the server is available for authentication. Default value is True. |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Search Filter examples:
* ``(telephoneNumber=919*)``: all telephone numbers starting with 919
* ``((&(OfficeLocations=RTP)(|(department=Engineering)(department=Marketing)))``:
office is located in RTP and department is either Engineering or Marketing
* ``(&(MemberOf=cn=Admin,ou=users,dc=foo,dc=com)(!(c=US)))``: all Admins except
those in the U.S.
User lookup for LDAP authentication will be restricted to the ``device/ldap`` model
specified in the **Authentication Attribute**: **Model Type**.
For example, if this attribute was ``device/ldap/user``, then the LDAP user authentication will be
restricted to ``(objectClass=user)``.
LDAP Sync List Fields
........................
When adding a new LDAP server or updating
an existing server added prior to release 19.3.4,
you can choose an **LDAP Sync List Option**.
The benefits of a Sync List is sync performance and
limiting synced attributes to those of interest.
The **LDAP Sync List Option** drop down offers:
* No sync list
LDAP sync is not driven by a LDAP Sync List;
all fields are imported as before release 19.3.4.
* Create sync list manually
The fields to sync can be added or modified manually.
For list override precedence and other considerations, see :ref:`ldap-sync-lists`.
* Create sync list from template
An **LDAP Sync List Template** drop down is presented
to allow a sync list to be selected from a predefined Configuration Template (CFT).
VOSS-4-UC provides default Sync List Configuration Templates (CFTs) for:
* Microsoft AD servers
* Open LDAP servers
These CFTs contain LDAP attributes that are typically required to be synced with LDAP.
After applying the template or if template is not used, a sync list
is visible and configurable directly on a saved LDAP server **Sync List** tab.
For further details, see :ref:`ldap-sync-lists`.
.. [#] See also: :ref:`user-login-auth-method-srv-auth-scope`.