---
title: LDAP authentication
url: https://www.tines.com/docs/self-hosted/configuring-tines/ldap-authentication/
updated: 2026-05-08T17:56:23+00:00
---

*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/llms.txt) › [Self-Hosted](https://www.tines.com/llm/docs/self-hosted.md) › [Configuring Tines](https://www.tines.com/llm/docs/self-hosted/configuring-tines.md)*

# LDAP authentication

*[View on tines.com](https://www.tines.com/docs/self-hosted/configuring-tines/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)

*ℹ️ ****Note****: *Use single quotes around any value that contains $, {, }, spaces, or other shell metacharacters (for example, LDAP_USER_FILTER='(sAMAccountName=${username})').

- `LDAP_USER_FILTER` - The filter to find users (default: `(uid=${username})`)
- `LDAP_EMAIL_ATTRIBUTE` - The attribute containing user email (default: `userPrincipalName`)
- `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

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

### Active Directory Configuration

```bash
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=userPrincipalName
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):

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

StartTLS on port 389:

```bash
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:

```bash
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:

```bash
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: `userPrincipalName`)
  - **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., `mail` 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