Synchronizing Data Through LDAP

LDAP is a lightweight directory access protocol. LDAP can be considered a tree-like database that stores user and organization information. One of the main application scenarios of LDAP is SSO where users are automatically logged in to intranet of their company after logging in on a PC for once.

**Table 1** Terms
Term	Description
ou	Organization unit (ou), which is a container object.
dc	Domain component (dc), which is a part of a domain name. A domain name is divided into several parts.
sn	Short for surname.
cn	Short for common name.
dn	Short for distinguished name. A dn must be unique.
uid	Short for user ID.
rdn	Relative distinguished name (RDN) is similar to the relative path in a file system.

This section describes how to synchronize organization and user data to OpenLDAP through the LDAP protocol.

Configuration Process

Prerequisites

You have permissions to access the administrator portal.

Deploying and Configuring the LDAP Service

Deploy and configure the LDAP service. For details, see Setting Up an LDAP Server and Configuring LDAP Connection.

Adding an Application

Log in to the administrator portal.
On the top navigation bar, choose Resources > Applications.
Click Add Custom Application in the Custom Applications section, set the logo and application name, and click Save.

Configuring the Application

Click the application added in Adding an Application.
In the General Information area, click next to Synchronization to enable synchronization, select LDAP, and click Save.

The protocol cannot be changed once specified.

In the General Information area, click Configure next to Synchronization to access the configuration page.

Figure 1 Configuring synchronization parameters

**Table 2** Common parameters
Parameter	Description
* Host	Host name or IP address of the LDAP server. NOTE: OneAccess can be accessed only over public networks. Provide the public network address of your LDAP server.
*TCP Port	TCP/IP port of the LDAP server. The default port is 636.
SSL	Default value: true, which indicates that SSL is used to connect the LDAP server.
StartTLS	Whether to enable startTLS for encrypted communication. true: StartTLS is enabled, and SSL cannot be set to true. false: StartTLS is not enabled. If data is synchronized to the AD server, either SSL or StartTLS must be enabled.
Verifying certificate	Whether to verify the certificate. This parameter is valid only when SSL or StartTLS is set to true. true: Verify the certificate. false: Do not verify the certificate. The certificate must be authenticated by the public network. Self-signed certificates cannot be used.
Protocol Version	Default value: TLSv1.2. Recommended: TLSv1.3 and TLSv1.2.
* Principal	Identifier used for LDAP server authentication, for example, cn=admin, cn=test, and cn=com.
* Password	Password of the principal.
* Base Contexts	Root node in the LDAP directory to be synchronized.
UID Attribute	Name of the LDAP attribute mapped to the UID attribute. Default value: entryUUID.
Account Object Classes	One or more object classes to be used when a new user object is created in the LDAP tree. If you enter multiple object classes, each item occupies a line. Do not use commas (,) or semicolons (;) to separate multiple object classes. Some object classes may require you to specify all object classes in the class hierarchy. The default value is top, person, organizationalPerson, or inetOrgPerson.

**Table 3** Optional parameters
Parameter	Description
Domain Name	If a domain name exists, it should be excluded from the reclaimed username. If there are multiple domain names, separate them with commas (,). The default user name excludes the domain name.
Account Username Attributes	Saves one or more attributes of an account user name. During authentication, these attributes are used to search for the LDAP entry of the username to be authenticated. The default value is uid and cn.
Organization Object Classes	One or more object classes to be used when a new organization object is created in the LDAP tree. If you enter multiple object classes, each item occupies a line. Do not use commas (,) or semicolons (;) to separate multiple object classes. Some object classes may require you to specify all object classes in the class hierarchy. The default value is top and organizationalUnit.
Organization Name Attributes	Stores one or more attributes of the organization name. During authentication, these attributes are used to search for the LDAP entry of the organization name to be authenticated. The default value is ou.
Failover Servers	Lists all servers that will be used for failover when the preferred server fails. If the preferred server fails, JNDI will connect to the next available server in the list. Lists all servers in the "ldap://ldap.example.com:389/" format (compliant with the standard LDAP v3 URL described in RFC 2255). Only the host and port parts of the URL are relevant in this setting.
Password Attribute	Name of the LDAP attribute used to store passwords. When the password of a user is changed, a new password will be set for this attribute. The default value is userPassword. If the password is synchronized to the AD server, set this parameter to unicodePwd.
LDAP Filter	Optional LDAP filter used to control the accounts returned from LDAP resources. If no filter is specified, only accounts containing all specified object classes are returned.
Password Hash Algorithm	Algorithm used by the identity system to hash passwords. Currently, SSHA, SHA, SMD5, and MD5 are supported. A null value indicates that the system does not hash the password. Unless the LDAP server performs hashing (Netscape Directory Server and iPlanet Directory Server perform hashing), this will result in plaintext passwords being stored in LDAP.
Respect Resource Password Policy Change-After-Reset	If this resource is specified in the login module (i.e., this resource is the passing verification target) and the password policy of the resource is configured to change after reset, users who have reset the resource account password for management purpose need to change the password after successful verification. The default value is false.
Use VLV Controls	Whether to force the use of VLV controls on standard LDAP controls. The default value is false.
VLV Sort Attribute	Sorting attribute used for VLV indexes on resources. Default value: uid.
Read Schema	If the value is true, the connector reads the schema from the server. If false, the connector provides a default schema based on the object class in the configuration. To use the extended object class, this attribute must be set to true. The default value is true.
Base Contexts to Synchronize	One or more starting points in the LDAP tree that are used to determine whether changes should be synchronized. If this attribute is not set, the base context attribute is used to synchronize changes.
Object Classes to Synchronize	Object classes to be synchronized. The change log is for all objects; it filters updates based on the listed object classes. You should not list the superclasses of an object class unless you want to synchronize the object with any superclass value. For example, if only the inetOrgPerson object should be synchronized, but the superclasses (person, organizationalperson, and top) of inetOrgPerson should be filtered out, only inetOrgPerson should be listed here. All objects in LDAP are derived subclasses of top. Therefore, top should never be listed. Otherwise, no object can be filtered. The default value is inetOrgPerson.
Attributes to Synchronize	Name of the attribute to be synchronized. When this option is set, if updates in the change log do not update any named attributes, these updates are ignored. For example, if only department is listed, only changes that affect department are processed and all other updates are ignored. If you leave it blank (default setting), all changes are processed.
LDAP Filter for Accounts to Synchronize	Optional LDAP filter used for synchronizing objects. Because the change log applies to all objects, this filter updates only the objects that meet the specified filter criteria. If a filter is specified, the object is synchronized only when the object meets the filter conditions and contains the synchronized object class.
Change Log Block Size	Number of change log entries obtained by each query. The default value is 100.
Change Number Attribute	The name of the change number attribute in the change log entry. The default value is changeNumber.
Filter with Or Instead of And	Typically, the filter used to obtain change log entries is to retrieve change entries over a period of time based on the AND condition. If this attribute is set, the filter filters with the OR condition instead with the required number of changes. The default value is false.
Remove Log Entry Object Class from Filter	If this attribute is set (default), the filter used to obtain change log entries will not contain the changeLogEntry object class because the change log should not contain entries of other object classes. The default value is true.
Password Attribute to Synchronize	Name of the password attribute to be synchronized during password synchronization.
Status Management Class	Class used to manage the enabling/disabling status. If no class is specified, identity status management cannot be performed.
Retrieve Passwords with Search	Whether to retrieve the user password during search. The default value is false.
DN Attribute	DN attribute name of an item. The default value is entryDN.
LDAP Filter	Optional LDAP filter that controls the groups returned from LDAP resources. If no filter is specified, only groups containing all specified object classes are returned.
Read Timeout (ms)	Time for waiting for a response. If no response is received within the specified time, the read attempt is aborted. If the value is 0 or less than 0, there is no limit. The default value is 30000.
Connection Timeout (ms)	Waiting time for opening a new server connection. The value 0 indicates that the TCP network timeout will be used, which may be several minutes. If the value is less than 0, there is no limit. The default value is 6000.
Account DN Prefix	If the value is empty, the default value cn is used. You can also set the value to another attribute name used as the DN prefix, such as uid.

Once configured, click Save. To test the connectivity, click Test.
Click the General tab. On the displayed page, set synchronization data processing logic for Account Deletion, Organization Deletion, Account Deactivation, and Organization Deactivation. Then select Enable to apply the synchronization data processing logic.

To synchronize other user attributes, choose Object Models > Application Accounts in the left pane, click the Attributes tab, and click Add to add more attributes. For details, see Table 4. employeeNumber is used for illustration.

Built-in attributes can be modified but cannot be deleted.
Modify or delete non-built-in attributes by clicking Modify or Delete in the Operation column.

**Table 4** Attributes
Parameter	Description
Attribute	Account attribute of the application system, for example, employeeNumber.
Label	Identifier of an attribute name. It is recommended that the value of this parameter match that of Attribute.
Description	Description of Attribute.
Attribute Type	Type of an attribute. You can select a value from the drop-down list box.
Format	This parameter specifies the text format. It can be set only when Attribute Type is set to Text.
Required	If this option is selected, the attribute must be set when user data is synchronized to an application. If the attribute is left blank, a prompt message is displayed.
Unique	It can be set only when Attribute Type is set to Text. If this option is selected, the attribute value is kept unique when user data is synchronized to an application. If the attribute is duplicate, a prompt message is displayed.
Sensitive	It can be set only when Attribute Type is set to Text. If this option is selected, the user data is hidden when it is synchronized to an application. You can click to view the content.

After you have finished setting the parameters, click Save.

Switch to the Mappings tab page, click Modify, and configure attribute mappings.

**Table 5** Mappings
Parameter	Description
User	Attribute that OneAccess will map to the application, for example, mobile number.
Conversion Mode	Attribute mapping mode.
Script Expression	Enter a script if you specify the conversion mode as Script-based. For details about mapping scripts, see Developing Mapping Scripts.
Execution Mode	Operation to be performed when user data is synchronized from OneAccess to the target application.
Application Accounts	Account attribute of the application.

To synchronize organizations, choose Object Models > Application Organization Model, and click to enable the application organization model. The model cannot be disabled once enabled.
- Built-in attributes can be modified but cannot be deleted.
- Modify or delete non-built-in attributes by clicking Modify or Delete in the Operation column.

To synchronize other organization attributes, choose Object Models > Application Organization in the left pane, click the Attributes tab, and click Add to add more attributes. For details, see Table 6.

**Table 6** Attributes
Parameter	Description
Attribute	Attribute name of an application organization.
Label	Identifier of an attribute name. It is recommended that the value of this parameter match that of Attribute.
Description	Description of Attribute.
Attribute Type	Type of an attribute. You can select a value from the drop-down list box.
Format	This parameter specifies the text format. It can be set only when Attribute Type is set to Text.
Required	If this option is selected, the attribute must be set when organization data is synchronized to an application. If the attribute is left blank, a prompt message is displayed.
Unique	It can be set only when Attribute Type is set to Text. If this option is selected, the attribute value is kept unique when organization data is synchronized to an application. If the attribute is duplicate, a prompt message is displayed.
Sensitive	It can be set only when Attribute Type is set to Text. If this option is selected, the organization data is hidden when it is synchronized to an application. You can click to view the content.

After you have finished setting the parameters, click Save.

Switch to the Mappings tab page, click Modify, and configure attribute mappings. For details, see Table 7.

**Table 7** Mappings
Parameter	Description
Organization	Organization attribute in OneAccess that will be mapped to the application.
Conversion Mode	Attribute mapping mode.
Script Expression	Enter a script if you specify the conversion mode as Script-based. For details about mapping scripts, see Developing Mapping Scripts.
Execution Mode	Operation to be performed when organization data is synchronized from OneAccess to the target application.
Organization	Organization attribute of an application.

Verifying Data Synchronization to OpenLDAP

On the application details page, choose Authorization > Application Organizations in the left pane. Click Authorization Policy, enable automatic organization authorization, select organizations to be synchronized, click Save, and then click Add.
- To delete synchronized organizations, deselect the organizations, click Save, and then click Delete.
- To add a virtual organization, click in the page.
Figure 2 Authorizing organizations
In the left pane, choose Authorization > Application Accounts. Then click Add Accounts to authorize specific users to access the application. To authorize access using a policy, see the descriptions about the application account authorization policy in Configuring an Application.

Figure 3 Adding accounts
Choose Authorization > Synchronization Events in the left pane, and view the synchronization records. You can view and filter the organization and user modification and deletion records.

Figure 4 Viewing the synchronization events
View the synchronized data in LDAP.