NAME

ldap.conf - Configures the interface for authenticating end users via LDAP

SYNOPSIS

/opt/pmx6/etc/enduser/auth.d/ldap.conf

DESCRIPTION

The configuration directives are as follows:

Specifies the 'host:port' of the server(s) to connect to in order to authenticate users via LDAP. You can provide a list of hosts, each on its own line. If no ':port' is specified, port 389 is used by default.

Note: It is strongly advised that you specify two or more LDAP servers. This is done by separating the URLs with spaces, for example:

    ldap://myhost1:389 ldap://myhost2:389 ldap://myhost3:389

To use an encrypted LDAPS connection, simply prefix the host:port with 'ldaps://' (please see example below). For LDAPS connections, port 636 is the default.

Example:

  <ldap_server>
      ldaps://localhost:636
  </ldap_server>

bind_dn

bind_password

Specifies the Distinguished Name and password used to connect to the LDAP server in order to query the Distinguished Name of the user to be authenticated. This DN/password should be granted minimal rights, but it must be able to perform a query to retrieve the DN for a user based on the name/ID provided by the user.

Note that bind_dn is subject to variable substitution (see Variable Substitution below).

base_dn

Specifies the top LDAP directory node underneath which the search is performed to retrieve the Distinguished Name of the user that the system is attempting to authenticate.

Example:

  base_dn = "OU=Users,DC=mydomain,DC=com"

The base_dn is also subject to variable substitution (see Variable Substitution below).

filter

Specifies the LDAP query performed to retrieve the Distinguished Name of the user account to be authenticated. This filter should return one (and only one) result record; you may experience inconsistent behavior if the filter returns multiple results.

Note that the filter is subject to variable substitution (see Variable Substitution below).

Examples:

To query an Active Directory server by 'sAMAccountName':

    (&(sAMAccountName=%%username%%)(mail=*))

To query an LDAP server by 'mail':

    (mail=%%username%%)

attribute_mail

Specifies the LDAP attribute within your LDAP schema that refers to the 'primary email address' for a user. Defaults to 'mail' if not provided.

Variable Substitution

Some, but not all, of the configuration options in ldap.conf are subject to variable substitution, which is used to substitute information or values into the configuration directives using a pre-defined syntax. Refer to the individual ldap.conf options to see which of them support variable substitution.

The following variables are available for substitution:

%%username%%: The full username as provided by the user on the login page.
%%password%%: The full password as provided by the user on the login page.
%%bind_dn%%: The Bind DN as specified in the configuration.
%%base_dn%%: The Base DN as specified in the configuration.

Examples:

Filter to query an ActiveDirectory server by 'sAMAccountName':

  (&(sAMAccountName=%%username%%)(mail=*))

Filter to query an LDAP server by 'mail':

  (mail=%%username%%)

Bind DN based on the Base DN

  CN=%%username%%,%%base_dn%%

Advanced Configuration

The following additional ldap.conf configuration options are recommended for use by advanced administrators only.

debug

Note: This configuration option is recommended for use by advanced administrators only.

Enables debug logging to the error log. This option generates a significant amount of debugging information and is recommended for use during testing only.

dn_discovery

Note: This configuration option is recommended for use by advanced administrators only.

Enables the 'User DN Discovery' phase of the LDAP Authenticator. When enabled, the LDAP Authenticator attempts to auto-discover the User DN, and uses the provided 'ind_dn/bind_password' to connect to the LDAP server to do this discovery. When disabled, the LDAP Authenticator attempts to authenticate directly by using the bind_dn as the User DN, along with the password provided by the user on the login form.

attribute_mail_index

Note: This configuration option is recommended for use by advanced administrators only.

Specifies the index of the 'attribute_mail' LDAP attribute that is returned as the primary email address for the user. Note that if an LDAP query returns less result items than this index, the authentication is considered to have failed.

NAME

SYNOPSIS

DESCRIPTION

Variable Substitution

Advanced Configuration

COPYRIGHT