-# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Using SASL
OpenLDAP clients and servers are capable of authenticating via the
{{TERM[expand]SASL}} ({{TERM:SASL}}) framework, which is detailed
-in {{REF:RFC2222}}. This chapter describes how to make use of
+in {{REF:RFC4422}}. This chapter describes how to make use of
SASL in OpenLDAP.
There are several industry standard authentication mechanisms that
-can be used with SASL, including {{TERM:Kerberos}} V4, {{TERM:GSSAPI}},
-and DIGEST-MD. The standard client tools provided with OpenLDAP,
-such as {{ldapsearch}}(1) and {{ldapmodify}}(1), will by default
-attempt to authenticate the user to the {{slapd}}(8) server using
-SASL. Basic authentication service can be set up by the LDAP
+can be used with SASL, including {{TERM:GSSAPI}} for {{TERM:Kerberos}}
+V, {{TERM:DIGEST-MD5}}, and {{TERM:PLAIN}} and {{TERM:EXTERNAL}}
+for use with {{TERM[expand]TLS}} (TLS).
+
+The standard client tools provided with OpenLDAP Software, such as
+{{ldapsearch}}(1) and {{ldapmodify}}(1), will by default attempt
+to authenticate the user to the {{TERM:LDAP}} directory server using
+SASL. Basic authentication service can be set up by the LDAP
administrator with a few steps, allowing users to be authenticated
to the slapd server as their LDAP entry. With a few extra steps,
some users and services can be allowed to exploit SASL's proxy
then switch their identity to that of another user or service.
This chapter assumes you have read {{Cyrus SASL for System
-Administrators}}, provided with the {{PRD:Cyrus}} {{PRD:SASL}}
+Administrators}}, provided with the {{PRD:Cyrus SASL}}
package (in {{FILE:doc/sysadmin.html}}) and have a working Cyrus
SASL installation. You should use the Cyrus SASL {{EX:sample_client}}
and {{EX:sample_server}} to test your SASL installation before
-attempting to make use of it in OpenLDAP.
+attempting to make use of it with OpenLDAP Software.
Note that in the following text the term {{user}} is used to describe
a person or application entity who is connecting to the LDAP server
SASL offers many different authentication mechanisms. This section
briefly outlines security considerations.
-Some mechanisms, such as PLAIN and LOGIN, offer no greater security over
-LDAP "simple" authentication. Like "simple" authentication, such
-mechanisms should not be used unless you have adequate security
-protections in place. It is recommended that these mechanisms be
-used only in conjunction with {{TERM[expand]TLS}} (TLS). Use of
-PLAIN and LOGIN are not discussed further in this document.
+Some mechanisms, such as PLAIN and LOGIN, offer no greater security
+over LDAP {{simple}} authentication. Like LDAP {{simple}}
+authentication, such mechanisms should not be used unless you have
+adequate security protections in place. It is recommended that
+these mechanisms be used only in conjunction with {{TERM[expand]TLS}}
+(TLS). Use of PLAIN and LOGIN are not discussed further in this
+document.
The DIGEST-MD5 mechanism is the mandatory-to-implement authentication
mechanism for LDAPv3. Though DIGEST-MD5 is not a strong authentication
mechanism in comparison with trusted third party authentication
-systems (such as Kerberos or public key systems), yet it does offer
-significant protections against a number of attacks. Unlike the
-CRAM-MD5 mechanism, it prevents chosen plaintext attacks. DIGEST-MD5
-is favored over the weaker and even more dangerous use of plaintext
-password mechanisms. The CRAM-MD5 mechanism is deprecated in favor
-of DIGEST-MD5. Use of {{SECT:DIGEST-MD5}} is discussed below.
-
-The KERBEROS_V4 mechanism utilizes Kerberos IV to provide secure
-authentication services. There is also a GSSAPI based mechanism
-which is generally used in conjunction with Kerberos V. Kerberos
-is viewed as a secure, distributed authentication system suitable
-for both small and large enterprises. Use of {{SECT:KERBEROS_V4}}
-and {{SECT:GSSAPI}} are discussed below.
+systems (such as {{TERM:Kerberos}} or public key systems), it does
+offer significant protections against a number of attacks. Unlike
+the {{TERM:CRAM-MD5}} mechanism, it prevents chosen plaintext
+attacks. DIGEST-MD5 is favored over the use of plaintext password
+mechanisms. The CRAM-MD5 mechanism is deprecated in favor of
+DIGEST-MD5. Use of {{SECT:DIGEST-MD5}} is discussed below.
+
+The GSSAPI mechanism utilizes {{TERM:GSS-API}} {{TERM:Kerberos}} V
+to provide secure authentication services. The KERBEROS_V4 mechanism
+is available for those using Kerberos IV. Kerberos is viewed as a
+secure, distributed authentication system suitable for both small
+and large enterprises. Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}}
+are discussed below.
The EXTERNAL mechanism utilizes authentication services provided
-by lower level network services such as {{TERM:TLS}} (TLS). When
+by lower level network services such as {{TERM[expand]TLS}} ({{TERM:TLS}}). When
used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public
-key technology, EXTERNAL offers strong authentication. Use of
-EXTERNAL is discussed in the {{SECT:Using TLS}} chapter.
+key technology, EXTERNAL offers strong authentication.
+TLS is discussed in the {{SECT:Using TLS}} chapter.
+
+EXTERNAL can also be used with the {{EX:ldapi:///}} transport, as
+Unix-domain sockets can report the UID and GID of the client process.
There are other strong authentication mechanisms to choose from,
-including OTP (one time passwords) and SRP (secure remote passwords).
-These mechanisms are not discussed in this document.
+including {{TERM:OTP}} (one time passwords) and {{TERM:SRP}} (secure
+remote passwords). These mechanisms are not discussed in this
+document.
H2: SASL Authentication
Getting basic SASL authentication running involves a few steps.
-The first step configures your slapd server environment so
-that it can communicate with client programs using the security
-system in place at your site. This usually involves setting up a
-service key, a public key, or other form of secret. The second step
-concerns mapping authentication identities to LDAP DN's, which
+The first step configures your slapd server environment so that it
+can communicate with client programs using the security system in
+place at your site. This usually involves setting up a service key,
+a public key, or other form of secret. The second step concerns
+mapping authentication identities to LDAP {{TERM:DN}}'s, which
depends on how entries are laid out in your directory. An explanation
of the first step will be given in the next section using Kerberos
V4 as an example mechanism. The steps necessary for your site's
authentication mechanism will be similar, but a guide to every
mechanism available under SASL is beyond the scope of this chapter.
-The second step is described in the section
-{{SECT:Mapping Authentication identities to LDAP entries}}.
+The second step is described in the section {{SECT:Mapping
+Authentication Identities}}.
+
+
+H3: GSSAPI
+
+This section describes the use of the SASL GSSAPI mechanism and
+Kerberos V with OpenLDAP. It will be assumed that you have Kerberos
+V deployed, you are familiar with the operation of the system, and
+that your users are trained in its use. This section also assumes
+you have familiarized yourself with the use of the GSSAPI mechanism
+by reading {{Configuring GSSAPI and Cyrus SASL}} (provided with
+Cyrus SASL in the {{FILE:doc/gssapi}} file) and successfully
+experimented with the Cyrus provided {{EX:sample_server}} and
+{{EX:sample_client}} applications. General information about
+Kerberos is available at {{URL:http://web.mit.edu/kerberos/www/}}.
+
+To use the GSSAPI mechanism with {{slapd}}(8) one must create a service
+key with a principal for {{ldap}} service within the realm for the host
+on which the service runs. For example, if you run {{slapd}} on
+{{EX:directory.example.com}} and your realm is {{EX:EXAMPLE.COM}},
+you need to create a service key with the principal:
+
+> ldap/directory.example.com@EXAMPLE.COM
+
+When {{slapd}}(8) runs, it must have access to this key. This is
+generally done by placing the key into a keytab file,
+{{FILE:/etc/krb5.keytab}}. See your Kerberos and Cyrus SASL
+documentation for information regarding keytab location settings.
+
+To use the GSSAPI mechanism to authenticate to the directory, the
+user obtains a Ticket Granting Ticket (TGT) prior to running the
+LDAP client. When using OpenLDAP client tools, the user may mandate
+use of the GSSAPI mechanism by specifying {{EX:-Y GSSAPI}} as a
+command option.
+
+For the purposes of authentication and authorization, {{slapd}}(8)
+associates an authentication request DN of the form:
+
+> uid=<primary[/instance]>,cn=<realm>,cn=gssapi,cn=auth
+
+Continuing our example, a user with the Kerberos principal
+{{EX:kurt@EXAMPLE.COM}} would have the associated DN:
+
+> uid=kurt,cn=example.com,cn=gssapi,cn=auth
+
+and the principal {{EX:ursula/admin@FOREIGN.REALM}} would have the
+associated DN:
+
+> uid=ursula/admin,cn=foreign.realm,cn=gssapi,cn=auth
+
+
+The authentication request DN can be used directly ACLs and
+{{EX:groupOfNames}} "member" attributes, since it is of legitimate
+LDAP DN format. Or alternatively, the authentication DN could be
+mapped before use. See the section {{SECT:Mapping Authentication
+Identities}} for details.
+
H3: KERBEROS_V4
authentication policy, how to receive credentials in
a Kerberos ticket cache, and how to refresh expired credentials.
+Note: KERBEROS_V4 and Kerberos IV are deprecated in favor of GSSAPI
+and Kerberos V.
+
Client programs will need to be able to obtain a session key for
use when connecting to your LDAP server. This allows the LDAP server
to know the identity of the user, and allows the client to know it
same principal, either from the ticket cache or by obtaining a new
one from the Kerberos server. This will require the TGT to be
available and valid in the cache as well. If it is not present or
-has expired, SASL will print out the message
+has expired, the client may print out the message:
> ldap_sasl_interactive_bind_s: Local error
> uid=adamsom,cn=example.com,cn=kerberos_v4,cn=auth
-This authentication request DN by itself could be placed into ACL's
-and {{EX:groupOfNames}} "member" attributes, since it is of legitimate
-LDAP DN format. The section
-{{SECT:Mapping Authentication identities to LDAP entries}},
-however, tells how to map that
-DN into the DN of a person's own LDAP entry.
-
-Also note that this example, being for Kerberos, shows the <realm>
-portion of the DN being filled in with the Kerberos realm of the
-company. Several other authentication mechanisms do not employ the
-concept of a realm, so the ",cn=<realm>" portion of the authentication
-request DN would not appear.
-
-
-H3: GSSAPI
-
-This section describes the use of the SASL GSSAPI mechanism and
-Kerberos V with OpenLDAP. Since Kerberos V is being used, the
-information is very similar to the previous section. It will be
-assumed that you have Kerberos V deployed, you are familiar with
-the operation of the system, and that your users are trained in its
-use. This section also assumes you have familiarized yourself with
-the use of the GSSAPI mechanism by reading {{Configuring GSSAPI and
-Cyrus SASL}} (provided with Cyrus SASL in the {{FILE:doc/gssapi}}
-file) and successfully experimented with the Cyrus provided
-{{EX:sample_server}} and {{EX:sample_client}} applications. General
-information about Kerberos is available at
-{{URL:http://web.mit.edu/kerberos/www/}}.
-
-To use the GSSAPI mechanism with {{slapd}}(8) one must create a service
-key with a principal for {{ldap}} service within the realm for the host
-on which the service runs. For example, if you run {{slapd}} on
-{{EX:directory.example.com}} and your realm is {{EX:EXAMPLE.COM}},
-you need to create a service key with the principal:
-
-> ldap/directory.example.com@EXAMPLE.COM
-
-When {{slapd}}(8) runs, it must have access to this key. This is
-generally done by placing the key into a keytab, such as
-{{FILE:/etc/krb5.keytab}}.
-
-To use the GSSAPI mechanism to authenticate to the directory, the
-user obtains a Ticket Granting Ticket (TGT) prior to running the
-LDAP client. When using OpenLDAP client tools, the user may mandate
-use of the GSSAPI mechanism by specifying {{EX:-Y GSSAPI}} as a
-command option.
-
-For the purposes of authentication and authorization, {{slapd}}(8)
-associates a non-mapped authentication request DN of the form:
-
-> uid=<principal>,cn=<realm>,cn=gssapi,cn=auth
-
-Continuing our example, a user
-with the Kerberos principal {{EX:kurt@EXAMPLE.COM}} would have
-the associated DN:
-
-> uid=kurt,cn=example.com,cn=gssapi,cn=auth
-
-and the principal {{EX:ursula@FOREIGN.REALM}} would have the
-associated DN:
-
-> uid=ursula,cn=foreign.realm,cn=gssapi,cn=auth
+This authentication request DN can be used directly ACLs or,
+alternatively, mapped prior to use. See the section {{SECT:Mapping
+Authentication Identities}} for details.
H3: DIGEST-MD5
-This section describes the use of the SASL DIGEST-MD5 mechanism using
-secrets stored either in the directory itself or in Cyrus SASL's own
-database. DIGEST-MD5 relies on the client and the server sharing a
-"secret", usually a password. The server generates a challenge and the
-client a response proving that it knows the shared secret. This is much
-more secure than simply sending the secret over the wire.
-
-Cyrus SASL supports several shared-secret mechanisms. To do this, it
-needs access to the plaintext password (unlike mechanisms which pass
-plaintext passwords over the wire, where the server can store a hashed
-version of the password).
-
-Secret passwords are normally stored in Cyrus SASL's own {{sasldb}}
-database, but if OpenLDAP has been compiled with Cyrus SASL 2.1 it is
-possible to store the secrets in the LDAP database itself. With Cyrus
-SASL 1.5, secrets may only be stored in the {{sasldb}}. In either
-case it is very important to apply file access controls and LDAP access
-controls to prevent exposure of the passwords.
-
-The configuration and commands discussed in this section assume the use
-of Cyrus SASL 2.1. If you are using version 1.5 then certain features
-will not be available, and the command names will not have the trailing
-digit "2".
+This section describes the use of the SASL DIGEST-MD5 mechanism
+using secrets stored either in the directory itself or in Cyrus
+SASL's own database. DIGEST-MD5 relies on the client and the server
+sharing a "secret", usually a password. The server generates a
+challenge and the client a response proving that it knows the shared
+secret. This is much more secure than simply sending the secret
+over the wire.
+
+Cyrus SASL supports several shared-secret mechanisms. To do this,
+it needs access to the plaintext password (unlike mechanisms which
+pass plaintext passwords over the wire, where the server can store
+a hashed version of the password).
+
+The server's copy of the shared-secret may be stored in Cyrus SASL's
+own {{sasldb}} database, in an external system accessed via
+{{saslauthd}}, or in LDAP database itself. In either case it is
+very important to apply file access controls and LDAP access controls
+to prevent exposure of the passwords. The configuration and commands
+discussed in this section assume the use of Cyrus SASL 2.1.
To use secrets stored in {{sasldb}}, simply add users with the
{{saslpasswd2}} command:
command.
To use secrets stored in the LDAP directory, place plaintext passwords
-in the {{EX:userPassword}} attribute. It will be necessary to add an
-option to {{EX:slapd.conf}} to make sure that passwords changed through
-LDAP are stored in plaintext:
+in the {{EX:userPassword}} attribute. It will be necessary to add
+an option to {{EX:slapd.conf}} to make sure that passwords set using
+the LDAP Password Modify Operation are stored in plaintext:
> password-hash {CLEARTEXT}
-Passwords stored in this way can be managed either with {{EX:ldappasswd}}
-or by simply modifying the {{EX:userPassword}} attribute.
+Passwords stored in this way can be managed either with {{ldappasswd}}(1)
+or by simply modifying the {{EX:userPassword}} attribute. Regardless of
+where the passwords are stored, a mapping will be needed from
+authentication request DN to user's DN.
-Wherever the passwords are stored, a mapping will be needed from SASL
-authentication IDs to regular DNs. The DIGEST-MD5 mechanism produces
-authentication IDs of the form:
+The DIGEST-MD5 mechanism produces authentication IDs of the form:
> uid=<username>,cn=<realm>,cn=digest-md5,cn=auth
-NOTE that if the default realm is used, the realm name is omitted from
-the ID, giving:
+If the default realm is used, the realm name is omitted from the ID,
+giving:
> uid=<username>,cn=digest-md5,cn=auth
-See {{SECT: Mapping Authentication identities to LDAP entries}} below
-for information on mapping such IDs to DNs.
+See {{SECT: Mapping Authentication Identities}} below for information
+on optional mapping of identities.
With suitable mappings in place, users can specify SASL IDs when
performing LDAP operations, and the password stored in {{sasldb}} or in
can issue commands of the form:
-> ldapsearch -U u000997 -b dc=example,dc=com 'cn=andrew*'
+> ldapsearch -Y DIGEST-MD5 -U u000997 ...
-or can specify the realm explicitly:
+Note: in each of the above cases, no authorization identity (e.g.
+{{EX:-X}}) was provided. Unless you are attempting {{SECT:SASL
+Proxy Authorization}}, no authorization identity should be specified.
+The server will infer an authorization identity from authentication
+identity (as described below).
-> ldapsearch -U u000997@myrealm -b dc=example,dc=com 'cn=andrew*'
-If several SASL mechanisms are supported at your site, it may be
-necessary to specify which one to use, e.g.:
+H3: EXTERNAL
-> ldapsearch -Y DIGEST-MD5 -U u000997 -b dc=example,dc=com 'cn=andrew*'
+The SASL EXTERNAL mechanism makes use of an authentication performed
+by a lower-level protocol: usually {{TERM:TLS}} or Unix {{TERM:IPC}}
+Each transport protocol returns Authentication Identities in its own
+format:
-Note: in each of the above cases, no authorization identity (e.g.
-{{EX:-X}}) was provided. Unless you are attempting
-{{SECT:SASL Proxy Authorization}}, no authorization identity should
-be specified. The server will infer an authorization identity from
-authentication identity (as described below).
+H4: TLS Authentication Identity Format
+
+This is the Subject DN from the client-side certificate.
+Note that DNs are displayed differently by LDAP and by X.509, so
+a certificate issued to
+> C=gb, O=The Example Organisation, CN=A Person
+
+will produce an authentication identity of:
+
+> cn=A Person,o=The Example Organisation,c=gb
+
+Note that you must set a suitable value for TLSVerifyClient to make the server
+request the use of a client-side certificate. Without this, the SASL EXTERNAL
+mechanism will not be offered.
+Refer to the {{SECT:Using TLS}} chapter for details.
+
+H4: IPC (ldapi:///) Identity Format
+
+This is formed from the Unix UID and GID of the client process:
+
+> gidNumber=<number>+uidNumber=<number>,cn=peercred,cn=external,cn=auth
+
+Thus, a client process running as {{EX:root}} will be:
+> gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
-H3: Mapping Authentication identities to LDAP entries
+
+H3: Mapping Authentication Identities
The authentication mechanism in the slapd server will use SASL
library calls to obtain the authenticated user's "username", based
on whatever underlying authentication mechanism was used. This
username is in the namespace of the authentication mechanism, and
-not in the LDAP namespace. As stated in the sections above, that
-username is reformatted into an authentication request DN of the
-form
+not in the normal LDAP namespace. As stated in the sections above,
+that username is reformatted into an authentication request DN of
+the form
> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
> uid=<username>,cn=<mechanism>,cn=auth
depending on whether or not <mechanism> employs the concept of
-"realms". Note also that the realm part will be omitted if the default
-realm was used in the authentication.
+"realms". Note also that the realm part will be omitted if the
+default realm was used in the authentication.
+
+The {{ldapwhoami}}(1) command may be used to determine the identity
+associated with the user. It is very useful for determining proper
+function of mappings.
It is not intended that you should add LDAP entries of the above
-form to your LDAP database. Chances are you have an LDAP entry for
-each of the people that will be authenticating to LDAP, laid out
+form to your LDAP database. Chances are you have an LDAP entry for
+each of the persons that will be authenticating to LDAP, laid out
in your directory tree, and the tree does not start at cn=auth.
But if your site has a clear mapping between the "username" and an
LDAP entry for the person, you will be able to configure your LDAP
The LDAP administrator will need to tell the slapd server how to
map an authentication request DN to a user's authentication DN.
-This is done by adding one or more {{EX:sasl-regexp}} directives to
+This is done by adding one or more {{EX:authz-regexp}} directives to
the {{slapd.conf}}(5) file. This directive takes two arguments:
-> sasl-regexp <search pattern> <replacement pattern>
+> authz-regexp <search pattern> <replacement pattern>
The authentication request DN is compared to the search pattern
using the regular expression functions {{regcomp}}() and {{regexec}}(),
and if it matches, it is rewritten as the replacement pattern. If
-there are multiple {{EX:sasl-regexp}} directives, only the first
+there are multiple {{EX:authz-regexp}} directives, only the first
whose search pattern matches the authentication identity is used.
The string that is output from the replacement pattern should be
-the authentication DN of the user, in a legitimate LDAP DN format.
-It can also be an LDAP URL, which is discussed below.
+the authentication DN of the user or an LDAP URL. If replacement
+string produces a DN, the entry named by this DN need not be held
+by this server. If the replace string produces an LDAP URL, that
+LDAP URL must evaluate to one and only one entry held by this server.
The search pattern can contain any of the regular expression
characters listed in {{regexec}}(3C). The main characters of note
are dot ".", asterisk "*", and the open and close parenthesis "("
and ")". Essentially, the dot matches any character, the asterisk
-allows zero or more repeats of the immediately preceding character or
-pattern, and terms in parenthesis are
-remembered for the replacement pattern.
+allows zero or more repeats of the immediately preceding character
+or pattern, and terms in parenthesis are remembered for the replacement
+pattern.
-The replacement pattern will produce the final authentication DN
-of the user. Anything from the authentication request DN that
+The replacement pattern will produce either a DN or URL referring
+to the user. Anything from the authentication request DN that
matched a string in parenthesis in the search pattern is stored in
the variable "$1". That variable "$1" can appear in the replacement
pattern, and will be replaced by the string from the authentication
request DN. If there were multiple sets of parentheses in the search
pattern, the variables $2, $3, etc are used.
-For example, suppose the user's authentication identity is written
-as the DN string
+H3: Direct Mapping
+
+Where possible, direct mapping of the authentication request DN to
+the user's DN is generally recommended. Aside from avoiding the
+expense of searching for the user's DN, it allows mapping to
+DNs which refer to entries not held by this server.
-> uid=adamson,cn=example.com,cn=kerberos_v4,cn=auth
+Suppose the authentication request DN is written as:
-and the user's actual LDAP entry is
+> uid=adamson,cn=example.com,cn=gssapi,cn=auth
-> uid=adamson,ou=person,dc=example,dc=com
+and the user's actual LDAP entry is:
-The {{EX:sasl-regexp}} directive in {{slapd.conf}}(5) could be
-written
+> uid=adamson,ou=people,dc=example,dc=com
-> sasl-regexp
-> uid=(.*),cn=example.com,cn=kerberos_v4,cn=auth
-> uid=$1,ou=person,dc=example,dc=com
+then the following {{EX:authz-regexp}} directive in {{slapd.conf}}(5)
+would provide for direct mapping.
+
+> authz-regexp
+> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
+> uid=$1,ou=people,dc=example,dc=com
An even more lenient rule could be written as
-> sasl-regexp
-> uid=(.*),cn=.*,cn=auth
-> uid=$1,ou=person,dc=example,dc=com
+> authz-regexp
+> uid=([^,]*),cn=[^,]*,cn=auth
+> uid=$1,ou=people,dc=example,dc=com
Be careful about setting the search pattern too leniently, however,
-since it may mistakenly allow people to become authenticated as a
-DN to which they should not have access. It is better to write
+since it may mistakenly allow persons to become authenticated as a
+DN to which they should not have access. It is better to write
several strict directives than one lenient directive which has
-security holes. If there is only one authentication mechanism in
+security holes. If there is only one authentication mechanism in
place at your site, and zero or one realms in use, you might be
-able to map between authentication identities and LDAP DN's with
-a single {{EX:sasl-regexp}} directive.
-
-Don't forget to allow for the case where the realm is omitted as well
-as the case with an explicitly specified realm. This may well
-require a separate {{EX:sasl-regexp}} directive for each case, with the
-explicit-realm entry being listed first.
-
-Some sites may have people's DN's spread to multiple areas of the
-LDAP tree, such as if there were an {{EX:ou=accounting}} tree and an
-{{EX:ou=engineering}} tree, with people interspersed between them. Or
-there may not be enough information in the authentication identity
-to isolate the DN, such as if the above person's LDAP entry looked
-like
-
-> dn: cn=mark adamson,ou=person,dc=example,dc=com
-> objectclass: Person
-> cn: mark adamson
+able to map between authentication identities and LDAP DN's with a
+single {{EX:authz-regexp}} directive.
+
+Don't forget to allow for the case where the realm is omitted as
+well as the case with an explicitly specified realm. This may well
+require a separate {{EX:authz-regexp}} directive for each case, with
+the explicit-realm entry being listed first.
+
+H3: Search-based mappings
+
+There are a number of cases where mapping to a LDAP URL may be
+appropriate. For instance, some sites may have person objects
+located in multiple areas of the LDAP tree, such as if there were
+an {{EX:ou=accounting}} tree and an {{EX:ou=engineering}} tree,
+with persons interspersed between them. Or, maybe the desired
+mapping must be based upon information in the user's information.
+Consider the need to map the above authentication request DN to
+user whose entry is as follows:
+
+> dn: cn=Mark Adamson,ou=People,dc=Example,dc=COM
+> objectclass: person
+> cn: Mark Adamson
> uid: adamson
-In this case, the information in the authentication identity can
-only be used to search for the user's DN, not derive it directly.
-For both of these situations, and others, the replacement pattern
-in the {{EX:sasl-regexp}} directives will need to produce an LDAP
-URL, described in the next section.
-
-
-H3: Performing searches for a person's DN
-
-When there is not enough information in the authentication identity
-to derive a person's authentication DN directly, the {{EX:sasl-regexp}}
-directives in the {{slapd.conf}}(5) file will need to produce an
-LDAP URL. This URL will then be used to perform an internal search
-of the LDAP database to find the person's authentication DN.
+The information in the authentication request DN is insufficient
+to allow the user's DN to be directly derived, instead the user's
+DN must be searched for. For these situations, a replacement pattern
+which produces a LDAP URL can be used in the {{EX:authz-regexp}}
+directives. This URL will then be used to perform an internal
+search of the LDAP database to find the person's authentication DN.
An LDAP URL, similar to other URL's, is of the form
Suppose that the person in the example from above did in fact have
an authentication username of "adamson" and that information was
-kept in the attribute "uid" in their LDAP entry. The {{EX:sasl-regexp}}
+kept in the attribute "uid" in their LDAP entry. The {{EX:authz-regexp}}
directive might be written as
-> sasl-regexp
-> uid=(.*),cn=example.com,cn=kerberos_v4,cn=auth
-> ldap:///ou=person,dc=example,dc=com??sub?(uid=$1)
+> authz-regexp
+> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
+> ldap:///ou=people,dc=example,dc=com??one?(uid=$1)
This will initiate an internal search of the LDAP database inside
the slapd server. If the search returns exactly one entry, it is
accepted as being the DN of the user. If there are more than one
entries returned, or if there are zero entries returned, the
-authentication fails and the user's connection is left bound as
-the authentication request DN.
-
-Note that if the search scope <scope> in the URL is "base", then
-the only LDAP entry that will be returned is the searchbase DN
-<base>, so the actual search of the database is skipped. This is
-equivalent to setting the replacement pattern in the directive to
-a DN directly, as in the section above.
+authentication fails and the user's connection is left bound as the
+authentication request DN.
The attributes that are used in the search filter <filter> in the
URL should be indexed to allow faster searching. If they are not,
the authentication step alone can take uncomfortably long periods,
and users may assume the server is down.
-A more complex site might have several realms in use, each mapping to
-a different sub-tree in the directory. These can be handled with
+A more complex site might have several realms in use, each mapping
+to a different subtree in the directory. These can be handled with
statements of the form:
> # Match Engineering realm
-> sasl-regexp
-> uid=(.*),cn=engineering.example.com,cn=digest-md5,cn=auth
-> ldap:///dc=eng,dc=example,dc=com??sub?(&(uid=$1)(objectClass=person))
+> authz-regexp
+> uid=([^,]*),cn=engineering.example.com,cn=digest-md5,cn=auth
+> ldap:///dc=eng,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
>
> # Match Accounting realm
-> sasl-regexp
-> uid=(.*),cn=accounting.example.com,cn=digest-md5,cn=auth
-> ldap:///dc=accounting,dc=example,dc=com??sub?(&(uid=$1)(objectClass=person))
+> authz-regexp
+> uid=([^,].*),cn=accounting.example.com,cn=digest-md5,cn=auth
+> ldap:///dc=accounting,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
>
> # Default realm is customers.example.com
-> sasl-regexp
-> uid=(.*),cn=digest-md5,cn=auth
-> ldap:///dc=customers,dc=example,dc=com??sub?(&(uid=$1)(objectClass=person))
+> authz-regexp
+> uid=([^,]*),cn=digest-md5,cn=auth
+> ldap:///dc=customers,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
Note that the explicitly-named realms are handled first, to avoid
-the realm name becoming part of the UID. Note also the limitation
-of matches to those entries with {{EX:(objectClass=person)}} to
-avoid matching other entries that happen to refer to the UID.
+the realm name becoming part of the UID. Also note the use of scope
+and filters to limit matching to desirable entries.
+
+Note as well that {{EX:authz-regexp}} internal search are subject
+to access controls. Specifically, the authentication identity
+must have {{EX:auth}} access.
See {{slapd.conf}}(5) for more detailed information.
become that DN, users must first authenticate as one of the persons
on the list. This allows for better auditing of who made changes
to the LDAP database. If people were allowed to authenticate
-directly to the priviliged account, possibly through the {{EX:rootpw}}
+directly to the privileged account, possibly through the {{EX:rootpw}}
{{slapd.conf}}(5) directive or through a {{EX:userPassword}}
attribute, then auditing becomes more difficult.
In the first form, the <username> is from the same namespace as
the authentication identities above. It is the user's username as
-it is refered to by the underlying authentication mechanism.
+it is referred to by the underlying authentication mechanism.
Authorization identities of this form are converted into a DN format
by the same function that the authentication process used, producing
an {{authorization request DN}} of the form
> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
That authorization request DN is then run through the same
-{{EX:sasl-regexp}} process to convert it into a legitimate authorization
+{{EX:authz-regexp}} process to convert it into a legitimate authorization
DN from the database. If it cannot be converted due to a failed
search from an LDAP URL, the authorization request fails with
"inappropriate access". Otherwise, the DN string is now a legitimate
begins. There are two attributes that the LDAP administrator can
put into LDAP entries to allow authorization:
-> saslAuthzTo
-> saslAuthzFrom
+> authzTo
+> authzFrom
-Both can be multivalued. The {{EX:saslAuthzTo}} attribute is a
+Both can be multivalued. The {{EX:authzTo}} attribute is a
source rule, and it is placed into the entry associated with the
authentication DN to tell what authorization DNs the authenticated
DN is allowed to assume. The second attribute is a destination
The choice of which authorization policy attribute to use is up to
the administrator. Source rules are checked first in the person's
-authentication DN entry, and if none of the {{EX:saslAuthzTo}} rules
-specify the authorization is permitted, the {{EX:saslAuthzFrom}}
+authentication DN entry, and if none of the {{EX:authzTo}} rules
+specify the authorization is permitted, the {{EX:authzFrom}}
rules in the authorization DN entry are then checked. If neither
case specifies that the request be honored, the request is denied.
-Since the default behaviour is to deny authorization requests, rules
+Since the default behavior is to deny authorization requests, rules
only specify that a request be allowed; there are no negative rules
telling what authorizations to deny.
The value(s) in the two attributes are of the same form as the
-output of the replacement pattern of a {{EX:sasl-regexp}} directive:
-either a DN or an LDAP URL. For example, if a {{EX:saslAuthzTo}}
+output of the replacement pattern of a {{EX:authz-regexp}} directive:
+either a DN or an LDAP URL. For example, if a {{EX:authzTo}}
value is a DN, that DN is one the authenticated user can authorize
-to. On the other hand, if the {{EX:saslAuthzTo}} value is an LDAP
+to. On the other hand, if the {{EX:authzTo}} value is an LDAP
URL, the URL is used as an internal search of the LDAP database,
and the authenticated user can become ANY DN returned by the search.
If an LDAP entry looked like:
> dn: cn=WebUpdate,dc=example,dc=com
-> saslAuthzTo: ldap:///dc=example,dc=com??sub?(objectclass=Person)
+> authzTo: ldap:///dc=example,dc=com??sub?(objectclass=person)
-then any user who authenticated as cn=WebUpdate,dc=example,dc=com
+then any user who authenticated as {{EX:cn=WebUpdate,dc=example,dc=com}}
could authorize to any other LDAP entry under the search base
-"dc=example,dc=com" which has an objectClass of "Person".
+{{EX:dc=example,dc=com}} which has an objectClass of {{EX:Person}}.
H4: Notes on Proxy Authorization Rules
-An LDAP URL in a {{EX:saslAuthzTo}} or {{EX:saslAuthzFrom}} attribute
-will return a set of DNs. Each DN returned will be checked.
-Searches which return a large set can cause the authorization
-process to take an uncomfortably long time. Also, searches should
-be performed on attributes that have been indexed by slapd.
+An LDAP URL in a {{EX:authzTo}} or {{EX:authzFrom}} attribute
+will return a set of DNs. Each DN returned will be checked. Searches
+which return a large set can cause the authorization process to
+take an uncomfortably long time. Also, searches should be performed
+on attributes that have been indexed by slapd.
-To help produce more sweeping rules for {{EX:saslAuthzFrom}} and
-{{EX:saslAuthzTo}}, the values of these attributes are allowed to
+To help produce more sweeping rules for {{EX:authzFrom}} and
+{{EX:authzTo}}, the values of these attributes are allowed to
be DNs with regular expression characters in them. This means a
source rule like
-> saslAuthzTo: uid=.*,dc=example,dc=com
+> authzTo: dn.regex:^uid=[^,]*,dc=example,dc=com$
would allow that authenticated user to authorize to any DN that
matches the regular expression pattern given. This regular expression
Also note that the values in an authorization rule must be one of
the two forms: an LDAP URL or a DN (with or without regular expression
characters). Anything that does not begin with "{{EX:ldap://}}" is
-taken as a DN. It is not permissable to enter another authorization
+taken as a DN. It is not permissible to enter another authorization
identity of the form "{{EX:u:<username>}}" as an authorization rule.
H4: Policy Configuration
-The decision of which type of rules to use, {{EX:saslAuthzFrom}}
-or {{EX:saslAuthzTo}}, will depend on the site's situation. For
+The decision of which type of rules to use, {{EX:authzFrom}}
+or {{EX:authzTo}}, will depend on the site's situation. For
example, if the set of people who may become a given identity can
easily be written as a search filter, then a single destination
rule could be written. If the set of people is not easily defined
should be allowed to perform the proxy authorization.
By default, processing of proxy authorization rules is disabled.
-The {{EX:sasl-authz-policy}} directive must be set in the
+The {{EX:authz-policy}} directive must be set in the
{{slapd.conf}}(5) file to enable authorization. This directive can
-be set to {{EX:none}} for no rules (the default), {{EX:from}} for
-source rules, {{EX:to}} for destination rules, or {{EX:both}} for
+be set to {{EX:none}} for no rules (the default), {{EX:to}} for
+source rules, {{EX:from}} for destination rules, or {{EX:both}} for
both source and destination rules.
-Destination rules are extremely powerful. If ordinary users have
-access to write the {{EX:saslAuthzTo}} attribute in their own entries, then
-they can write rules that would allow them to authorize as anyone else.
-As such, when using destination rules, the {{EX:saslAuthzTo}} attribute
-should be protected with an ACL that only allows privileged users
-to set its values.
+Source rules are extremely powerful. If ordinary users have
+access to write the {{EX:authzTo}} attribute in their own
+entries, then they can write rules that would allow them to authorize
+as anyone else. As such, when using source rules, the
+{{EX:authzTo}} attribute should be protected with an ACL that
+only allows privileged users to set its values.
+
projects / openldap / blobdiff