LOGIN_LDAP(8)

NAME
login_ldap - contact LDAP directory server for authentication

SYNOPSIS
login_ldap [-s service] [-d] [-v name=value] user [class]

DESCRIPTION
The login_ldap utility contacts the slapd(8) daemon to authenticate a user. If no class is specified, the login class will be obtained from the password database.

When executed as the name login_style, login_ldap will request slapd(8) use the authentication specified by style.

Available options are:

-s  Specify the service. Currently only login and response are supported. The challenge service is not supported, but it is not an error to specify this service. If this happens login_ldap will request the response service.

-d  Print debugging information.

-v  This option and its value are ignored.

The login_ldap utility will perform up to two searches on the LDAP server to identify the user's DN, and will then attempt to bind using the supplied password.

The first pass occurs for all users to be authenticated with this utility, and searches for the given username in the section given by the specified basedn (see below). The second pass occurs only if values for x-ldap-groupdn and x-ldap-groupfilter are present in login.conf. This second pass will check that the user is present in the section of the directory represented by x-ldap-groupdn, according to the specification of x-ldap-groupfilter.

LOGIN.CONF VARIABLES
The login_ldap utility requires the following LDAP-specific login.conf(5) variables:

x-ldap-server
    Hostname or IP Adress of the primary server to contact for authorization requests. See SERVER FORMATS for details.

x-ldap-basedn
    Point in the LDAP server's Directory Information Tree login_ldap should begin searching for user objects.

In most cases, you will need to configure additional options.

The following entries to login.conf are also recognised by login_ldap and are optional:

x-ldap-binddn
    DN used by login_ldap to bind to the ldap server. Leave this out for an anonymous bind.

x-ldap-bindpw
    Password used by login_ldap to bind to the ldap server. Leave this out for a passwordless bind.

x-ldap-filter
    LDAP search filter (in accordance with RFC 1558) which identifies the objectclass(s) and attribute(s) necessary for login_ldap to locate the user object. See the FILTER FORMATS section for details.

x-ldap-noreferrals
    If present, login_ldap will turn off LDAP referrals.

x-ldap-refkeepcreds
    If present, login_ldap will use x-ldap-binddn and x-ldap-bindpw when attempting to bind to servers obtained via referral. The default is to attempt anonymous binds in the case of referrals.

x-ldap-serveraltN
    Server info of alternate ldap servers to use when the primary is not responding. N starts at 0 (e.g. x-ldap-serveralt0) and increasing sequentially by 1 can range up to 9999, allowing 10,000 alternate servers to be configured.

x-ldap-timeout
    Time in seconds to wait for the ldap server to respond to a query. The default is 60 seconds per query, with up to four queries occuring. There is a hard limit of 5 minutes (300 seconds) for any login session to take place.

x-ldap-groupdn
    DN of the group object in which membership of is a pre-requisite for authorization. If this is set be sure to specify a value for x-ldap-groupfilter.

x-ldap-groupfilter
    LDAP search filter (in accordance with RFC 1558) which identifies the objectclass(s) and attribute(s) necessary for login_ldap to determine group membership in the DN defined by x-ldap-groupdn.

x-ldap-uscope
    The directory scope when performing the user lookup (first pass) search. Acceptable values are:

    base
        Base object search

    one One level search

    sub Full subtree search

    The default is sub if x-ldap-uscope is unspecified.

x-ldap-gscope
    The directory scope when performing the group lookup search (second pass). See the entry for x-ldap-uscope for details of values. The default is sub if x-ldap-gscope is unspecified.

The following options are used to configure SSL/TLS behaviour as implemented by OpenLDAP and OpenSSL. The CA certificate file and CA certificate directory may also be specified in the global ldap.conf(5) file, typically /etc/openldap/ldap.conf. If they are set in login.conf, they will override any values specified in ldap.conf.

x-ldap-cacertdir
    The directory containing the certificates of trusted CA's

x-ldap-cacert
    The pathname of the CA used for SSL certificates.

x-ldap-usercert
    The pathname of the users SSL certificate.

x-ldap-userkey
    The pathname to the users key.

If x-ldap-usercert or x-ldap-userkey are unspecified, they will be set to NULL for all OpenLDAP operations. This is to prevent any unexpected behaviour due to per user ldap.conf(5) settings (for instance values set in ~/.ldaprc).

If present in x-ldap-usercert or x-ldap-userkey, the format specifiers %u and %h will be processed as described in the FILTER FORMATS section.

FILTER FORMATS
The following format specifiers are valid for the x-ldap-filter and x-ldap-groupfilter login.conf(5) variables:

%u  Username. The username of the user to be authenticated as specified by the user argument.

%h  Hostname. The hostname of the host the user is trying to authenticate on, as returned by gethostname(3) and displayed by hostname(1).

The following filter format is only valid for the x-ldap-groupfilter login.conf variable

%d  The dn of the user attempting authentication as returned from the first pass of the search.

SERVER FORMATS
The values for x-ldap-server and x-ldap-serveralt should be a list delimited by the comma character ``,''. The fields in order are: hostname of the server, port to use, ssl/tls mode and version. The hostname must be present, all others are optional.

The hostname of the server should be a fully qualified domain name, for example foo.ifost.org.au.

The port is simply an integer. If the mode (see below) is 'plain' or 'starttls' it defaults to 389, if the mode is 'ssl' it defaults to 636.

The SSL/TLS mode is one of:

starttls
    Connect to the standard port, send a StartTLS request, and negotiate SSL/TLS.

ssl Connect to the "ssl-wrapped" port, negotiate SSL/TLS.

plain
    INSECURE - no attempt will made to use SSL/TLS.

The version is an integer, either 1, 2 or 3. The default is to use LDAP version 3.

Apart from the hostname, options may be left out or left blank. For example, the following would result in SSL being used on port 636, with LDAPv3:

x-ldap-server=foo.ifost.org.au,,ssl

Similarly, the following would result in an insecure connection to the host on port 389:

x-ldap-server=bar.ifost.org.au

EXAMPLES
For more examples, please see the following files.

/usr/local/share/examples/login_ldap/login_ldap.conf
/usr/local/share/examples/login_ldap/active-directory.login_ldap.conf

FILES
/etc/login.conf
    login configuration database

SEE ALSO
login.conf(5), login(8), ldap.conf(5)

AUTHORS
Peter Werner <peterw@ifost.org.au>, Michael Erdely <merdely@openbsd.org>

Please direct all questions/problems/suggestions to Peter Werner or Michael Erdely.

Raul Aldaz <raul.aldaz@grupocarreras.com>

Please contact Michael Erdely with any issues relating to the port.

CAVEATS
As there is no SASL support, passwords are sent to the LDAP server. TLS should be used to protect the password in transit.

As of version 3.4 the default scope is sub, which is what most people want.

There have been some significant changes to the login.conf variables, in particular how servers are specified.

login_ldap does not provide user account maps, only authentication services. User accounts may be handled either via ypldap(8) or by static entries in the passwd(5) file (e.g. by using useradd(8) with arguments like this: useradd -m -d /home/peterw -s /bin/sh -L ldap peterw).