LDAP authentication

The default Tines identity provider can be configured by self hosted customers to authenticate users via LDAP (as opposed to via email or SSO).

To enable it, configure the following environment variables:

Required Settings 

  • LDAP_HOST - The hostname or IP address of your LDAP server

  • LDAP_BASE_DN - The base distinguished name for searches (e.g., dc=example,dc=com)

Optional Settings 

  • LDAP_PORT - The port number (default: 636)

  • LDAP_BIND_DN - The distinguished name to bind with for searches (optional for anonymous bind)

  • LDAP_BIND_PASSWORD - The password for the bind DN (required if LDAP_BIND_DN is set)

  • LDAP_USER_FILTER - The filter to find users (default: (uid=${username}))

  • LDAP_EMAIL_ATTRIBUTE - The attribute containing user email (default: mail)

  • LDAP_FIRST_NAME_ATTRIBUTE - The attribute containing first name (default: givenName)

  • LDAP_LAST_NAME_ATTRIBUTE - The attribute containing last name (default: sn)

  • LDAP_ENCRYPTION - Transport security: simple_tls (default), start_tls, or none

  • LDAP_CA_CERT_PEM - Inline PEM string of one or more CA certificates

  • LDAP_CONNECT_TIMEOUT - Connection timeout in seconds (default: 10)

  • LDAP_READ_TIMEOUT - Read timeout in seconds (default: 10)

⚠️ Security Warning: Disabling SSL verification makes your LDAP connection vulnerable to man-in-the-middle attacks. Only disable these settings in secure, isolated environments for testing purposes.

  • LDAP_VERIFY_PEER - Verify server certificate is valid and trusted (default: true)

  • LDAP_VERIFY_HOSTNAME - Verify certificate matches the hostname (default: true)

Example Configuration 

Basic Configuration 

LDAP_HOST=ldap.example.com
LDAP_BASE_DN=dc=example,dc=com
LDAP_USER_FILTER=(uid=${username})

Active Directory Configuration 

LDAP_HOST=ad.example.com
LDAP_PORT=389
LDAP_BASE_DN=dc=example,dc=com
LDAP_BIND_DN=cn=service-account,ou=service-accounts,dc=example,dc=com
LDAP_BIND_PASSWORD=your-service-account-password
LDAP_USER_FILTER=(sAMAccountName=${username})LDAP_EMAIL_ATTRIBUTE=mail
LDAP_FIRST_NAME_ATTRIBUTE=givenName
LDAP_LAST_NAME_ATTRIBUTE=sn

SSL/TLS Configuration 

By default we use LDAPS (simple TLS) with certificate and hostname verification.

LDAPS (recommended default):

LDAP_HOST=ldaps.example.com
LDAP_PORT=636
LDAP_ENCRYPTION=simple_tls
LDAP_BASE_DN=dc=example,dc=com

StartTLS on port 389:

LDAP_HOST=ldap.example.com
LDAP_PORT=389
LDAP_ENCRYPTION=start_tls
LDAP_BASE_DN=dc=example,dc=com

Provide custom CA certificate if necessary:

LDAP_CA_CERT_PEM="-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----"

More than one cert block is supported (for including a chain). You can use a command like the following to flatten a PEM file with a CA cert chain into a single line in a suitable format:

awk 'BEGIN{ORS="\\\\n"}{print}' certs/ca.crt | sed 's/\\\\n$//'

How It Works 

  1. When LDAP is configured, an “Sign in with LDAP” option appears on the login page

  2. Users enter their LDAP username and password

  3. The system searches for the user in LDAP using the configured filter

  4. If found, it attempts to authenticate by binding with the user’s credentials

  5. Upon successful authentication, user information is extracted from the following LDAP attributes:

    • Email (required): Extracted from the attribute specified by LDAP_EMAIL_ATTRIBUTE (default: mail)

    • First Name (optional): Extracted from the attribute specified by LDAP_FIRST_NAME_ATTRIBUTE (default: givenName)

    • Last Name (optional): Extracted from the attribute specified by LDAP_LAST_NAME_ATTRIBUTE (default: sn)

  6. If the email address is missing or blank, authentication fails with “No email address found for user”

  7. The user is then signed in to their Tines tenant

Important: The email attribute is required for successful authentication. If your LDAP directory uses a different attribute for email addresses (e.g., userPrincipalName in Active Directory), ensure you set LDAP_EMAIL_ATTRIBUTE accordingly.

Common Issues 

  1. “Sign in with LDAP” not appearing - Ensure LDAP_HOST and LDAP_BASE_DN are set

  2. “Incorrect username or password” - Check the LDAP_USER_FILTER and LDAP_BASE_DN settings and verify the username and password are correct

  3. “Incorrect username or password” (when multiple users match) - If your username filter returns multiple users, authentication will fail with the same error as an incorrect password. Check the server logs for “Multiple users found” messages:

    • Review your LDAP_USER_FILTER to make it more specific

    • Ensure usernames are unique in your LDAP directory

    • Consider using a more specific base DN to limit the search scope

  4. “LDAP connection failed”

    • Verify LDAP_ENCRYPTION is set correctly (simple_tls, start_tls or none)

    • Ensure the server certificate is trusted via system trust or LDAP_CA_CERT_PEM

    • Confirm LDAP_HOST/LDAP_PORT and network connectivity

  5. Connection timeouts

    • Increase LDAP_CONNECT_TIMEOUT for slow network connections

    • Increase LDAP_READ_TIMEOUT for slow LDAP servers or large directories

    • Check network connectivity and firewall rules

  6. SSL/TLS certificate errors

    • Certificate verification failed: Set LDAP_CA_CERT_PEM with your CA certificate, or temporarily set LDAP_VERIFY_PEER=false for testing

    • Hostname verification failed: Certificate is valid but for different hostname - set LDAP_VERIFY_HOSTNAME=false if using load balancers or internal hostnames

    • Self-signed certificate: Set LDAP_VERIFY_PEER=false for testing, but consider using proper certificates in production

Was this helpful?