LDAP integration troubleshooting

  • Release version: Zurich
  • Updated July 31, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of LDAP integration troubleshooting

    This guide provides essential troubleshooting guidance for customers integrating LDAP servers with their ServiceNow instances. Proper LDAP integration is crucial because if the LDAP server is unavailable, users cannot log in. The document outlines preliminary checks, error code references, multi-domain integration considerations, handling of incoming records, common authentication errors, and connection testing procedures.

    Show full answer Show less

    Preliminary Checks

    • Maintain local administrator accounts to ensure instance access if LDAP is down.
    • Verify the LDAP service account is not expired or locked out.
    • Check username formats, trying domain-qualified usernames (e.g., domain\username or username@domain).
    • Confirm the systemid on the ldapserverconfig record is correctly set and not unintentionally modified by update sets, as incorrect systemid can cause connection failures.

    Error Codes and Logs

    Error codes for LDAP and Active Directory are logged in the LDAP wrapper log file:

    • LDAP errors are two-digit codes.
    • Active Directory errors are three-digit codes.

    Familiarity with common error codes helps diagnose connection and authentication issues.

    Multiple Domain Integration

    • Support exists for integration across multiple domains within the same forest or across non-trusted domains by creating separate LDAP server records per domain.
    • Each LDAP server record must point to the domain controller for its domain, requiring network access permissions.
    • Multiple AD forests cannot be integrated through LDAP using a single LDAP account.
    • When integrating multiple domains, it is critical to identify unique LDAP attributes (such as objectSid, email, or userPrincipalName) for username uniqueness and proper import coalesce behavior.

    Incoming Records and Authentication Errors

    • LDAP transform maps control how incoming LDAP records without matching reference fields are processed.
    • Common authentication errors include invalid Distinguished Name (DN), invalid Common Name (CN), and invalid connection issues that prevent users from logging in.

    LDAP Connection Testing

    • ServiceNow automatically tests LDAP connections in two ways:
      • Each time the LDAP Server form is opened.
      • Via the LDAP Connection Test scheduled job, which runs every 15 minutes by default; this interval can be adjusted.
    • If connection attempts fail, a one-time retry is scheduled after 5 minutes or half the repeat interval, whichever is sooner.
    • Error messages display directly on the LDAP Server form when connection issues occur.
    • Connection tests also support LDAP servers behind MID servers.

    If you are integrating your LDAP server and have questions, these items may help you troubleshoot the issue.

    Preliminary checks

    • If the LDAP is unavailable, users cannot log in to the instance. A good practice is to have local accounts for administrators so that if the LDAP is down, administrators can still access the instance.
    • Check the service account to ensure that it is not expired or locked out.
    • Check the format of the username. Instead of using just the username, try using the domain with the username, or username@domain.
    • Verify that you have changed the system_id entry on the ldap_server_config record. If you modify the system_id unintentionally with an update set, system_id points to the wrong node for the target instance and does not work.

    Error codes

    The LDAP log file lists industry standard error codes for both LDAP and Active Directory (AD). The LDAP log file is contained in the wrapper file. The LDAP error codes are two-digit numbers, while the Active Directory error codes are three-digit numbers. For a list of the most-common error codes, see LDAP Error Codes.

    Multiple domain integration

    You can integrate multiple domains within the same forest or in completely non-trusted domains. It is recommended that you create a separate LDAP server record for each domain. Each LDAP server record must point to a domain controller for that given domain. This means you will have to allow connections to each of the domain controllers. Multiple AD forests through LDAP with one LDAP account is not supported.

    When you expand to more than one domain, it is critical that you identify unique LDAP attributes for the application usernames and import coalesce values. A common unique coalesce attribute for Active Directory is objectSid. Unique usernames will vary based on your LDAP data design. Common unique attributes are email or userPrincipalName.

    Incoming records

    See LDAP transform maps to set how the integration processes incoming LDAP records that are missing matching values in reference fields.

    Common authentication errors

    • User Cannot Log In (Invalid DN)
    • Invalid CN
    • Invalid Connection

    Automatic LDAP connection tests

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

    The system tests the connection automatically:
    • 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. Also supported are test connections for servers behind a MID server.