Configure LDAP authentication
Settings guide
Authenticate NIM users against an LDAP directory while keeping identity matching explicit and supportable.
Use LDAPS with TLS encryption on TCP port 636 to protect credentials and directory traffic between NIM and the LDAP server. Avoid sending simple-bind credentials over unencrypted LDAP. The NIM SSL option enables the encrypted connection.
Before you beginDirect link to Before you begin
Add the directory as a system, create an inter-system relation between it and the Internal system, and permit TCP 636 for the recommended LDAPS connection. LDAP uses TCP 389; that port alone does not guarantee encryption. Map each Internal user's ExternalID to the directory user identifier and set AuthMethod to the name of the LDAP configuration you will use.
Secure connection recommendationsDirect link to Secure connection recommendations
- Validate the server identity. Use the server's fully qualified DNS name and a certificate that covers that hostname. Trust the issuing CA in NIM and renew the certificate before it expires. See certificate trust troubleshooting and hostname matching.
- Keep certificate validation enabled. Fix certificate-chain or hostname errors before using the connection for authentication.
- Use modern TLS. Prefer TLS 1.3 where the directory server and NIM client support it; use TLS 1.2 for compatibility. Disable SSLv2, SSLv3, TLS 1.0, and TLS 1.1 in the directory server's TLS policy. Follow IETF RFC 9325 (BCP 195) and the OWASP TLS guidance.
- Limit network access. Allow the NIM server to reach only the required directory endpoints and ports.
- Test before rollout. Verify sign-in with a controlled Internal user after enabling LDAPS or changing certificates, TLS versions, or directory security policies.
Provider security guidanceDirect link to Provider security guidance
| Provider | Guidance |
|---|---|
| Microsoft Active Directory | Follow Microsoft's LDAPS certificate requirements and verification steps. Review LDAP signing and channel binding with your directory administrator, and validate client compatibility before enforcing policy changes. |
| Google Workspace / Cloud Identity | Follow Google's Secure LDAP client connection guidance. Google Secure LDAP requires a client certificate and private key. Configure the client certificate in NIM's Certificate field; server certificate trust is configured separately. |
LDAP configuration fieldsDirect link to LDAP configuration fields
These fields are available under Configuration > Settings > LDAP.
| Field | Purpose |
|---|---|
| Name | The name of the LDAP configuration. Use this exact name in the Internal user's AuthMethod to select this configuration. See AuthMethod rules. |
| Related system | The connected directory system where the users reside. An inter-system relation links internal.users.ExternalID to the directory user's identifier in this system. |
| DNS name | The hostname or IP address of the LDAP server. For SSL/LDAPS, use a hostname covered by the server certificate. |
| SSL | Enables LDAPS, encrypting the LDAP connection with TLS. |
| Port | The port NIM connects to. The default ports are 389 for LDAP and 636 for LDAPS. |
| Certificate | The client certificate used to authenticate NIM to the LDAP server. Required for Google Secure LDAP. Manage certificates under Certificates. |
| Status | The result of testing the connection, such as Connection OK, or an error to investigate. |
The Certificate field selects the client certificate. Trust in the LDAP server's issuing CA is configured separately in NIM. For Active Directory binding, leave this field empty after adding the issuing CA as described in certificate trust troubleshooting.
Configure LDAP or LDAPSDirect link to Configure LDAP or LDAPS
Provision matching usersDirect link to Provision matching users
Create a filter of directory users and map them to Internal users. Set AuthMethod to the LDAP configuration name, ExternalID to the directory user identifier, and the username, email, display name, and enabled state as appropriate.
For example, an LDAP configuration named CorporateDirectory requires AuthMethod to be CorporateDirectory. Use LDAP only when the configuration is actually named LDAP. If AuthMethod is undefined, the user can use any authentication method configured in NIM. See Internal user fields and AuthMethod rules.
Match Internal users to the directoryDirect link to Match Internal users to the directory
In Processing > Relations, relate internal.users.ExternalID to the directory users’ object identifier, then save.
Configure the connectionDirect link to Configure the connection
Go to Configuration > Settings > LDAP, select Add, and complete the LDAP configuration fields. Use the configuration Name selected for the Internal users' AuthMethod. For the recommended LDAPS connection, enable SSL, use port 636, and enter the fully qualified DNS name covered by the server certificate. Select a client Certificate when required, including for Google Secure LDAP.
Apply the secure connection recommendations, test the connection, and review Status. Then verify sign-in with a controlled Internal user.
Troubleshoot sign-inDirect link to Troubleshoot sign-in
Check the NIM logs when a user cannot sign in. Several different account problems produce the same LDAP InvalidCredentialsError-49 entry and the same login-screen message, so that log entry alone does not identify the cause. A POST /api/login entry only confirms a login request was made. Check the directory account state and the matching Internal user record before changing configuration.
Unable to connect to the LDAP serverDirect link to Unable to connect to the LDAP server
Problem
Unable to connect to the LDAP server
Login screen
Name password combination not valid.
NIM log
Error authenticating user <USERNAME> using LDAP server with ID LDAP (ldap://<LDAP SERVER>):Error-ENOTFOUND: getaddrinfo ENOTFOUND <LDAP SERVER>
Resolution
Check the LDAP server name in Configuration > Settings > LDAP. Confirm that the NIM server can resolve that name in DNS, then retry sign-in.
Disabled LDAP userDirect link to Disabled LDAP user
Problem
Disabled LDAP user
Login screen
Name password combination not valid.
NIM log
Error authenticating user <USERNAME> using LDAP server with ID LDAP (ldap://<LDAP SERVER>):InvalidCredentialsError-49: Invalid Credentials
Resolution
Check whether the user is disabled in the LDAP directory. If the account should be active, restore it through your normal account-management process and retry.
Incorrect passwordDirect link to Incorrect password
Problem
Incorrect password
Login screen
Name password combination not valid.
NIM log
Error authenticating user <USERNAME> using LDAP server with ID LDAP (ldap://<LDAP SERVER>):InvalidCredentialsError-49: Invalid Credentials
Resolution
Confirm the user is entering the correct credentials. If needed, reset the directory password through your normal process, then retry sign-in.
Password must change at next logonDirect link to Password must change at next logon
Problem
Password must change at next logon
Login screen
Name password combination not valid.
NIM log
Error authenticating user <USERNAME> using LDAP server with ID LDAP (ldap://<LDAP SERVER>):InvalidCredentialsError-49: Invalid Credentials
Resolution
Check whether the directory account is set to Must change password at next logon. Have the user complete the password change through a supported directory sign-in or password-change process, then retry NIM.
Expired LDAP accountDirect link to Expired LDAP account
Problem
Expired LDAP account
Login screen
Name password combination not valid.
NIM log
Error authenticating user <USERNAME> using LDAP server with ID LDAP (ldap://<LDAP SERVER>):InvalidCredentialsError-49: Invalid Credentials
Resolution
Check the directory account expiration date. If access should continue, update the account through the approved lifecycle process and retry.
No matching user in the Internal systemDirect link to No matching user in the Internal system
Problem
No matching user in the Internal system
Login screen
Name password combination not valid.
NIM log
POST /api/login for sessionId: <SESSION ID>
Resolution
Confirm that the user exists in internal.users, that any defined AuthMethod matches the LDAP configuration name, and that ExternalID matches the directory user through the configured inter-system relation. Correct the mapping or provision the missing Internal user, then retry.
NIM Internal user disabledDirect link to NIM Internal user disabled
Problem
NIM Internal user disabled
Login screen
Account is disabled.
NIM log
POST /api/login for sessionId: <SESSION ID>
Resolution
Check the matching internal.users record and its enabled state. If the user should have access, correct the source data or mapping that sets the Internal user state, then refresh the user record and retry.
Troubleshoot LDAP and LDAPSDirect link to Troubleshoot LDAP and LDAPS
LDAPS certificate chain cannot be verifiedDirect link to LDAPS certificate chain cannot be verified
Problem
LDAPS certificate chain cannot be verified
Likely cause
An UNABLE_TO_VERIFY_LEAF_SIGNATURE error means NIM does not trust the certificate authority that issued the LDAPS server certificate.
Resolution
- On a server that trusts the directory certificate chain, run
CertUtil.exeto identify the issuing certificate authority. - Open
mmc, add the Certificates snap-in for the Computer account, then open Trusted Root Certification Authorities > Certificates. - Export the issuing CA certificate as DER encoded binary X.509 (.CER).
- In NIM, go to Configuration > Settings > Certificates, add the exported CA certificate, and save.
- Test the LDAP connection again.
For Active Directory binding, leave the LDAP server configuration’s Certificate field empty after adding the CA to NIM. The uploaded CA establishes trust; it is not the server certificate to select for the connection.
LDAPS hostname does not match the certificateDirect link to LDAPS hostname does not match the certificate
Problem
LDAPS hostname does not match the certificate
Likely cause
An ERR_TLS_CERT_ALTNAME_INVALID error means the configured LDAP DNS name is absent from the LDAPS certificate’s Subject Alternative Name values.
Resolution
- Compare the configured DNS name with the certificate’s SAN entries.
- Use the fully qualified domain name of the domain controller when its certificate was issued to that specific controller.
- Do not use an IP address or alias unless it appears in the certificate.
- Save the LDAP configuration and test again over port
636.