[Index]

Model: relation/HcsLdapServerREL

LDAP Server

Full HTML Help

Add LDAP Server

This procedure adds and configures a LDAP server for integration with Automate.

Note

When integrating with a eDirectory LDAP server, OpenLDAP configuration options are followed, except for the primary key configuration options.

  1. Log in as Provider, Reseller, or Customer administrator.

  2. Set the hierarchy node to the node where you want to sync in users from LDAP to Automate.

  3. Go to (default menus) LDAP Management > LDAP Server.

  4. Click Add.

  5. Configure the LDAP server. See Configure LDAP Server in this guide.

  6. Click Save.

  7. Test the connection to the LDAP server.

    If the authentication credentials or search base DN are invalid, the system displays an error, for example:

    Error encountered while processing your request

    caught exception: [Helper] validation failed; Invalid search base db.

Configure LDAP Server

Fill out fields on the LDAP Server page when adding or updating the LDAP server.

This page contains the following tabs/panels:

Base Tab / Panel

Field Description
Description Defaults to the current hierarchy level.
Host Name * Mandatory. Hostname or IP address of the LDAP server.
Port Port number for LDAP traffic. Defaults to 389.
User DN *

Mandatory. The User Distinguished Name of an admin user that has access rights to the Base DN on the LDAP server.

Examples:
Admin Password * Mandatory. Admin password associated with the user.
Search Base DN *

Mandatory. 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 (OU). For example, to search within an OU called CUS01 under a domain called GCLAB.COM, the Search Base DN would be OU=CUS01,DC=GCLAB,DC=COM.

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 * Either 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, Automate user management allows for the management of users on the LDAP server (add, modify, delete).
Field Description
CUCM LDAP Directory Name

Optional. 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. While this parameter is optional, note the following when this parameter is not set:

  • In a top-down scenario, users are added to CUCM as Local Users
  • In a bottom-up sync scenario, users won't be able to log on to Automate
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 unchecked, 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 Defines whether 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.

Note

From v21.4-PB5, Automate introduced support for syncs from an eDirectory LDAP server configured as an OpenLDAP server type, and allows the use of an OctetString-formatted GUID primary key (pk) instead of the entryUUID attribute.
Authentication Scope Hierarchical scope this server applies to: Local authentication or Full tree authentication. [1]
User sync type

Choose the type of users that can authenticate against this server - options are:

  • 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 Defines whether the server is available for authentication. Default is True.

Search Filter examples:

User lookup for LDAP authentication is restricted to the device/ldap model specified in the Authentication Attribute: Model Type. For example, if this attribute was device/ldap/user, the LDAP user authentication is restricted to (objectClass=user).

Related Topics

[1]For details around authentication scope, see User Login Options by Authentication Method and Server Authentication Scope.

Sync List Tab / Panel

A sync list improves performance, and limits sync attributes to those relevant to your scenario.

On this tab you can choose a LDAP sync list option, when adding a new LDAP server or when updating an existing LDAP server (one that was added prior to release 19.3.4).

Important

The following attributes are always synced in, regardless of the sync list option you choose:

The table describes the LDAP sync list options you can choose on this tab:

LDAP Sync List Option Description
No sync list - all fields will be synced LDAP sync is not driven by a LDAP sync list. All fields are imported (as they were 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 LDAP Sync Lists.
Create sync list from template

Displays an additional field on the tab (LDAP Sync List Template) and allows you to choose a sync list from a predefined configuration template (CFT).

Automate provides default Sync List CFTs for the following:

  • Microsoft AD servers
  • OpenLDAP servers

These CFTs contain LDAP attributes that are typically required to be synced with LDAP. Once you've applied the template, or if a template is not used, a sync list is visible and configurable directly on a saved LDAP server's Sync List tab. See LDAP Sync Lists.

LDAP Server

Full HTML Help

Add a LDAP Server

This procedure adds and configures a LDAP server for integration with VOSS Automate.

  1. Log in as Provider, Reseller, or Customer administrator.

  2. Set the hierarchy node to the node where you want to sync in users from LDAP to VOSS Automate.

  3. Go to (default menus) LDAP Management > LDAP Server.

  4. Click Add.

  5. Fill out the fields on the Base tab.

  6. Optionally, on the Sync List tab, if you choose LDAP sync list option Create sync list from template, you can choose a LDAP sync list template (based on the server type) - either of these:

    You can choose a template when adding the LDAP server, or update your choice after saving. If you don't choose a template, LDAP sync is not affected by this list. See the tab description, and:

  7. Click Save.

  8. Test the connection to the LDAP server.

    If the authentication credentials or search base DN are invalid, the system displays an error, for example:

    Error encountered while processing your request

    caught exception: [Helper] validation failed; Invalid search base db.

LDAP Server Page Field Reference

This page contains the following tabs:

Base Tab

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.
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 Automate user management allows for the management of users on the LDAP server (add, modify, delete).
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 VOSS Automate 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. [1]
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:

User lookup for LDAP authentication is restricted to the device/ldap model specified in the Authentication Attribute: Model Type. For example, if this attribute was device/ldap/user, the LDAP user authentication is restricted to (objectClass=user).

Related Topics

[1]For details around authentication scope, see User Login Options by Authentication Method and Server Authentication Scope.

Sync List Tab

On this tab you can choose a LDAP sync list option, when adding a new LDAP server or when updating an existing LDAP server (one that was added prior to release 19.3.4).

Note

A sync list improves performance, and limits sync attributes to those relevant to your scenario.

Important

A note on this tab warns that the following attributes are always synced in, regardless of the sync list option you choose:

The table describes the LDAP sync list options you can choose on this tab:

LDAP Sync List Option Description
No sync list - all fields will be synced LDAP sync is not driven by a LDAP sync list. All fields are imported (as they were 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 LDAP Sync Lists.
Create sync list from template

Displays an additional field on the tab (LDAP Sync List Template) and allows you to choose a sync list from a predefined configuration template (CFT).

VOSS Automate provides default Sync List CFTs for the following:

  • Microsoft AD servers
  • Open LDAP servers

These CFTs contain LDAP attributes that are typically required to be synced with LDAP. Once you've applied the template, or if a template is not used, a sync list is visible and configurable directly on a saved LDAP server's Sync List tab. See LDAP Sync Lists.

LDAP Authentication

Full HTML Help

VOSS Automate supports LDAP authentication and can be used either standalone (LDAP Authentication only) or in conjunction with LDAP syncing of users:

LDAP sync and authentication
  • Users are synced in from LDAP.
  • LDAP authenticates these users.
  • LDAP user sync is available for Active Directory (AD) and OpenLDAP.
LDAP authentication-only (standalone)
  • Users are added locally or are synced in from CUCM.
  • LDAP authenticates these users.
  • Not available for OpenLDAP.
  • Requires VOSS Automate version 10.6(3) or later.

Note

LDAP authentication workflow

  1. User provides their credentials in the VOSS Automate system Login page.

  2. Authentication request is sent to the relevant LDAP server(s), based on the user's authentication setup:

    Default authentication setup

    Matching username and password

    • VOSS Automate username and password must match the username and password in the LDAP server (based on the LDAP field chosen for username).
    • Once authenticated, the LDAP username is mapped to VOSS Automate user to determine access, role, and so on.
    Alternative authentication setup

    Non-matching username and password

    VOSS Automate supports authentication for mapping non-matching usernames. This is useful where the username in VOSS Automate and the UC apps is different to the username in LDAP. For example, if the LDAP username is bobsmith but the username in VOSS Automate is bsmith, then choose LDAP as the authentication type and set the LDAP username (bobsmith in this case) to match the username of bsmith in VOSS Automate. You would do this via the LDAP authentication attribute, such as sAMAccountName, mail, or userPrincipalName (which define the field where the username is sourced from, and which is used to authenticate the user.)

Note

For LDAP authentication, the password rules of the VOSS Automate credential policy don't apply as the password is managed in the LDAP directory. Other credential policy rules are applied (such as session length), as these are managed in VOSS Automate.

Related Topics

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
Enable Write Operations Enables Add, Modify and Delete operations for users on the the LDAP server.
  • Field Name: allow_write_back
  • Type: Boolean
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
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: /api/data/File/choices/?format=json&hierarchy=[hierarchy]&auth_token=%3D%3D%24DWKTTfbtoLmYcNyz%24YuFY67xpC/2bWWp2hrtpfhCykLKLFyCYh%2BLL2nS8f%2BJHshyu161B00taJ28sMA1TdZmCZupdF9PTZ%2BdP1liAds2Bd/AX4XX3UOvyAfg5/NJXE%2BlRezhC5jfcEt9nR9S7KgtSWhBFs2/PEEpmqNfDKGktlG%2BI0yVErEoS8uZ7zW%2BeVGMXJWbva9n/4Rnw8UJBSNseRlyz9bkm%2B0K90KBEcW14cLUkQIaG/Y7BxJzWv7dwzzz8s4h%2B9rKIh1glF%2BiXXUCiMKJCzcMZa7J2v3x%2BzZM573mDz%2B2jmdyZF3J1v%2Bie4P/isT8eTFO0nvpg1R3akCBj4GF2DT7wHXqG55qj9HEl5v5aVYqtxEWxAoEIuacPOAUhmdokmkxiU3/MQ2w3/2KrE7SKlJfXj5qG5MnZwY2qPWj/9AVFcffxL8WaNtKY34ffg1LsBPdBDBtoRHcCRGCjE6/ubPkVXsfNsf0w6UPbJyc9GUk%2B6yvgzw%3D%3D%24%3D%3D
  • Target Model Type: data/File
  • Format: uri
  • Choices: []
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
  • Target: /api/choices/?format=json&hierarchy=[hierarchy]&auth_token=%3D%3D%24JW5wsN6r3Illyf9z%248BV4VuwMAqY25z0JhnVhUZ%2B8cOKaPwfhMnZILSl4ojX4cAtdqMoILgUgIJwmjWtV%2BRXoV7A8V4tvfUQGQwsDAcoiDZgu6ZfMK2J68ZiCA%2BrbbmViyR3asT4AwyUOTKpxfGt01QEeSLZwM%2BuL/8qs%2BM4yLQazOH%2BltwMzBBagBV5LYILdN%2BrxL70coItjVtBeb%2BU4sYM7KN2TAQJ65xs0NgGc2IU9man5/2JvOJnbkcnzg/7XV0w9hCVZAPMm2O96YNsv3cVG1PoqmJzhYmIH6eL0q2Vs74cOW5jordhTPmbbE9Hdkh4W0rG3E%2B%2Bl8RYgDfymUsggVhsyFdxPKWbwS/OVbc7/bi%2BBfYjLgsORDhMn9sagOU5UtPWytOUG%2B%2B20zCEbPLjf5KJxicACUewtxdYv5zIJBjcf2RTX16ZeqEeYL1cKdRPepsJMkmNKPM0uDnyCUvkx6mRVvt%2BLFVUuo0Ep%24%3D%3D
  • Format: uri
  • Choices: []
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 always 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