# $OpenLDAP$
-# Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
+# Portions Copyright 2008 Andrew Findlay.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Security Considerations
allows only incoming connections from the private network {{F:10.0.0.0}}
and localhost ({{F:127.0.0.1}}) to access the directory service.
-Note that IP addresses are used as {{slapd}}(8) is not normally
+
+Note: IP addresses are used as {{slapd}}(8) is not normally
configured to perform reverse lookups.
It is noted that TCP wrappers require the connection to be accepted.
An anonymous bind results in an {{anonymous}} authorization
association. Anonymous bind mechanism is enabled by default, but
can be disabled by specifying "{{EX:disallow bind_anon}}" in
-{{slapd.conf}}(5). Note that disabling the anonymous bind mechanism
-does not prevent anonymous access to the directory. To require
-authentication to access the directory, one should instead
-specify "{{EX:require authc}}".
+{{slapd.conf}}(5).
+
+Note: Disabling the anonymous bind mechanism does not prevent
+anonymous access to the directory. To require authentication to
+access the directory, one should instead specify "{{EX:require authc}}".
An unauthenticated bind also results in an {{anonymous}} authorization
association. Unauthenticated bind mechanism is disabled by default,
The user/password authenticated bind mechanism can be completely
disabled by setting "{{EX:disallow bind_simple}}".
-Note: An unsuccessful bind always results in the session having
+Note: An unsuccessful bind always results in the session having
an {{anonymous}} authorization association.
H3: SASL method
-The LDAP {{TERM:SASL}} method allows use of any SASL authentication
-mechanism. The {{SECT:Using SASL}} discusses use of SASL.
+The LDAP {{TERM:SASL}} method allows the use of any SASL authentication
+mechanism. The {{SECT:Using SASL}} section discusses the use of SASL.
+
+H2: Password Storage
+
+LDAP passwords are normally stored in the {{userPassword}} attribute.
+{{REF:RFC4519}} specifies that passwords are not stored in encrypted
+(or hashed) form. This allows a wide range of password-based
+authentication mechanisms, such as {{EX:DIGEST-MD5}} to be used.
+This is also the most interoperable storage scheme.
+
+However, it may be desirable to store a hash of password instead.
+{{slapd}}(8) supports a variety of storage schemes for the administrator
+to choose from.
+
+Note: Values of password attributes, regardless of storage scheme
+used, should be protected as if they were clear text. Hashed
+passwords are subject to {{dictionary attacks}} and {{brute-force
+attacks}}.
+
+The {{userPassword}} attribute is allowed to have more than one value,
+and it is possible for each value to be stored in a different form.
+During authentication, {{slapd}} will iterate through the values
+until it finds one that matches the offered password or until it
+runs out of values to inspect. The storage scheme is stored as a prefix
+on the value, so a hashed password using the Salted SHA1 ({{EX:SSHA}})
+scheme looks like:
+
+> userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
+
+The advantage of hashed passwords is that an attacker which
+discovers the hash does not have direct access to the actual password.
+Unfortunately, as dictionary and brute force attacks are generally
+quite easy for attackers to successfully mount, this advantage is
+marginal at best (this is why all modern Unix systems use shadow
+password files).
+
+The disadvantages of hashed storage is that they are non-standard, may
+cause interoperability problem, and generally preclude the use
+of stronger than Simple (or SASL/PLAIN) password-based authentication
+mechanisms such as {{EX:DIGEST-MD5}}.
+
+H3: SSHA password storage scheme
+
+This is the salted version of the SHA scheme. It is believed to be the
+most secure password storage scheme supported by {{slapd}}.
+
+These values represent the same password:
+
+> userPassword: {SSHA}DkMTwBl+a/3DQTxCYEApdUtNXGgdUac3
+> userPassword: {SSHA}d0Q0626PSH9VUld7yWpR0k6BlpQmtczb
+
+H3: CRYPT password storage scheme
+
+This scheme uses the operating system's {{crypt(3)}} hash function.
+It normally produces the traditional Unix-style 13 character hash, but
+on systems with {{EX:glibc2}} it can also generate the more secure
+34-byte MD5 hash.
+
+> userPassword: {CRYPT}aUihad99hmev6
+> userPassword: {CRYPT}$1$czBJdDqS$TmkzUAb836oMxg/BmIwN.1
+
+The advantage of the CRYPT scheme is that passwords can be
+transferred to or from an existing Unix password file without having
+to know the cleartext form. Both forms of {{crypt}} include salt so
+they have some resistance to dictionary attacks.
+
+Note: Since this scheme uses the operating system's {{crypt(3)}}
+hash function, it is therefore operating system specific.
+
+H3: MD5 password storage scheme
+
+This scheme simply takes the MD5 hash of the password and stores it in
+base64 encoded form:
+
+> userPassword: {MD5}Xr4ilOzQ4PCOq3aQ0qbuaQ==
+
+Although safer than cleartext storage, this is not a very secure
+scheme. The MD5 algorithm is fast, and because there is no salt the
+scheme is vulnerable to a dictionary attack.
+
+H3: SMD5 password storage scheme
+
+This improves on the basic MD5 scheme by adding salt (random data
+which means that there are many possible representations of a given
+plaintext password). For example, both of these values represent the
+same password:
+
+> userPassword: {SMD5}4QWGWZpj9GCmfuqEvm8HtZhZS6E=
+> userPassword: {SMD5}g2/J/7D5EO6+oPdklp5p8YtNFk4=
+
+H3: SHA password storage scheme
+
+Like the MD5 scheme, this simply feeds the password through an SHA
+hash process. SHA is thought to be more secure than MD5, but the lack
+of salt leaves the scheme exposed to dictionary attacks.
+
+> userPassword: {SHA}5en6G6MezRroT3XKqkdPOmY/BfQ=
+
+H3: SASL password storage scheme
+
+This is not really a password storage scheme at all. It uses the
+value of the {{userPassword}} attribute to delegate password
+verification to another process. See below for more information.
+
+Note: This is not the same as using SASL to authenticate the LDAP
+session.
+
+H3: KERBEROS password storage scheme
+
+This is not really a password storage scheme at all. It uses the
+value of the {{userPassword}} attribute to delegate password
+verification to Kerberos.
+
+Note: This is not the same as using Kerberos authentication of
+the LDAP session.
+
+This scheme could be said to defeat the advantages of Kerberos by
+causing the Kerberos password to be exposed to the {{slapd}} server
+(and possibly on the network as well).
+
+H2: Pass-Through authentication
+
+Since OpenLDAP 2.0 {{slapd}} has had the ability to delegate password
+verification to a separate process. This uses the {{sasl_checkpass(3)}}
+function so it can use any back-end server that Cyrus SASL supports for
+checking passwords. The choice is very wide, as one option is to use
+{{saslauthd(8)}} which in turn can use local files, Kerberos, an IMAP
+server, another LDAP server, or anything supported by the PAM mechanism.
+
+The server must be built with the {{EX:--enable-spasswd}}
+configuration option to enable pass-through authentication.
+
+Note: This is not the same as using a SASL mechanism to
+authenticate the LDAP session.
+
+Pass-Through authentication works only with plaintext passwords, as
+used in the "simple bind" and "SASL PLAIN" authentication mechanisms.}}
+
+Pass-Through authentication is selective: it only affects users whose
+{{userPassword}} attribute has a value marked with the "{SASL}"
+scheme. The format of the attribute is:
+
+> userPassword: {SASL}username@realm
+
+The {{username}} and {{realm}} are passed to the SASL authentication
+mechanism and are used to identify the account whose password is to be
+verified. This allows arbitrary mapping between entries in OpenLDAP
+and accounts known to the backend authentication service.
+
+Note: There is no support for changing passwords in the backend
+via {{slapd}}.
+
+It would be wise to use access control to prevent users from changing
+their passwords through LDAP where they have pass-through authentication
+enabled.
+
+
+H3: Configuring slapd to use an authentication provider
+
+Where an entry has a "{SASL}" password value, OpenLDAP delegates the
+whole process of validating that entry's password to Cyrus SASL. All
+the configuration is therefore done in SASL config files.
+
+The first
+file to be considered is confusingly named {{slapd.conf}} and is
+typically found in the SASL library directory, often
+{{EX:/usr/lib/sasl2/slapd.conf}} This file governs the use of SASL
+when talking LDAP to {{slapd}} as well as the use of SASL backends for
+pass-through authentication. See {{EX:options.html}} in the {{PRD:Cyrus SASL}}
+docs for full details. Here is a simple example for a server that will
+use {{saslauthd}} to verify passwords:
+
+> mech_list: plain
+> pwcheck_method: saslauthd
+> saslauthd_path: /var/run/sasl2/mux
+
+H3: Configuring saslauthd
+
+{{saslauthd}} is capable of using many different authentication
+services: see {{saslauthd(8)}} for details. A common requirement is to
+delegate some or all authentication to another LDAP server. Here is a
+sample {{EX:saslauthd.conf}} that uses Microsoft Active Directory (AD):
+
+> ldap_servers: ldap://dc1.example.com/ ldap://dc2.example.com/
+>
+> ldap_search_base: cn=Users,DC=ad,DC=example,DC=com
+> ldap_filter: (userPrincipalName=%u)
+>
+> ldap_bind_dn: cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com
+> ldap_password: secret
+
+In this case, {{saslauthd}} is run with the {{EX:ldap}} authentication
+mechanism and is set to combine the SASL realm with the login name:
+
+> saslauthd -a ldap -r
+
+This means that the "username@realm" string from the {{userPassword}}
+attribute ends up being used to search AD for
+"userPrincipalName=username@realm" - the password is then verified by
+attempting to bind to AD using the entry found by the search and the
+password supplied by the LDAP client.
+
+H3: Testing pass-through authentication
+
+It is usually best to start with the back-end authentication provider
+and work through {{saslauthd}} and {{slapd}} towards the LDAP client.
+
+In the AD example above, first check that the DN and password that
+{{saslauthd}} will use when it connects to AD are valid:
+
+> ldapsearch -x -H ldap://dc1.example.com/ \
+> -D cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com \
+> -w secret \
+> -b '' \
+> -s base
+
+Next check that a sample AD user can be found:
+
+> ldapsearch -x -H ldap://dc1.example.com/ \
+> -D cn=saslauthd,cn=Users,DC=ad,DC=example,DC=com \
+> -w secret \
+> -b cn=Users,DC=ad,DC=example,DC=com \
+> "(userPrincipalName=user@ad.example.com)"
+
+Check that the user can bind to AD:
+
+> ldapsearch -x -H ldap://dc1.example.com/ \
+> -D cn=user,cn=Users,DC=ad,DC=example,DC=com \
+> -w userpassword \
+> -b cn=user,cn=Users,DC=ad,DC=example,DC=com \
+> -s base \
+> "(objectclass=*)"
+
+If all that works then {{saslauthd}} should be able to do the same:
+
+> testsaslauthd -u user@ad.example.com -p userpassword
+> testsaslauthd -u user@ad.example.com -p wrongpassword
+
+Now put the magic token into an entry in OpenLDAP:
+
+> userPassword: {SASL}user@ad.example.com
+
+It should now be possible to bind to OpenLDAP using the DN of that
+entry and the password of the AD user.
projects / openldap / blobdiff