Redmine supports authentication against one or more LDAP or Active Directory servers. Authentication sources are managed at Administration → LDAP authentication.
LDAP authentication requires the net-ldap gem. It is included in the :ldap gem group in the Gemfile and installed automatically by bundle install.
Creating an LDAP auth source
- Navigate to Administration → LDAP authentication → New authentication source.
- Fill in the connection and attribute mapping fields described below.
- Click Save, then use the Test button to verify the connection.
Connection fields
| Field | Description | Example |
|---|
| Name | Display name for this authentication source (max 60 characters). | Corporate LDAP |
| Host | Hostname or IP address of the LDAP server (max 60 characters). | ldap.example.com |
| Port | TCP port for LDAP connections. Default is 389 for plain LDAP, 636 for LDAPS. | 389 |
| LDAP mode | Connection security mode. | See below. |
| Account | DN or username used by Redmine to bind to the directory and search for users. Leave blank for anonymous binding. Use $login to bind as the authenticating user. | cn=redmine,ou=service,dc=example,dc=com |
| Password | Password for the bind account. Leave blank for anonymous binding. | |
| Base DN | The starting point for user searches (max 255 characters). | ou=users,dc=example,dc=com |
| LDAP filter | Optional LDAP search filter to restrict which entries are considered valid users. | (objectClass=person) |
| Timeout | Connection timeout in seconds. Defaults to 20 seconds if blank or zero. | 15 |
LDAP modes
| Mode | Description |
|---|
ldap | Unencrypted LDAP (port 389). Use only on trusted internal networks. |
ldaps_verify_none | LDAPS with TLS encryption (port 636), but the server certificate is not verified. |
ldaps_verify_peer | LDAPS with TLS encryption and server certificate verification. Recommended for production. |
Attribute mapping
Map LDAP directory attributes to Redmine user fields:
| Field | Description | Common AD value | Common OpenLDAP value |
|---|
| Login attribute | LDAP attribute containing the username. Required. Max 30 characters. | sAMAccountName | uid |
| Firstname attribute | LDAP attribute for the user’s first name. | givenName | givenName |
| Lastname attribute | LDAP attribute for the user’s last name. | sn | sn |
| Email attribute | LDAP attribute for the user’s email address. | mail | mail |
On-the-fly user creation
When On-the-fly user creation is enabled, Redmine automatically creates a local user account the first time a user successfully authenticates via LDAP. The account is populated using the firstname, lastname, and email attributes defined in the attribute mapping.
For on-the-fly creation to work, all four attribute fields (login, firstname, lastname, email) must be configured.
The LDAP source is also searchable for user lookup (e.g. when adding members to a project) when on-the-fly creation is enabled and all attributes are mapped.
Bind strategy
Service account bind
The most common approach uses a dedicated service account to search the directory:
- Set Account to the DN of a read-only service account.
- Set Password to that account’s password.
- Redmine binds as the service account, searches for the user’s DN, then attempts to bind with the user’s credentials to verify the password.
Direct bind ($login)
When Account contains the string $login, Redmine substitutes it with the authenticating user’s login at bind time. This is useful when users’ DNs follow a predictable pattern:
cn=$login,ou=users,dc=example,dc=com
$login account, the directory is not searchable from Redmine (user lookup and on-the-fly creation based on directory search are unavailable).
Example: Active Directory
Name: Active Directory
Host: ad.example.com
Port: 389
LDAP mode: ldap
Account: EXAMPLE\redmine-svc
Password: **********
Base DN: CN=Users,DC=example,DC=com
LDIF filter: (objectClass=user)
Login attribute: sAMAccountName
Firstname attr: givenName
Lastname attr: sn
Email attr: mail
On-the-fly: enabled
Example: OpenLDAP
Name: OpenLDAP
Host: ldap.example.com
Port: 636
LDAP mode: ldaps_verify_peer
Account: cn=redmine,ou=service,dc=example,dc=com
Password: **********
Base DN: ou=users,dc=example,dc=com
LDIF filter: (objectClass=inetOrgPerson)
Login attribute: uid
Firstname attr: givenName
Lastname attr: sn
Email attr: mail
On-the-fly: enabled
Testing the connection
After saving an LDAP auth source, click Test on the LDAP authentication list. Redmine opens a connection to the server, performs the bind, and reports success or a connection error.
If the account and password are set (and $login is not used), Redmine also verifies the bind credentials and reports an error if they are invalid.
Troubleshooting
| Symptom | Likely cause |
|---|
| Connection refused | Wrong host or port, or firewall blocking the connection. |
| Invalid credentials error | Incorrect bind account DN or password. |
| User not found | Base DN too narrow, or login attribute does not match. |
| Certificate error | LDAPS with ldaps_verify_peer and the server certificate is not trusted. Add the CA certificate to the system trust store. |
| Timeout | Network latency or unreachable host. Increase the timeout value. |
