From ServiceNow Wiki

LDAP Integration
LDAP Integration Setup Uploading a Certificate Setting Up the LDAP Transform Map Record Creation Options During an LDAP Transform LDAP Integration Troubleshooting LDAP Error Codes Active Directory (AD) Topics Configuring Microsoft Active Directory for SSL Access Using ADAMSync To Populate ADAM LDAP Using Global Catalog OpenLDAP Minor Schema Modification
Related Topics
Integration Overview
Get the Book
Get the Book

1 Overview

Administrators typically enable an LDAP integration to allow single sign-on of ServiceNow users from their company LDAP directory.

2 LDAP Configuration Workflow

Enabling an LDAP integration involves:

1. Determining how LDAP communicates with ServiceNow.
2. Uploading certificates, if necessary.
3. Defining an LDAP server in ServiceNow.
4. Providing LDAP login credentials.
5. Setting LDAP connection properties.
6. Testing the LDAP connection.
7. Defining LDAP organizational units (OUs).
8. Creating import set table data source.
9. Mapping imported data into ServiceNow tables using a transform map.
10. Scheduling an import.

2.1 Step 1. Determine the LDAP Communication Channel

LDAP typically uses one of these types of communication channels:

• A standard LDAP integration communicates over TCP on port 389 by default. This communication channel does not require a certificate.
• An SSL-encrypted LDAP integration (LDAPS) communicates over TCP on port 636 by default, This communication channel requires a certificate. Go to Step 2 to obtain and upload the certificate.
• A VPN connection communicates over an IPSEC tunnel. Purchase or create an IPSEC tunnel on your local network.

2.2 Step 2. Upload the X.509 Certificate

If an administrator has not already uploaded a certificate as part of ServiceNow Go Live activities:

1. Purchase or generate an SSL certificate on your Active Directory server.
2. Upload the LDAP certificate.

2.3 Step 3. Define the LDAP Server

To create a new LDAP server record in ServiceNow:

1. Navigate to System LDAP > Create New Server.
2. Specify the values in the connection settings, as described in the table.
3. Click Submit.

The New LDAP Server form contains these fields:

To modify an existing LDAP server record:

1. Navigate to System LDAP > LDAP Servers.
2. In the list of servers, select the existing LDAP server to change.
3. Specify the values in the connection settings.
4. Click Update.

2.3.1 Specify Redundant LDAP Servers

Administrators can specify multiple servers in the Server URL field to list their network's redundant LDAP servers. Separate each URL address with a space character. The instance searches for an available LDAP server in the order in which the LDAP servers are listed.

2.3.2 Enable SSL

If the LDAPS integration uses the default SSL port of 636, no further configuration is necessary; SSL is automatically enabled. If the LDAPS integration uses another SSL port, define the alternate SSL connection properties:

1. Navigate to System LDAP > LDAP Servers and select the LDAP server to configure.
2. Under Related Links, click Advanced view.
3. In the Server URL field, specify the LDAP IP address and alternate SSL communications port.
4. Select the SSL check box.
5. Click Update.

Note: Be sure a network administrator configures the local firewall to allow the application server to access the LDAP server. If the LDAP server is located within an internal network, the firewall forwards (or NATs) the application server's IP address through the firewall on the correct port.

2.4 Step 4. Provide LDAP Server Login Credentials

The LDAP login credentials determine what organizational units the integration can see. Servers that do allow anonymous login generally limit the OU data available to anonymous connections.

1. Navigate to System LDAP > LDAP Servers.
2. Select an LDAP server record to modify.
3. In Login distinguished name, enter the user credentials for an account with read access to the directory levels from which you want to import users and/or groups. ServiceNow uses these credentials to connect to your LDAP server. If this information is not entered, the ServiceNow application attempts an anonymous login to the LDAP server.

   The Login distinguished name fields accepts several formats.

   To access a Microsoft Active Directory (AD) server, use one of the following:

   user@domain.com, domain\user

   cn=user,ou=users,dc=domain,dc=com>

   To access a different LDAP directory, the username must be in the full distinguished name format:

   cn=user,ou=users,dc=domain,dc=com

4. In Login password, enter the password for the LDAP user.
5. Select the Active check box.
6. (Optional) In the Starting search directory field, explicitly specify the LDAP OU attributes you want the ServiceNow instance to import.
7. Click Update.

Note: If you provide an LDAP password, the integration performs a Simple Bind operation. If you do not provide an LDAP password, the LDAP server must allow anonymous login or the integration cannot bind to the LDAP server.

2.4.1 (Optional) Enable a Listener

A listener is a dedicated process that periodically searches for changes on the LDAP server. When enabled, a listener notifies ServiceNow to to process LDAP records soon after there is an update on the LDAP server.

Note: The Listener requires a Microsoft Active Directory server that supports persistent queries (ADNotify)

To enable a listener:

1. Navigate to System LDAP > LDAP Servers.
2. In the list of servers, select the existing LDAP server to change.
3. Select the Listener check box.
4. Click Update.

2.4.2 (Optional) Specify Attributes for Better Performance or Security Considerations

By default, ServiceNow loads all of the attributes for each object that it has permission to read from your LDAP server. By personalizing the LDAP Server form and adding the Attributes field, you can specify (and thereby limit) the attributes the LDAP server query returns. Using this approach for large LDAP imports can greatly improve the speed of those imports. For best results, define attributes where possible. If there is information that you do not want exposed to ServiceNow, exclude the attribute.

Note: To use the manager lookup scripts in Step 9, specify the manager and dn (distinguished name) attributes. Neither attribute is required to be a part of a transform map.

Note: If you do not specify LDAP server attributes, user transactions may freeze for extended periods of time when new attributes are added to an LDAP server object because the system will be busy loading data from the new attributes.

2.5 Step 5. Set Connection Properties

To use LDAP for user authentication:

1. Navigate to System Properties > LDAP .
2. In the Use LDAP for password authentication field, select the Yes check box. If this check box is not selected, LDAP is used only to populate the ServiceNow application with directory information.
3. Click Save.

To set connection properties for a specific LDAP server:

1. Navigate to System LDAP > LDAP Servers.
2. Select an existing LDAP server from the list.
3. Set the connection property fields, as described in the table.
4. Click Update.

Note: If you enable an SSL connection, you can set the read timeout value with the system property com.glide.ssl.read.timeout. See Additional Glide Properties to learn more.

Note: Depending on your environment, you may add other fields not included on the default LDAP Server form.

2.6 Step 6. Test the Connection

After defining an LDAP server, verify that ServiceNow can establish a connection to the LDAP server.

1. Navigate to System LDAP > LDAP Servers.
2. Select the LDAP server to test.
3. Under Related Links, click Test connection.
4. Under Related Links, click Browse to verify that the appropriate LDAP directory structure is visible to ServiceNow.

Note: ServiceNow employees can also verify connectivity between the ServiceNow server and the LDAP server. Contact Customer Support for assistance verifying LDAP connectivity.

2.7 Step 7. Define OUs Within the Server

An OU definition specifies the LDAP source directories available to the integration. OU definitions can contain locations, people, or user groups. Every LDAP server definition contains two sample OU definitions: one for the importing users into the system and the other for groups.

1. Navigate to System LDAP > LDAP Servers.
2. Select the LDAP server to configure.
3. In the LDAP OU Definitions related list, select either the Groups or Users sample OU definition.
4. Complete the LDAP OU Definition form, as described in the table.
5. Click Update.
6. Under Related Links, click Test connection to verify the LDAP connection.
7. Under Related Links, click Browse to view the LDAP directory records the OU definition returns.

(&(objectClass=person)(sn=*)(!(objectClass=computer))(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

2.7.1 Example OU Definitions

Suppose you have an LDAP server with the following directory structure:

• dc=my-domain,dc=com
  • ou=Groups
    • cn=Development
    • cn=HR
    • cn=Sales
  • ou=Users
    • ou=Development
    • ou=HR
    • ou=Sales

Further suppose that you want to exclude the HR group and HR users from ServiceNow.

First, create an LDAP server record with a starting search directory of dc=my-domain,dc=com.

Next, create an OU definition record for ou=Groups with a filter to exclude cn=HR.

Finally, create an OU definition record for ou=Users with a filter to exclude ou=HR.

If you do not specify additional attributes or filters with an OU definition, the LDAP query returns the entire sub-tree from the starting directory and RDN.

In these examples, an OU definition with the RDN value of ou=Groups and no filter would have returned all groups. Likewise, an OU definition with the RDN value of ou=Users and no filter would have returned all users and child organizational units.

2.7.2 (Optional) Filtering for Better Performance

Administrators can use the Filter field to select specific records to import from the OU. The more specific the LDAP filter query, the more efficient the query is. The example Users LDAP OU definition uses this filter to select records that are classified as a person, have an sn attribute value, are NOT computers and are NOT flagged as inactive.

(&(objectClass=person)(sn=*)(!(objectClass=computer))(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

2.8 Step 8. Create a Data Source

Each LDAP OU definition has its own related list of data sources.

To create a new data source:

1. Navigate to System LDAP > LDAP Servers.
2. Select the LDAP server to configure.
3. In the LDAP OU Definitions related list, select an item, such as Groups or Users.
4. In the Data Sources related list, click New.
5. Complete the Data Source form, as described in the table.
6. Click Submit.
7. Under Related Links, click Test Load 20 Records to test whether the data source can bring LDAP data into the import table.

Note: Both the LDAP Server and LDAP OU Definition must be active for the test load action to function properly.

Note: During the first import, ServiceNow samples up to 20 records to determine the length of the import set fields. If the sampled records do not contain values for the User ID field, ServiceNow sets the field length to the default length of 40. The import truncates any imported data that exceeds the import set table field length.

2.9 Step 9. Create a Transform Map for LDAP Data

The transform map moves data from the import set table to the target table (User or Group). The LDAP integration uses standard import sets and transform maps, but there are some mapping features unique to transforming LDAP data.

Note: By default, ServiceNow does not have a transform map for LDAP department records.

If an LDAP attribute contains simple data, then the transform map links an imported LDAP attribute to an appropriate field in the target table (User or Group). For example, simple data in the sAMAccoutName attribute maps to the User ID field in the User table.

If the imported LDAP data maps to a reference field, ServiceNow searches for an existing matching record. If no matching record exists, ServiceNow creates a new record for the reference field unless the field mapping specifies otherwise (see Record Creation Options During an LDAP Transform).

For example, suppose the LDAP attribute l maps to the Location reference field in the User table. Whenever the import brings in an attribute value that does not match an existing Location record value, the transform map creates a new Location record. The new Location record has the same value as the imported attribute, and the imported User record now has a link to the new Location record.

However, there are times when LDAP attribute returns a distinguished name (DN), which is essentially a reference to another record within the LDAP directory. For example, the manager attribute typically contains the distinguished name for the manager of the current LDAP directory entry. An imported DN typically has uses a long text string such as: cn=Beth Anglin,ou=Users,dc=my-domain,dc=com.

Warning: Make sure your target fields are long enough to contain a DN. Many text fields use the default length of 40, which may not be long enough for some DN values. ServiceNow truncates any value that exceeds the field length.

2.9.1 Searching for Existing Reference Field Values

Administrators do not typically want ServiceNow to create new users from the DN value because the new user has no association with an existing ServiceNow user. Instead, administrators want the import to locate the manager's existing ServiceNow user record and associate it with the newly imported user. The LDAPUtils script include contains the setManager and processManagers functions that can parse a DN and searches for an existing ServiceNow user. For best results, use these functions to create a custom transform map.

For example, the LDAP User Import transform map script calls the setManager function:

//
// The manager coming in from LDAP is the DN value for the manager.  
// The line of code below will locate the manager that matches the
// DN value and set it into the target record.  If you are not 
// interested in getting the manager from LDAP then remove or
// comment out the line below
ldapUtils.setManager(source, target);

In some cases, the integration imports a user's record before importing the associated manager's user record. To handle such cases, you may want to call the processManagers function after the transform completes. For example, the LDAP User Import transform map uses an onComplete transform script to call the processManagers function.

// It is possible that the manager for a user did not exist in the database when
// the user was processed and therefore we could not locate and set the manager field.
// The processManagers call below will find all those records for which a manager could 
// not be found and attempt to locate the manager again. This happens at the end of the 
// import and therefore all users should have been created and we should be able to 
// locate the manager at this point 
ldapUtils.processManagers();

Remove or comment out the setManager and processManagers function calls if your LDAP integration does not use the manager attribute.

2.9.2 Add onStart and onAfter scripts

Any custom transform map should include onStart and onAfter scripts.

The onStart script should call the LDAPUtils script include and start logging. For example, the LDAP User Import transform map has an onStart script that uses this code:

gs.include("LDAPUtils");
 var ldapUtils = new LDAPUtils();
ldapUtils.setLog(log);

The onAfter script should call the addMembers function. For example:

ldapUtils.addMembers(source, target);

2.10 Step 10. Create and Execute a Scheduled Import

A scheduled import is a common part of the import set functionality that allows administrators to import LDAP data on a regualr schedule. By default, the LDAP integration includes two sample scheduled imports:

• Example LDAP User Import
• Example LDAP Group Import

Neither example is active by default. Change these scheduled imports to meet your company's business needs.

3 Test the LDAP Integration

Verify that the LDAP integration connects to the LDAP server and imports and transforms LDAP attributes as expected. See the LDAP Integration Troubleshooting page to fix any problems you encounter.