[Index]

Model: relation/HcsLdapServerREL

LDAP Server

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:

    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:

  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

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.
User DN *

The User Distinguished Name of an administrative user who has access rights to the Base DN on the LDAP server. This field is required.

Examples:
Admin Password * Admin password associated with the user. This field is required.
Search Base DN *

Base Distinguished Name for LDAP search. This should be a container or directory on the LDAP server where the LDAP users exist, such as an 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.
Fields Description
CUCM LDAP Directory Name The name of the LDAP Directory configured on CUCM that we want this user to be considered synced from. The LDAP Directory must be configured on CUCM already. 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 Method

Choose between No Encryption, Use SSL Encryption (ldaps://), or Use StartTLS Extension.

  • 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
Server Root Certificate If Trust All is Cleared, the LDAP server's SSL certificate is validated against this root certificate. If no Server Root Certificate is specified, 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 (Default): All users can authenticate against this server.
  • Synced users only: 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:

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:

Ldap Sync List Microsoft Active Directory Ldap Sync List Open Ldap

LDAP servers can be integrated with VOSS-4-UC for these two purposes:

LDAP Authentication and VOSS-4-UC Credential Policies

VOSS-4-UC supports LDAP authentication as either standalone (LDAP Authentication only) or in conjunction with LDAP syncing of the users. The user accessing the system provides credentials via the VOSS-4-UC login page and an authentication request is sent to the appropriate LDAP server(s) based on the user setup.

The username and password provided needs to match that in the LDAP server based on the LDAP field selected for username. This username is used to map to the requisite user in VOSS-4-UC to determine access, role, and so on after successful authentication. By default, this mapping is done based on the LDAP field used (as defined in the LDAP setup in VOSS-4-UC) that matches the VOSS-4-UC username. However, if required, VOSS-4-UC does allow you to map non-matching usernames as part of the authentication setup for the user. This is useful when you need to have a different username in VOSS-4-UC and the UC apps than you have in LDAP.

When using LDAP Authentication, the password rules part of the credential policy in VOSS-4-UC do not apply as the password is managed in the directory. Other credential policy rules like session length are applied as they are managed by VOSS-4-UC.

User authentication only is not available for OpenLDAP.

Note

LDAP Sync Scenarios

User synchronization is available for Active Directory (AD) and OpenLDAP.

Two sync scenarios are possible:

LDAP Sync Lists

With LDAP sync, consider the following lists. They are here arranged in order of override precedence:

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 - 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

Details of these lists are provided below:

Always Synced List

A number of fields are always synced, since these 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

If any items in the LDAP Sync List are contained in the DROP_FIELD_LIST below, these are not synced, since they are not considered during any sync. This list is fixed in the system and is not configurable:

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 Blacklist

Refer to Data Sync Blacklist

An LDAP Sync List will not override any of the Data Sync Blacklist attributes - default or custom - in data/Settings. In other words, if a field is in both the LDAP Sync List and the Data Sync Blacklist and the field value is different on LDAP server, then when syncing the LDAP server, the LDAP sync will not trigger any update for the LDAP entity during sync.

Existing Model Type List

Given an existing LDAP Server with a LDAP Sync List configured, when executing a Data Sync against the LDAP server, then the existing Model Type List functionality from the LDAP data sync is maintained and takes precedence over the LDAP Sync List.

See:

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:

The template (CFT) can also be created and applied to a server - see LDAP Sync List Configuration Templates.

Important

Besides the sync override order indicated above, manual or template sync lists are bound by the following considerations:

For details on the LDAP Sync List on the LDAP server, see: Set up an LDAP Server.

Note

By default LDAP user details shown on the GUI display all device/ldap/user fields. It is therefore recommended to 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 List Configuration Templates

Administrators can also clone the default sync list Configuration Templates to a hierarchy and modify these for use during initial LDAP server setup. The modified CFTs will then be available at the hierarchy on the Sync List tab from the LDAP Sync List Template drop-down list.

Two default CFTs are provided and can be cloned:

The default CFT fields are:

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: 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 OUs 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.

VOSS-4-UC allows for multiple LDAP OUs at a hierarchy by providing for a unique combination of the following LDAP server properties at the hierarchy:

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:

Model Details: relation/HcsLdapServerREL

Title Description Details
Description The description of the LDAP server.
  • Field Name: description
  • Type: String
Host Name * The host name of the LDAP server.
  • Field Name: host
  • Type: String
Port The port number for LDAP traffic. The ports a fully configurable. Default: 389
  • Field Name: port
  • Type: String
  • Default: 389
User DN * The User Distinguished Name (DN) on the LDAP server.
  • Field Name: user_dn
  • Type: String
Admin Password * The administrator Password associated with the Username to connect to the LDAP server.
  • Field Name: password
  • Type: String
  • Is Password: True
  • Store Encrypted: True
Search Base DN * The base Distinguished Name for LDAP search.
  • Field Name: search_base_dn
  • Type: String
Search Filter A RFC 2254 conformant string that is used to restrict the results retuned by list operations on the LDAP server.
  • Field Name: search_filter
  • Type: String
Server Type * The selected LDAP server type. The type can be Open LDAP or Microsoft Active Directory.
  • Field Name: server_type
  • Type: String
  • Choices: ["Microsoft Active Directory", "Open LDAP"]
Authentication Attribute
  • Field Name: auth_attribute
  • Type: Object
Model Type The model type to be used for authentication. The defualt choices are device/ldap/inetOrgPerson, device/ldap/person, and device/ldap/user. If the default choices do not fit the deployment scenario, custom values are allowed for this field.
  • Field Name: auth_attribute.model_type
  • Type: String
  • Choices: ["device/ldap/inetOrgPerson", "device/ldap/person", "device/ldap/user"]
Login Attribute Name The selected attribute of the LDAP user login. When Server Type is Microsoft Active Directory, the following default choices are populated employeeNumber, mail, sAMAccountName, telephoneNumber, userPrincipalName. When Server Type is Open LDAP, the following choices are populated employeeNumber, mail, telephoneNumber, uid. If the default choices do not fit the deployment, custom values are allowed for this field.
  • Field Name: auth_attribute.name
  • Type: String
  • Choices: [""]
Connection Security
  • Field Name: connection_security
  • Type: Object
Encryption Method The encryption mechanism to be used. This can be No Encryption, Use SSL Encryption (ldaps://), or Use StartTLS Extension Default: no_encryption
  • Field Name: connection_security.encryption_method
  • Type: String
  • Default: no_encryption
  • Choices: ["No Encryption", "Use SSL Encryption (ldaps://)", "Use StartTLS Extension"]
Certificate Validation Specifies behavior for certificate validation eg. Trust all certificates (no validation).
  • Field Name: certificate_validation
  • Type: Object
Trust All When enabled, the system will not check if the server's certificate is trusted.
  • Field Name: connection_security.certificate_validation.trust_all
  • Type: Boolean
Server Root Certificate When trust_all is False, the LDAP server's SSL certificate will be validated against this root certificate. If this certificate is not specified, validation will done against any existing trusted CA certificates. Use this option for custom root certificates in (.pem format)
  • Field Name: connection_security.certificate_validation.server_root_certificate
  • Type: String
  • Target: data/File
  • Format: uri
Advanced Configuration Advanced configuration settings.
  • Field Name: advanced_configuration
  • Type: Object
Primary Key Attribute This field allows an administrator to specify the primary key attribute that will be used to retrieve records from the ldap server.
  • Field Name: advanced_configuration.custom_pk
  • Type: String
Data Sync List LDAP attributes to be included during data sync.
  • Field Name: data_sync_list.[n]
  • Type: Array
Model Type Model type whose attributes should be included (eg device/ldap/user)
  • Field Name: data_sync_list.[n].model_type
  • Type: String
  • Format: uri
Attributes Attributes to be included for model type.
  • Field Name: attributes.[n]
  • Type: Array
Name
  • Field Name: data_sync_list.[n].attributes.[n].name
  • Type: String
Authentication settings Authentication settings.
  • Field Name: authentication
  • Type: Object
Authentication Scope Hierarchical scope this server applies to Default: Down
  • Field Name: authentication.scope
  • Type: String
  • Default: Down
  • Choices: ["Current hierarchy level only", "Current hierarchy level and below"]
User Sync Type Type of users that can authenticate against this server. Default: Synced_only
  • Field Name: authentication.user_type
  • Type: String
  • Default: Synced_only
  • Choices: ["LDAP synced users only", "All users"]
Authentication Enabled Authentication Enabled Default: True
  • Field Name: authentication.auth_enabled
  • Type: Boolean
  • Default: True
Ext
  • Field Name: ext
  • Type: Object
LDAP Server The assoicated LDAP server host.
  • Field Name: ext.host
  • Type: String
  • MaxLength: 1024
Port The assoicated LDAP server port.
  • Field Name: ext.port
  • Type: String
  • MaxLength: 1024
Search_Base_Dn The assoicated LDAP server Search Base Dn.
  • Field Name: ext.search_base_dn
  • Type: String
  • MaxLength: 1024
Unique ID This is an auto-generated internal identifier that does not need to be explicitly initialized. Default: Auto generated
  • Field Name: ext.uniqueId
  • Type: String
  • Default: Auto generated
  • MaxLength: 1024
AD Sync Mode * The mode in which users will be synced from the LDAP server. Currently, only Direct sync from the LDAP server is supported.
  • Field Name: ext.adSyncMode
  • Type: String
  • MaxLength: 1024
  • Choices: ["Direct"]
Organization ID The organization ID assigned to the tenant in the Common Identity Store. This is not used currently and does not need to be initialized.
  • Field Name: ext.organizationID
  • Type: String
  • MaxLength: 1024
CUCM LDAP Directory Name The name of the LDAP Directory configured on CUCM that we want this user to be considered synced from. The LDAP Directory must be configured on CUCM already. 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.
  • Field Name: ext.cucmLdapDirectoryName
  • Type: String
  • MaxLength: 1024
Ldapsynclist
  • Field Name: ldapsynclist
  • Type: Object
Note Note about certain fields that will always get synced.
  • Field Name: ldapsynclist.note
  • Type: String
LDAP Sync List Option LDAP Sync List Option. Please Note: LDAP server sync will allways sync in the following attributes, regardless of whether they are explicitly set in the sync list or not. (sAMAccountName, userPrincipalName, mail, cn, uid, description) Default: none
  • Field Name: ldapsynclist.ldap_sync_list_option
  • Type: String
  • Default: none
  • Choices: ["No sync list - all fields will be synced", "Create sync list manually", "Create sync list from template"]
LDAP Sync List Template LDAP Sync List Template. A template contains a predefined list of fields that is normally used when syncing in LDAP servers.
  • Field Name: ldapsynclist.ldap_sync_list_template
  • Type: String
LDAP Sync List Template Flag Flag to see if we need to show the LDAP Sync List Template field
  • Field Name: ldapsynclist.ldap_sync_list_template_flag
  • Type: Boolean