LDAP Integration Setup

From ServiceNow Wiki
Home > Integrate > Single Sign-On > LDAP > LDAP Integration Setup (Redirected from LDAP Integration Configuration)
Jump to: navigation, search
Note
Note: The latest release this documentation applies to is Fuji. For the Helsinki release, see LDAP Integration Setup. Documentation for later releases is also on docs.servicenow.com.

1 Overview

Starting in Dublin, Administrators can enable an LDAP integration to allow single sign-on of ServiceNow users from their company LDAP directory. The procedures on this page guide you through the process of setting up an LDAP integration.

After the integration, the MID Server connects to the instance and the MID Server also connects to the LDAP server. In both cases, the MID Server initiates the connection:

  • The MID Server connects to the LDAP server via LDAP on Port 389.
  • Then the MID Server initiates an HTTPS encrypted connection to the instance on Port 443 to push the data to the instance.

2 Determine the LDAP Communication Channel

LDAP typically uses one of these types of communication channels:

  • A MID Server connection communicates over HTTP on port 80 by default. This communication channel does not require a certificate. The connection between the MID Server and the instance is over HTTPS (port 443). You can use the MID Server to import data over LDAP, but you cannot use the MID Server for LDAP authentication. Proceed to Define the LDAP Server.
  • A standard LDAP integration communicates over TCP on port 389 by default. This communication channel does not require a certificate. Proceed to Define the LDAP Server.
  • An SSL-encrypted LDAP integration (LDAPS) communicates over TCP on port 636 by default, This communication channel requires a certificate. Proceed to Upload the X.509 Certificate to obtain and upload the certificate.
  • A VPN connection communicates over an IPSEC tunnel. Purchase or create an IPSEC tunnel on your local network. Proceed to Define the LDAP Server.

A MID server initiates one connection to an LDAP server via port 398, then initiates an encrypted HTTPS connection to an instance via port 443 to push data to the instance. When using a MID server, the instance does not make the connection to the LDAP server. The MID server does.

The instance can also connect to the LDAP server directly, using LDAP or LDAPS, either over the internet or through a VPN tunnel.

For more information about VPNs, Mid Servers, and LDAP, see You Don't Need A VPN Part II on the ServiceNow Community.

3 Upload the X.509 Certificate

If your administrator is setting up an SSL-encrypted LDAP integration (LDAPS) to communicate over TCP on port 636, and has not already uploaded a certificate as part of ServiceNow Go Live activities:

  1. Purchase or generate an SSL certificate on your LDAP server.
  2. Upload the LDAP certificate to ServiceNow.

4 Define the LDAP Server

To create a new LDAP server record:

  1. Navigate to System LDAP > Create New Server.
  2. Fill in the form fields. See Set Connection Properties for field descriptions.
  3. Click Submit.
Creating a new LDAP server record

4.1 Specify Redundant LDAP Servers

Administrators can specify redundant servers from either the Create New Server module or from an individual LDAP Server record. The LDAP integration can use one of these servers if the primary LDAP server experiences a service interruption.

To specify one or more redundant LDAP servers from the Create New Server module:

  1. Navigate to System LDAP > Create New Server.
  2. Fill out the form as specified in Define the LDAP Server.
  3. In the Server URL field, the valid URLs of all servers appear separated by a space (starting with the Fuji release). Servers are first ordered by operational status, with servers that are Up listed first, then ordered by the Order value that you specify. The first server listed is the primary LDAP server. The others are redundant servers.
    Note: There is a slight delay between the change in the actual operational status and the display.
  4. Enter other LDAP server fields as needed. See Set Connection Properties.
  5. Click Submit.
Entering multiple LDAP servers

To specify one or more redundant LDAP servers from an individual LDAP Server record:

  1. Navigate to System LDAP > LDAP Servers.
  2. Select the LDAP server for which you want to specify a redundant server.
  3. From the LDAP Server URLs embedded list, click Insert a new row.
  4. Fill in the fields for the row (see table).
  5. Right-click the form header and click Save.
  6. Repeat these steps for each additional server you want to specify.
Entering multiple LDAP servers on the embedded list

Field Description
URL The URL or IP address to the redundant LDAP server.
Order The order in which the instance searches for an available LDAP server from lowest value to highest. A business rule automatically populates this value if you leave the field blank.
Active A true/false field indicating whether the LDAP server is available for use as a backup server. Only active servers can be used as backup servers.
Operational Status A read-only true/false field indicating whether the LDAP server is currently available. Only servers that are currently operational can be used as backup servers.

The LDAP Servers embedded list is available starting with Fuji release. If you are using an earlier version, see the previous version information.

4.2 Enable SSL

If you use an LDAPS integration and the default SSL port is 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.
  2. Select the LDAP server to configure.
  3. Under Related Links, click Advanced view.
  4. In the Server URL field, specify the LDAP IP address and alternate SSL communications port.
  5. Select the SSL check box.
  6. Click Update.
Note
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.


5 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 the LDAP server to configure.
  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 or groups. The ServiceNow system 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 server, 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
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.


5.1 Enable a Listener

Enabling a listener is optional. If enabled, a listener notifies the ServiceNow system to process LDAP records soon after there is an update on the LDAP server. See LDAP Listener for more information.

To enable a listener:

  1. Navigate to System LDAP > LDAP Servers.
  2. Select the LDAP server to configure.
  3. Select the Listener check box.
  4. Click Update.
Note
Note: If a user is added via the listener, but the user does not meet the requirements as defined by the OU filter, then the instance ignores the record on the LDAP server. If it meets the criteria, the user is added to the instance.


5.2 Specify Attributes for Better Performance or Security Considerations

By default, the ServiceNow system loads all of the attributes for each object that it has permission to read from your LDAP server. By configuring 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 the ServiceNow system, exclude the attribute. 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.

Note
Note: To use the manager lookup scripts described in Select or Create a Transform Map for LDAP Data, specify manager and dn (distinguished name) in the Attributes field. Neither attribute is required to be a part of a transform map.


LDAP attributes

6 Set Connection Properties

To set connection properties for a specific LDAP server:

  1. Navigate to System LDAP > LDAP Servers.
  2. Select the LDAP server to configure.
  3. Set the connection property fields (see table).
  4. Click Update.
LDAP Server setup

Field Description
Name Enter the name of the server.
Active Select this check box if the server is active.
LDAP Server URLs Enter the URLs of the primary and backup LDAP servers. This field is available starting with the Fuji release. Servers are first ordered by operational status, with servers that are Up listed first, then ordered by the Order value that you specify. The first server listed is the primary LDAP server. The others are redundant servers.
Server URL Enter the URL of the server (prior to the Fuji release). Starting with the Fuji release, this field is not shown on the form by default. Configure the form to add this field if necessary. It is a calculated read-only field that shows the list of LDAP servers that you can also see in the LDAP Server URLs field, separated by a space, and ordered by operational status and the order values of the URLs.
Login distinguished name Enter the distinguished name (DN) of the user authenticating the LDAP connection.
Login password Enter the server's password.
Starting search directory Enter the relative distinguished name (RDN) of the default search directory. All queries to this LDAP server will start from this RDN.
MID Server Select the MID Server you want to use to connect to the LDAP server. Using a MID Server to establish an LDAP connection prevents you from having to expose the LDAP server to external network traffic. It also eliminates the need to establish a VPN tunnel between your LDAP server and ServiceNow data centers.

Notes:

  • The MID Server user must have the user_admin role in order to be able to read LDAP server configuration records.
  • The following are not available with the MID Server:
  • LDAP authentication
  • SSL connection
Connect timeout Specify the maximum number of seconds that the instance has to establish an LDAP connection. If no connection is made by this time, the connection is terminated.
Read timeout Specify the number of seconds the integration has to read LDAP data. The integration stops reading LDAP data after the connection exceeds the read timeout. If you enable an SSL connection, you can also set a read timeout value with the com.glide.ssl.read.timeout system property. If you enter timeout values for both this field and the system property, the lowest timeout value takes precedence. For more information, see Available System Properties.
SSL Select this check box to require the LDAP server to make an SSL-encrypted connection. For more information, see Enable SSL. If you selected a MID Server, this field is not available.
Listener Select this check box to have the instance continually poll Microsoft Active Directory servers, LDAP servers, or MID Servers that support persistent search request control. The instance pools the server for changes to the information specified in the LDAP OU Definitions. If you do not select this option, the LDAP server that you are configuring is used for authentication only.
Listen interval Specify the number of minutes the integration listens for LDAP data with every connection. The integration stops listening for LDAP data after the connection exceeds the listen interval.
Paging Select this check box to have the LDAP server split up LDAP attribute data into multiple result sets rather than submit multiple queries.

6.1 Automatic Validations

When an LDAP Server record is set to active, the system automatically tests every connection to validate it. Validations include:

  • The LDAP server is accessible at the provided URL and port
  • The LDAP server URL is properly formatted
  • The login credentials are valid

If the LDAP servers fail validation, the system displays an error message explaining the failure (prior to the Fuji release). For example:

Sample LDAP server validations prior to the Fuji release

Starting with the Fuji release, the system displays colored dots next to each server URL:

  • Green: The server if active and operational.
  • Gray: The server is neither active nor operational.
  • Red: The server is active but not operational.
Sample LDAP server validations starting with the Fuji release

7 Testing the Connection

You can manually test connection to LDAP servers or allow the ServiceNow system to automatically test the connections.

7.1 Testing the Connection Manually

You can manually test the connection to the LDAP server from the LDAP server form. For versions prior to Dublin, this is the only way to test the connection.

  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 the system.
Note
Note: The Filter and RDN fields on the left of the Browse window are ignored when you use the search field on the right.


7.2 Testing the Connection Automatically

The ServiceNow system tests the connection automatically (starting with the Dublin release):

  • Every time a user opens the LDAP Server form,
  • Through the LDAP Connection Test scheduled job, which runs every 15 minutes by default. You can change how often this scheduled job runs. If this scheduled job is not able to establish a connection, a new one-time schedule job retries the connection test after either five minutes, or half the Repeat Interval value in the scheduled job, whichever occurs first.

Error messages appear on the form if there are any issues connecting to the LDAP server. Connections to redundant servers are also tested starting with the Fuji release. Also supported are test connections for servers behind a MID server.

7.3 LDAP Connection Monitoring and Notification

The ServiceNow system automatically sends an email to users configured in the LDAP Admins group when an LDAP server connection fails, starting with the Dublin release. This uses the LDAP Connection Failed email notification, which is launched by the LDAP Connection Test scheduled job. This email notification is enabled by default.

Note
Note: The ServiceNow system does not send the email notification unless there is at least one member in the LDAP Admins group. Make sure to populate this group with the users you want to receive the email.

7.3.1 Modifying the LDAP Connection Test Scheduled Job

To change how often the scheduled job tests connections or to disable the scheduled job:

  1. Navigate to System Definition > Scheduled Jobs.
  2. Open LDAP Connection Test.
  3. Do one of the following:
    • Change the interval in the Repeat Interval field.
    • Disable monitoring by clearing the Active check box.

7.4 Automatic Operational Status Update

The instance changes the Operational Status value depending on the result of the connection test:

  • If your instance establishes a connection to a server that has a Operational Status value of down, the Operational Status value is automatically changed to up. This functionality is supported for both automatic and manual connection tests.
  • If a connection cannot be established to a server that has a Operational Status value of up, the Operational Status value is automatically changed to down. This functionality is supported for automatic connection tests only, not manual tests.

8 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 importing groups into the system and the other for users.

  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 (see table).
  5. Click Update.
  6. [Versions prior to Dublin] Under Related Links, click Test connection to verify the LDAP connection.
    Starting with the Dublin Release, the test is performed automatically when you update the LDAP record.
  7. Under Related Links, click Browse to view the LDAP directory records that the OU definition returns.
The LDAP OU Definition form

Field Description
Name Specify the name the integration uses when referencing this OU. The name you enter here becomes an LDAP target in the data source record.
RDN Specify the relative distinguished name of the subdirectory you want to search. This RDN is combined with the start-searching directory from the LDAP server definition to identify the subdirectory containing information for this organizational unit. For example, the sample OU definition uses the RDN value of CN=Users to search the LDAP directory CN=Users,DC=service-now,DC=com and any directory below this point. This field must match a subdirectory in your LDAP system.
Query field Specify the name of the attribute within the LDAP server to query for records. The query field must be unique in both single and multiple domain instances. For best results, use email addresses or other credentials that uniquely identify the user in a multiple domain instance. Active Directory uses the sAMAccountName attribute. Other LDAP servers tend to use the cn attribute.

Note:The Query field must map to the User ID field in the User [sys_user] table. For example, if an Active Directory user logs in as joe.example, there must be a user record with a User ID value of joe.example and an LDAP record with an sAMAccountName value of joe.example.

Active Select this check box to activate the OU definition and to allow administrators to test importing data. The Test connection and Browse related links work on inactive OU definitions for versions prior to the Dublin release. However, the integration can only bring data into the system from active OU definitions.
Table Specify the ServiceNow table that receives the mapped data from your LDAP server. For users select User and for groups select Group.
Filter Enter an LDAP filter string to select specific records to import from the OU. The more specific the LDAP filter query, the more efficient the query is. For example, the Users LDAP OU definition uses the following 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)))

You can find a description of LDAP filter syntax by searching the internet for LDAP Filters RFC.

8.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 the ServiceNow application. Do the following:

  1. Create an LDAP server record with a starting search directory of dc=my-domain,dc=com.
  2. Create an OU definition record for ou=Groups with a filter to exclude cn=HR.
  3. 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.

9 Create a Data Source

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

Note
Note: Both the LDAP Server and LDAP OU Definition must be active for the test load action to function properly. When the test load is activated for the first time, the ServiceNow system 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, the ServiceNow system sets the field length for all subsequent imports to the default length of 40. The import truncates any imported data that exceeds the import set table field length. Additionally, the User ID field is truncated to a maximum of 40 characters. Be aware that the 20 loaded records cannot be transformed and are for testing purposes only. If the test records contain values for the User ID field,the field length is set based on the field length of the longest user ID in the test records.


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 (see 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.
Field Description
Name Specify the name the integration uses when referencing this data source.
Import set table name Enter the name of the staging table where the ServiceNow system temporarily places the imported LDAP records and attributes. Review this table to view imported LDAP records. You can use the same import set table name for all LDAP data sources.
Type Select LDAP to indicate the imported data is LDAP data. After you select the type LDAP, the form displays the LDAP target field.
LDAP target Select the LDAP OU definition associated with this data source.

9.1 Select or 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.

Note
Note: Whether you select or create custom LDAP transform maps, it is recommended that there only ever be one active transform map for a set of source and target tables. Enabling multiple transform maps for the same source and target tables can produce duplicate entries in the target table unless you coalesce against the matching fields. For more information, see Creating New Transform Maps.


9.1.1 Selecting Existing Transform Maps for LDAP Data

By default, the ServiceNow system provides two transform maps for LDAP data.

Transform Map Source Table Target Table Description
LDAP User Import ldap_import sys_user Default transform map for creating ServiceNow user records from LDAP credentials as part of LDAP on-demand login. Contains mappings for an Active Directory LDAP server.
LDAP Group Import ldap_group_import sys_user_group Default transform map for creating ServiceNow group records from LDAP OUs. Contains mappings for an Active Directory LDAP server.
Note
Note: By default, the ServiceNow system does not have a transform map for LDAP department records.


9.1.2 Creating a Custom Transform Map for LDAP Data

If you choose to create a custom transform map, the transform map must meet the following mapping requirements.

Source Table Source Field Target Table Target Field Coalesce Description
ldap_import u_source sys_user source false The u_source field identifies the LDAP DN of the imported user or group. The ServiceNow system uses this field to determine that a user requires LDAP authentication, to find a user's manager, and to put users into groups.
ldap_import Select one of the following fields:
  • u_samaccountname
  • u_dn
  • u_cn
sys_user user_name true If LDAP integrates to Active Directory, select u_samaccountname as the source field. If other LDAP directories are used, select u_dn or u_cn as the source field.

9.2 Converting LDAP Data to ServiceNow Data Types

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, sample 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, the ServiceNow system searches for an existing matching record. If no matching record exists, the ServiceNow system 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 uses a long text string such as: cn=Beth Anglin,ou=Users,dc=my-domain,dc=com.

Warning
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. The ServiceNow system truncates any value that exceeds the field length.

Administrators do not typically want the ServiceNow system 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 search 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.

9.3 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);

10 Create and Execute a Scheduled Import

A scheduled import allows administrators to import LDAP data on a regular 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.

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

Was this article helpful?
Yes, I found what I needed
No, I need more assistance