Dovecot CE
Search K

Appearance

LDAP Authentication (ldap) ​

There are two ways to do LDAP authentication:

Password Lookups ​

Advantages over Authentication Binds:

  • Faster, because Dovecot can keep sending multiple LDAP requests asynchronously to the server. With auth binds Dovecot must wait for each request to finish before sending the next one.

  • Supports non-plaintext authentication mechanisms (if returning plaintext or properly hashed passwords).

  • When using LDA or LMTP Server and static userdb, deliver can check if destination user exists. With auth binds this check isn't possible.

LDAP Server Permissions ​

Normally LDAP server doesn't give anyone access to users' passwords, so you'll need to create an administrator account that has access to the userPassword field.

With OpenLDAP this can be done by modifying /etc/ldap/slapd.conf:

#---- there should already be something like this in the file
access to attribute=userPassword

    #---- just add this line
    by dn="<dovecot's dn>" read

    by anonymous auth
    by self write
    by * none

Replace <dovecot's dn> with the DN you specified in ldap_auth_dn in dovecot.conf's ldap settings.

Alternatively, you can:

  1. Create below text file and save it as authuser_modify.ldif.
dn: olcDatabase={2}hdb,cn=config
changetype: modify
replace: olcAccess
olcAccess: {0}to attrs=userPassword
	by self write
	by dn="cn=authuser,dc=test,dc=dovecot,dc=net" read
	by * auth
olcAccess: {1}to *
	by self read
	by dn="cn=authuser,dc=test,dc=dovecot,dc=net" read
	by * auth
  1. Run ldapmodify to apply the change.
sh
$ ldapmodify -Q -Y EXTERNAL -H ldapi:/// -f doveauth_access.ldif

Dovecot Configuration ​

The two important settings in password lookups are:

  • passdb_ldap_filter specifies the LDAP filter how user is found from the LDAP. You can use all the normal Settings variables like %{user} in the filter.

  • passdb_fields specifies a list of attributes that are returned and how to produce the returned value.

Usually the LDAP attribute names aren't the same as the field names that Dovecot uses internally. You must create a mapping between them to get the wanted results. This is done by listing the fields as <dovecot field> = <expression> where expression can include ldap specific variables and other variables too.

For example:

passdb ldap {
  fields {
    user = %{ldap:uid}
    password = %{ldap:userPassword}
  }
}

This maps the LDAP "uid" attribute to Dovecot's "user" field and LDAP's "userPassword" attribute to Dovecot's "password" field. These two fields should always be returned, but it's also possible to return other special passdb: Extra Fields.

Password ​

Most important, passdb_fields must return a password field, which contains the user's password.

The next thing Dovecot needs to know is what format the password is in. If all the passwords are in same format, you can use passdb_default_password_scheme setting in dovecot.conf to specify it. Otherwise each password needs to be prefixed with {password-scheme}, for example {plain}plaintext-password.

See password schemes for a list of supported password schemes.

Username ​

LDAP lookups are case-insensitive. Unless you somehow normalize the username, it's possible that a user logging in as "user", "User" and "uSer" are treated differently.

The easiest way to handle this is to tell Dovecot to change the username to the same case as it's in the LDAP database. You can do this by returning "user" field in passdb_fields setting, as shown in the above example.

If you can't normalize the username in LDAP, you can alternatively lowercase the username via auth_username_format = %{user | lower}.

Use Worker ​

By default (no) all LDAP lookups are performed by the auth master process.

If passdb_use_worker/passdb_use_worker= yes, auth worker processes are used to perform the lookups. Each auth worker process creates its own LDAP connection so this can increase parallelism.

With passdb_use_worker/passdb_use_worker= no, the auth master process can keep 8 requests pipelined for the LDAP connection, while with passdb_use_worker/passdb_use_worker= yes each connection has a maximum of 1 request running.

For small systems, passdb_use_worker/passdb_use_worker= no is sufficient and uses less resources.

Example ​

A typical configuration would look like:

  passdb ldap {
    bind = no
    default_password_scheme = MD5
    ldap_filter = (&(objectClass=posixAccount)(uid=%{user}))
    fields {
      user = %{ldap:uid}
      password = %{ldap:userPassword}
    }
  }

Authentication Binds ​

Advantages over Password Lookups

  • LDAP server verifies the password, so Dovecot doesn't need to know what format the password is stored in.

  • A bit more secure, as a security hole in Dovecot doesn't give attacker access to all the users' password hashes. (And Dovecot admins in general don't have direct access to them.)

You can enable authentication binds by setting passdb_ldap_bind = yes.

Dovecot needs to know what DN to use in the binding. There are two ways to configure this: lookup or template.

DN Lookup ​

DN is looked up by sending a passdb_ldap_filter LDAP request and getting the DN from the reply. This is very similar to doing a password lookup. The only difference is that userPassword attribute isn't returned.

Just as with password lookups, the passdb_fields may contain special passdb: Extra Fields.

Example:

  passdb ldap {
    bind = yes
    ldap_filter = (&(objectClass=posixAccount)(uid=%{user}))
    fields {
      user = %{ldap:uid}
    }
  }

DN Template ​

The main reason to use DN template is to avoid doing the DN lookup, so that the authentication consists only of one LDAP request.

With IMAP and POP3 logins, the same optimization can be done by using prefetch authentication database and returning userdb info in the DN lookup (a total of two LDAP requests per login in both cases).

If you're also using Dovecot for SMTP AUTH, it doesn't do a userdb lookup so the prefetch optimization doesn't help.

If you're using DN template, passdb_fields and passdb_ldap_filter settings are completely ignored. That means you can't make passdb return any passdb: Extra Fields. You should also set auth_username_format = %{user | lower} in dovecot.conf to normalize the username by lowercasing it.

  passdb ldap {
    bind = yes
    bind_userdn = cn=%{user},ou=people,o=org
  }

Connection Optimization ​

When using

  • auth binds and
  • userdb ldap lookups,

the userdb lookups should use a separate connection to the LDAP server. That way it can send LDAP requests asynchronously to the server, which improves the performance. This can be done by specifying distinct ldap_connection_group in the LDAP passdb / userdb sections.

passdb ldap {
  # ldap_connection_group left unchanged, the default is ''
  ...
}

userdb ldap {
  ldap_connection_group = different-connection-group
  ...
}

Common Configuration ​

This sections describes the configuration common to LDAP passdb and userdb.

Connecting ​

The LDAP server(s) endpoints must be specified as ldap URIs:

  • ldap_uris: A space separated list of LDAP URIs to connect to.

If multiple LDAP servers are specified, it's decided by the LDAP library how the server connections are handled. Typically the first working server is used, and it's never disconnected from. So there is no load balancing or automatic reconnecting to the "primary" server.

SSL/TLS ​

You can enable TLS in two alternative ways:

  • Connect to ldaps port (636) by using "ldaps" protocol, e.g. ldap_uris = ldaps://secure.domain.org
  • Connect to ldap port (389) and use STARTTLS command. Use ssl = yes to enable this.

See the SSL configuration settings for how to configure TLS. Not all of Dovecot SSL settings are supported by the LDAP library. Below is the list of supported settings:

ssl_cipher_list

DefaultALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@STRENGTH (for ssl_server, empty for ssl_client)
Valuestring
See Also

The list of SSL ciphers to use for TLSv1.2 and below connections, in order of preference. Use ssl_cipher_suites for TLSv1.3 connections.

You do not need to edit this setting in order to disable specific SSL protocols; that is best done with ssl_min_protocol instead.

This setting is used for both incoming and outgoing SSL connections.

ssl_client_ca_dir

Default[None]
Valuestring
See Also

The directory where trusted SSL CA certificates can be found. For example /etc/ssl/certs. These certificates are used only for outgoing SSL connections (e.g. with the imapc driver).

For extra security you might want to point to a directory containing certificates only for the CAs that are actually needed for the server operation instead of all the root CAs.

ssl_client_ca_file

Default[None]
ValueFile
See Also

File containing the trusted SSL CA certificates. For example /etc/ssl/certs/ca-bundle.crt.

These certificates are used only for outgoing SSL connections (e.g. with the imapc driver).

Note that this setting isn't recommended to be used with large CA bundles, because all the certificates are read into memory. This leads to excessive memory usage, because it gets multiplied by the number of imap processes. It's better to either use ssl_client_ca_dir setting or use a CA bundle that only contains the CAs that are actually necessary for the server operation.

ssl_client_cert_file

Default[None]
ValueFile
See Also

Public SSL certificate used for outgoing SSL connections. This is generally needed only when the server authenticates the client using the certificate.

ssl_client_key_file is also needed for the private certificate.

Example:

ssl_client_cert_file = /etc/dovecot/dovecot-client.crt
ssl_client_key_file = /etc/dovecot/dovecot-client.key

ssl_client_require_valid_cert

Defaultyes
Valueboolean
See Also

Require a valid certificate when connecting to external SSL services?

ssl_curve_list

Default<defaults from the SSL library>
Valuestring
See Also

Colon separated list of elliptic curves to use, in order of preference. An empty value uses the defaults from the SSL library.

This setting is used for both incoming and outgoing SSL connections.

Example:

ssl_curve_list = P-521:P-384:P-256

ssl_min_protocol

DefaultTLSv1.2
Valuestring
See Also

The minimum SSL protocol version Dovecot accepts.

This setting is used for both incoming and outgoing SSL connections.

Supported values are:

ANY

WARNING

This value is meant for tests only. It should not be used in any deployment of any value/relevance.

TLSv1
Support TLSv1+. (TLSv1 deprecated: RFC 8996)
TLSv1.1
Support TLSv1.1+. (TLSv1.1 deprecated: RFC 8996)
TLSv1.2
Support TLSv1.2+.
TLSv1.3
Support TLSv1.3+.
LATEST
Support only the latest version available.

Custom Certs ​

If you need to connect to ldaps secured against a custom certificate of authority (CA), you will need to install the custom CA on your system.

For OpenLDAP, by default, the CA must be installed under the directory specified in the TLS_CACERTDIR option found under /etc/openldap/ldap.conf (default value is /etc/openldap/certs).

After copying the CA, you'll need to run "c_rehash ." inside the directory, this will create a symlink pointing to the CA.

You can test the CA installation with this command:

sh
$ openssl s_client -connect yourldap.example.org:636 \
      -CApath /etc/openldap/certs -showcerts

This should report "Verify return code: 0 (ok)".

SASL binds ​

It's possible to use SASL binds instead of the regular simple binds if your LDAP library supports them.

Note

SASL binds are currently incompatible with authentication binds.

Active Directory ​

When connecting to AD, you may need to use port 3268. Then again, not all LDAP fields are available in port 3268. Use whatever works. See: https://technet.microsoft.com/en-us/library/cc978012.aspx.

LDAP Driver Configuration ​

passdb ldap {
  ...
}

This enables LDAP to be used as passdb. The most important settings are:

  • Configure how the LDAP server is reached. (Active directory allows binding with username@domain):
  ldap_uris = ldap://ldap.example.com
  ldap_auth_dn = cn=admin,dc=example,dc=com
  ldap_auth_dn_password = secret
  ldap_base = dc=example,dc=com
  • Use LDAP authentication binding for verifying users' passwords:
passdb ldap {
  bind_userdn = %{user}
  bind = yes
}
  • Use auth worker processes to perform LDAP lookups in order to use multiple concurrent LDAP connections. Otherwise only a single LDAP connection is used.
(passdb|userdb) ... {
  use_worker = yes
}
  • Normalize the username to exactly the mailRoutingAddress field's value regardless of how the passdb_ldap_filter found the user:
passdb ldap {
  fields {
      user     = %{ldap:mailRoutingAddress}
      password = %{ldap:userPassword}
      proxy    = y
      proxy_timeout = 10
  }
}
  • Returns userdb fields when prefetch userdb wasn't used (LMTP & doveadm). The username is again normalized in case user_filter found it via some other means:
passdb ldap {
  fields {
    user = %{ldap:mailRoutingAddress}
    quota_storage_size = %{ldap:messageQuotaHard}B
  }
}
  • How to find the user for passdb lookup (this can be set specifically to distinct values inside each passdb / userdb section):
passdb ldap {
  filter = (mailRoutingAddress=%{user})
}
  • How to iterate through all the valid usernames:
userdb ldap {
  filter = (mailRoutingAddress=%{user})
  iterate_filter = (objectClass=messageStoreRecipient)
  iterate_fields {
    user = %{ldap:mailRoutingAddress}
  }
}

LDAP-Specific Variables ​

The following variables can be used inside the passdb / userdb sections:

VariableDescription
%{ldap:attrName}Fetches a single-valued attribute. Fails if the attribute is not present, unless the `
%{ldap_multi:attrName}Added: 2.4.0 Fetches a multi-valued attribute and outputs the values separated by tabs, with each value "tab-escaped". Use the list filter to further convert it to a wanted value. For example: mail_access_groups = %{ldap_multi:userGroups | list | default('mail')}
%{ldap:dn}Retrieves the Distinguished Name of the entry.

Multiple Queries via userdbs ​

Example: Give the user a class attribute, which defines the default quota:

userdb ldap1 {
  driver = ldap
  result_success = continue-ok
  fields {
    class = %{ldap:userClass}
    quota_storage_size = %{ldap:quotaBytes}B
  }
}

userdb ldap2 {
  driver = ldap
  skip = notfound
  fields {
    quota_storage_size:default = %{ldap:classQuotaBytes}B
  }
}

Variables and Domains ​

User names and domains may be distinguished using the Variables %{user | username} and %{user | domain}. They split the previous username at the @ character.

The previous username is:

  • For LMTP, it will be user@hostname, where hostname depends on, e.g., the Postfix configuration.

  • For IMAP, it will be whatever the password database has designated as the username.

    If the (LDAP) password database has:

    fields {
  user = %{user | username}
}

    then the domain part of the login name will be stripped by the password database.

  • The userdb will not see any domain part, i.e. %{user | username} and %{user} are the same thing for the userdb. The userdb may set a new username, too, using:

    fields {
  user = ...
}

    This will be used for Logging %{user} and %{user | domain} variables in other parts of the configuration (e.g. quota file names).

passdb ldap {
  ...
}

userdb prefetch {
  driver = prefetch
}

userdb ldap {
  ...
}

These enable LDAP to be used as passdb / userdb. The userdb prefetch allows IMAP or POP3 logins to do only a single LDAP lookup by returning the userdb information already in the passdb lookup. prefetch authentication database has more details on the prefetch userdb.

LDAP Settings ​

ldap_auth_dn

Default[None]
Valuestring

Specify the Distinguished Name (the username used to login to the LDAP server).

Leave it commented out to bind anonymously (useful with passdb_ldap_bind = yes).

Example: ldap_auth_dn = uid=dov-read,dc=example,dc=com,dc=.

ldap_auth_dn_password

Default[None]
Valuestring

Password for LDAP server. Used if ldap_auth_dn is specified.

ldap_auth_sasl_authz_id

Default[None]
Valuestring

SASL authorization ID, ie. the ldap_auth_dn_password is for this "master user", but the ldap_auth_dn is still the logged in user. Normally you want to keep this empty.

ldap_auth_sasl_mechanisms

Default[None]
ValueBoolean List

List of SASL mechanism names to use.

ldap_auth_sasl_realm

Default[None]
Valuestring

SASL realm to use.

ldap_base

Default[None]
Valuestring

LDAP base.

Settings variables can be used.

Example: ldap_base = dc=mail, dc=example, dc=org

ldap_connection_group

Default[None]
Valuestring

Only databases with the same connection group share the ldap connections. By default all the databases have the same ""(empty string) default connection group, and as such share the connections.

ldap_debug_level

Default0
Valueunsigned integer

LDAP library debug level as specified by LDAP_DEBUG_* in ldap_log.h.

Value -1 means everything.

You may need to recompile OpenLDAP with debugging enabled to get enough output.

ldap_deref

Defaultnever
Valuestring
Allowed Valuesneversearchingfindingalways

Specify dereference which is set as an LDAP option.

ldap_scope

Defaultsubtree
Valuestring
Allowed Valuesbaseonelevelsubtree

This specifies the search scope.

ldap_starttls

Defaultno
Valueboolean

Set to yes to use TLS to connect to the LDAP server.

ldap_uris

Default[None]
Valuestring

LDAP URIs to use.

Configure this setting to specify what LDAP server(s) to connect to.

The URIs are in syntax protocol://host:port.

Example: ldap_uris = ldaps://secure.domain.org

ldap_version

Default3
Valueunsigned integer

LDAP protocol version to use. Likely 2 or 3.

passdb_ldap_bind

Defaultno
Valueboolean

Set yes to use authentication binding for verifying password's validity.

This works by logging into LDAP server using the username and password given by client.

The passdb_ldap_filter is used to find the DN for the user. Note that the passdb_fields are still used, only the password field is ignored in it.

Before doing any search, the binding is switched back to the default DN.

If you use this setting, it's a good idea to use a different ldap_connection_group for userdb. That way one connection is used only for LDAP binds and another connection is used for user lookups. Otherwise the binding is changed to the default DN before each user lookup.

passdb_ldap_bind_userdn

Default[None]
Valuestring

If authentication binding is used, you can save one LDAP request per login if users' DN can be specified with a common template. The template can use the standard Settings variables.

Note that you can't use any passdb_fields declaration if you use this setting.

Example: passdb_ldap_bind_userdn = cn=%{user},ou=people,o=org

passdb_ldap_filter

Default[None]
Valuestring

Filter for passdb lookup.

Variables that can be used (see Settings variables for full list).

Example:

passdb ldap {
  filter = (&(objectClass=posixAccount)(uid=%{user}))
  #...
}

userdb_ldap_filter

Default[None]
Valuestring

Filter for userdb lookup.

Variables that can be used (see Settings variables for full list).

Example:

userdb ldap {
  filter = (&(objectClass=posixAccount)(uid=%{user}))
  #...
}

userdb_ldap_iterate_fields

Default[None]
ValueString List

Attributes to get a list of all users. Currently only the attribute user is supported.

Example:

userdb ldap {
  iterate_filter = (objectClass=smiMessageRecipient)
  iterate_attrs {
    user = %{ldap:mailRoutingAddress}
  }
}

userdb_ldap_iterate_filter

Default[None]
Valuestring

Filter to get a list of all users.

userdb ldap {
  iterate_filter = (objectClass=smiMessageRecipient)
  iterate_attrs {
    user = %{ldap:mailRoutingAddress}
  }
}

LDAP userdb ​

Usually your LDAP database also contains the userdb.

If your home directory can be specified with a template and you're using only a single UID and GID, you should use static authentication database instead to avoid an unnecessary LDAP lookup. You can also use prefetch authentication database to avoid the userdb LDAP lookup.

Userdb lookups are always done using the default DN (dn setting) bind. It's not possible to do the lookup using the user's DN (remember that e.g. LDA or LMTP Server needs to do userdb lookups without knowing the user's password).

The userdb lookups are configured in very much the same way as password lookups. userdb_fields and userdb_ldap_filter, are used in the same way in passdb.

If you're using a single UID and GID for all the users, you can specify them globally with mail_uid and mail_gid settings instead of returning them from LDAP.

userdb ldap {
  filter = (&(objectClass=posixAccount)(uid=%{user}))
  fields {
    home = %{ldap:homeDirectory}
    uid = %{ldap:uidNumber}
    gid = %{ldap:gidNumber}
  }
}

For using doveadm -A: ​

userdb ldap {
  iterate_filter = (objectClass=posixAccount)
  iterate_fields {
    user = %{ldap:uid}
  }
}

Attribute Templates ​

You can mix static text with the value returned from LDAP by using %{ldap:*} variables, which expand to the named LDAP attribute's value.

Examples ​

Create a quota_storage_size field with value <n>B where <n> comes from "quotaBytes" LDAP attribute:

userdb ldap {
  fields {
    quota_storage_size = %{ldap:quotaBytes}B
  }
}

Create a mail_path field with value /var/mail/<dir>/Maildir where <dir> comes from "sAMAccountName" LDAP attribute:

userdb ldap {
  fields {
    mail_path = /var/spool/vmail/%{ldap:sAMAccountName}/Maildir
  }
}

You can add static fields that aren't looked up from LDAP. For example create a "mail_path" field with value /var/vmail/%{user | domain}/%{user | username}/Maildir:

userdb ldap {
  fields {
    quota_storage_size = %{ldap:quotaBytes}B
    mail_path = /var/vmail/%{user | domain}/%{user | username}/Maildir
  }
}

It is possible to give default values to nonexistent attributes by using e.g. %{ldap:userDomain:example.com} where if userDomain attribute doesn't exist, example.com is used instead.

Variables and Domains ​

User names and domains may be distinguished using the Settings variables%{user | username} and %{user | domain}. They split the previous username at the "@" character. The previous username is:

  • For LMTP, it will be user@hostname, where hostname depends on e.g. the Postfix configuration.

  • For IMAP, it will be whatever the password database has designated as the username. If the (LDAP) password database passdb_fields contains user=%{user | username}, then the domain part of the login name will be stripped by the password database. The userdb will not see any domain part, i.e. %{user | username} and %{user} are the same thing for the userdb.

The userdb may set a new username, too, using

userdb ldap {
  fields {
    user = ...
  }
}

This will be used for:

  • Logging

  • %{user} and %{user | domain} variables in other parts of the configuration (e.g. quota file names)

Copyright © Open-Xchange GmbH