-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
-H1: SASL
-
- OpenLDAP clients and servers are capable of providing authentication
-via the Simple Authentication Security Layer (SASL) system, which is
-explained in RFC 2222. There are several industry standard
-authentication mechanisms that can be used with SASL, including
-Kerberos V4, GSSAPI, and some of the Digest mechanisms. 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 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 authorization feature, allowing them to authenticate themselves
-and then switch their identity to that of another user or service.
-
- Note that in the following text the term "{{user}}" is used to
-describe a person who is connecting to the LDAP server via a client
-program, such as {{ldapsearch}}(1). The term can also be used to
-describe a computer program that runs itself and accesses the LDAP
-database, such as a sendmail program or a nightly update program run
-out of cron. Thus {{"user"}} refers to any computer process connecting
-to the LDAP server, whether or not it has a human monitoring it.
+H1: Using SASL
+
+OpenLDAP clients and servers are capable of authenticating via the
+{{TERM[expand]SASL}} ({{TERM:SASL}}) framework, which is detailed
+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: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
+authorization feature, allowing them to authenticate themselves and
+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 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 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
+via an LDAP client, such as {{ldapsearch}}(1). That is, the term
+{{user}} not only applies to both an individual using an LDAP client,
+but to an application entity which issues LDAP client operations
+without direct user control. For example, an e-mail server which
+uses LDAP operations to access information held in an LDAP server
+is an application entity.
+
+
+H2: SASL Security Considerations
+
+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 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 {{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[expand]TLS}} ({{TERM:TLS}}). When
+used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public
+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 {{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 simple
-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 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 next section after
-that describes the second step of mapping authentication identities to
-DN's.
-
-
-H3: MIT Kerberos V4
-
- It will be assumed that you are familiar with the workings of MIT's
-Kerberos security system, and that your site has this mechanism in
-place. Your users should be familiar with authentication policy, are
-aware of how to receive credentials in a Kerberos ticket cache, and
-how to refresh expired credentials.
-
- 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 is
-connecting to a legitimate server. If encryption layers are to be
-used, the session key can also be used to help negotiate that option.
-
- The slapd server runs the service called "{{ldap}}", and the server
-will require a srvtab file with a service key. SASL aware client
+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 {{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}}.
+
+
+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
+
+This section describes the use of the SASL KERBEROS_V4 mechanism
+with OpenLDAP. It will be assumed that you are familiar with the
+workings of the Kerberos IV security system, and that your site has
+Kerberos IV deployed. Your users should be familiar with
+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
+is connecting to a legitimate server. If encryption layers are to
+be used, the session key can also be used to help negotiate that
+option.
+
+The slapd server runs the service called "{{ldap}}", and the server
+will require a srvtab file with a service key. SASL aware client
programs will be obtaining an "ldap" service ticket with the user's
-ticket granting ticket (TGT), with the instance of the ticket matching
-the hostname of the OpenLDAP server. For example, if your realm is
-named EXAMPLE.COM and the slapd server is running on the host named
-directory.example.com, the /etc/srvtab file on the server will have a
-service key
+ticket granting ticket (TGT), with the instance of the ticket
+matching the hostname of the OpenLDAP server. For example, if your
+realm is named {{EX:EXAMPLE.COM}} and the slapd server is running
+on the host named {{EX:directory.example.com}}, the {{FILE:/etc/srvtab}}
+file on the server will have a service key
> ldap.directory@EXAMPLE.COM
-When a SASL client is authenticating a user to LDAP, it will request a
-session key for that 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
+When an LDAP client is authenticating a user to the directory using
+the KERBEROS_IV mechanism, it will request a session key for that
+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, the client may print out the message:
> ldap_sasl_interactive_bind_s: Local error
When the service ticket is obtained, it will be passed to the LDAP
-server as proof of the user's identity. The server will take the
-user's username and realm out of the service ticket using SASL library
-calls, and convert them into an {{authentication request DN}} of the form
+server as proof of the user's identity. The server will extract
+the identity and realm out of the service ticket using SASL
+library calls, and convert them into an {{authentication request
+DN}} of the form
-> uid=<username>,cn=<realm>,cn=<mechanism>,cn=authzid
+> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
So in our above example, if the user's name were "adamson", the
authentication request DN would be:
-> uid=ADAMSON,cn=EXAMPLE.COM,cn=KERBEROS_V4,cn=AUTHZID
+> 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 next section, however, tells how to map that DN
-into the DN of a person's own LDAP entry.
+This authentication request DN can be used directly ACLs or,
+alternatively, mapped prior to use. See the section {{SECT:Mapping
+Authentication Identities}} for details.
- 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 emply the
-concept of a realm, so the ",cn=<realm>" portion of the authentication
-request DN would not appear.
+H3: DIGEST-MD5
-H3: Mapping Authentication identities to LDAP entries
+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.
- 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 section above, that username is
-reformatted into an authentication request DN of the form
+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).
-> uid=<username>,cn=<realm>,cn=<mechanism>,cn=authzid
+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.
-or
+To use secrets stored in {{sasldb}}, simply add users with the
+{{saslpasswd2}} command:
-> uid=<username>,cn=<mechanism>,cn=authzid
+> saslpasswd2 -c <username>
-depending on whether or not <mechanism> employs the concept of "realms".
+The passwords for such users must be managed with the {{saslpasswd2}}
+command.
- 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 in
-your directory tree, and the tree does not start at cn=authzid. 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 server to
-automatically map a user's authentication username to their
-{{authentication DN.}}
+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 set using
+the LDAP Password Modify Operation are stored in plaintext:
- 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:saslRegexp}} directives to the
-{{slapd.conf}}(5) file. This directive takes two arguments:
+> password-hash {CLEARTEXT}
-> saslRegexp <search pattern> <replacement pattern>
+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.
- 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:saslRegexp}} 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 URI, which is discussed below.
+The DIGEST-MD5 mechanism produces authentication IDs of the form:
- 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 matches one
-or more characters, and terms in parenthesis are remembered for the
-replacement pattern.
+> uid=<username>,cn=<realm>,cn=digest-md5,cn=auth
- The replacement pattern will produce the final authentication DN of
-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 parenthesis in the search pattern, the
-variables $2, $3, etc are used.
+If the default realm is used, the realm name is omitted from the ID,
+giving:
- For example, suppose the user's authentication identity is written
-as the DN string
+> uid=<username>,cn=digest-md5,cn=auth
-> uid=ADAMSON,cn=EXAMPLE.COM,cn=KERBEROS_V4,cn=AUTHZID
+See {{SECT: Mapping Authentication Identities}} below for information
+on optional mapping of identities.
-and the user's actual LDAP entry is
+With suitable mappings in place, users can specify SASL IDs when
+performing LDAP operations, and the password stored in {{sasldb}} or in
+the directory itself will be used to verify the authentication.
+For example, the user identified by the directory entry:
-> uid=ADAMSON,ou=PERSON,dc=EXAMPLE,dc=COM
+> dn: cn=Andrew Findlay+uid=u000997,dc=example,dc=com
+> objectclass: inetOrgPerson
+> objectclass: person
+> sn: Findlay
+> uid: u000997
+> userPassword: secret
-The {{EX:saslRegexp}} directive in {{slapd.conf}}(5) could be written
+can issue commands of the form:
-> saslRegexp
-> uid=(.*),cn=example.com,cn=kerberos_v4,cn=authzid
-> uid=$1,ou=person,dc=example,dc=com
+> ldapsearch -Y DIGEST-MD5 -U u000997 ...
-An even more lenient rule could be written as
+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).
-> saslRegexp
-> uid=(.*),.*cn=authzid
-> uid=$1,ou=person,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 several
-strict directives than one lenient directive which has 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:saslRegexp}}
-directive.
-
- Some sites may have people's DN's spread to multiple areas of the
-LDAP tree, such as if there were an ou=accounting tree and an
-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
-> 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:saslRegexp}} directives will need to produce an LDAP URI,
-described in the next section.
+H3: EXTERNAL
+
+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:
+
+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:
-H3: Performing searches for a person's DN
+> gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
- When there is not enough information in the authentication identity
-to derive a person's authentication DN directly, the {{EX:saslRegexp}}
-directives in the {{slapd.conf}}(5) file will need to produce an
-LDAP URI. This URI will then be used to perform an internal search of
-the LDAP database to find the person's authentication DN.
- An LDAP URI, similar to other URI's, is of the form
+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 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
+
+or
+
+> 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.
+
+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 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
+server to automatically map a authentication request DN to the
+user's {{authentication DN}}.
+
+Note: it is not required that the authentication request DN nor the
+user's authentication DN resulting from the mapping refer to an
+entry held in the directory. However, additional capabilities
+become available (see below).
+
+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:authz-regexp}} directives to
+the {{slapd.conf}}(5) file. This directive takes two arguments:
+
+> 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: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 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.
+
+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.
+
+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.
+
+Suppose the authentication request DN is written as:
+
+> uid=adamson,cn=example.com,cn=gssapi,cn=auth
+
+and the user's actual LDAP entry is:
+
+> uid=adamson,ou=people,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
+
+> 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 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
+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: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
+
+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
> ldap://<host>/<base>?<attrs>?<scope>?<filter>
-This contains all of the elements necessary to perform an LDAP search:
-the name of the server <host>, the LDAP DN search base <base>, the
-LDAP attributes to retrieve <attrs>, the search scope <scope> which is
-one of the three options "base", "one", or "sub", and lastly an LDAP
-search filter <filter>. Since the search is for an LDAP DN on the
-local machine, the <host> portion is ignored. By the same token the
-<attrs> field is also ignored since only the DN is of concern. These
-two elements are left in the format of the URI to maintain the clarity
-of what information goes where in the string.
-
- 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:saslRegexp}}
+This contains all of the elements necessary to perform an LDAP
+search: the name of the server <host>, the LDAP DN search base
+<base>, the LDAP attributes to retrieve <attrs>, the search scope
+<scope> which is one of the three options "base", "one", or "sub",
+and lastly an LDAP search filter <filter>. Since the search is for
+an LDAP DN within the current server, the <host> portion should be
+empty. The <attrs> field is also ignored since only the DN is of
+concern. These two elements are left in the format of the URL to
+maintain the clarity of what information goes where in the string.
+
+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:authz-regexp}}
directive might be written as
-> saslRegexp
-> uid=(.*),cn=example.com,cn=kerberos_v4,cn=authzid
-> ldap://localhost/ou=person,dc=example,dc=com??sub?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 URI 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.
-
- The attributes that are used in the search filter <filter> in the
-URI 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.
-
-
-H2: SASL Authorization
-
- The SASL library offers a feature known as {{authorization}}, which
-allows an authenticated user to request that they act on the behalf of
-another user. This step occurs after the user has obtained an
-authentication DN, and involves sending an authorization identity to
-the server. The server will then make a decision on whether or not to
-allow the authorization to occur. If it is allowed, the user's LDAP
-connection is switched to have a binding DN derived from the
-authorization identity, and the LDAP session proceeds with the access
-of the new authorization DN.
-
- The decision to allow an authorization to proceed depends on the
-rules and policies of the site where LDAP is running, and thus cannot
-be made by SASL alone. The SASL library leaves it up to the server to
-make the decision. The LDAP administrator sets the guidelines of who
-can authorize to what identity by adding information into the LDAP
-database entries.
-
-
-H3: Uses of Authorization
-
- This sort of service is useful when one entity needs to act on the
-behalf of many other users. For example, users may be directed to a
-web page to make changes to their personal information in their LDAP
-entry. The users authenticate to the web server to establish their
-identity, but the web server CGI cannot authenticate to the LDAP
-server as that user to make changes for them. Instead, the web server
-authenticates itself to the LDAP server as a service identity, say,
+> 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.
+
+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 subtree in the directory. These can be handled with
+statements of the form:
+
+> # Match Engineering realm
+> 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
+> 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
+> 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. 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.
+
+
+H2: SASL Proxy Authorization
+
+The SASL offers a feature known as {{proxy authorization}}, which
+allows an authenticated user to request that they act on the behalf
+of another user. This step occurs after the user has obtained an
+authentication DN, and involves sending an authorization identity
+to the server. The server will then make a decision on whether or
+not to allow the authorization to occur. If it is allowed, the
+user's LDAP connection is switched to have a binding DN derived
+from the authorization identity, and the LDAP session proceeds with
+the access of the new authorization DN.
+
+The decision to allow an authorization to proceed depends on the
+rules and policies of the site where LDAP is running, and thus
+cannot be made by SASL alone. The SASL library leaves it up to the
+server to make the decision. The LDAP administrator sets the
+guidelines of who can authorize to what identity by adding information
+into the LDAP database entries. By default, the authorization
+features are disabled, and must be explicitly configured by the
+LDAP administrator before use.
+
+
+H3: Uses of Proxy Authorization
+
+This sort of service is useful when one entity needs to act on the
+behalf of many other users. For example, users may be directed to
+a web page to make changes to their personal information in their
+LDAP entry. The users authenticate to the web server to establish
+their identity, but the web server CGI cannot authenticate to the
+LDAP server as that user to make changes for them. Instead, the
+web server authenticates itself to the LDAP server as a service
+identity, say,
> cn=WebUpdate,dc=example,dc=com
and then it will SASL authorize to the DN of the user. Once so
-authorized, the CGI makes changes to the LDAP entry of the user, and
-as far as the slapd server can tell for its ACLs, it is the user
-themself on the other end of the connection. The user could have
-connected to the LDAP server directly and authenticated as themself,
-but that would require the user to have more knowledge of LDAP clients,
-knowledge which the web page provides in an easier format.
-
- Authorization can also be used to limit access to an account that
-has greater access to the database. Such an account, perhaps even the
-root DN specified in {{slapd.conf}}(5), can have a strict list of
-people who can authorize to that DN. Changes to the LDAP database
-could then be only allowed by that DN, and in order to 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}} {{slapd.conf}}(5)
-directive or through a {{EX:userPassword}} attribute, then auditing
-becomes more difficult.
-
- Note that after a successful authorization, the original
-authentication DN in the LDAP connection is overwritten by the new DN
-from the authorization request. If a service program is able to
-authenticate itself as its own authentication DN and then authorize to
-other DN's, and it is planning on switching to several different
-identities during one LDAP session, it will need to authenticate itself
-each time before authorizing to another DN. The slapd server does not
-keep record of the service program's ability to switch to other DN's.
+authorized, the CGI makes changes to the LDAP entry of the user,
+and as far as the slapd server can tell for its ACLs, it is the
+user themself on the other end of the connection. The user could
+have connected to the LDAP server directly and authenticated as
+themself, but that would require the user to have more knowledge
+of LDAP clients, knowledge which the web page provides in an easier
+format.
+
+Proxy authorization can also be used to limit access to an account
+that has greater access to the database. Such an account, perhaps
+even the root DN specified in {{slapd.conf}}(5), can have a strict
+list of people who can authorize to that DN. Changes to the LDAP
+database could then be only allowed by that DN, and in order to
+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 privileged account, possibly through the {{EX:rootpw}}
+{{slapd.conf}}(5) directive or through a {{EX:userPassword}}
+attribute, then auditing becomes more difficult.
+
+Note that after a successful proxy authorization, the original
+authentication DN of the LDAP connection is overwritten by the new
+DN from the authorization request. If a service program is able to
+authenticate itself as its own authentication DN and then authorize
+to other DN's, and it is planning on switching to several different
+identities during one LDAP session, it will need to authenticate
+itself each time before authorizing to another DN (or use a different
+proxy authorization mechanism). The slapd server does not keep
+record of the service program's ability to switch to other DN's.
On authentication mechanisms like Kerberos this will not require
multiple connections being made to the Kerberos server, since the
-user's TGT and "ldap" session key are valid for multiple uses for the
-several hours of the ticket lifetime.
+user's TGT and "ldap" session key are valid for multiple uses for
+the several hours of the ticket lifetime.
-H3: Authorization Identities
+H3: SASL Authorization Identities
- The authorization identity is sent to the slapd server via the -X
-switch for {{ldapsearch}}(1) and other tools, or in the *authzid
-parameter to the {{lutil_sasl_defaults}}() call. The identity can
-be in one of two forms, either
+The SASL authorization identity is sent to the LDAP server via the
+{{EX:-X}} switch for {{ldapsearch}}(1) and other tools, or in the
+{{EX:*authzid}} parameter to the {{lutil_sasl_defaults}}() call.
+The identity can be in one of two forms, either
> u:<username>
> dn:<dn>
-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. 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
+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 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=authzid
+> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
-That authorization request DN is then run through the same {{EX:saslRegexp}}
-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 URI, the authorization request fails with "inappropriate access".
-Otherwise, the DN string is now a legitimate authorization DN ready to
-undergo approval.
+That authorization request DN is then run through the same
+{{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
+authorization DN ready to undergo approval.
- If the authorization identity was provided in the second form, with
-a "dn:" prefix, the string after the prefix is already in
+If the authorization identity was provided in the second form, with
+a {{EX:"dn:"}} prefix, the string after the prefix is already in
authorization DN form, ready to undergo approval.
-H3: Authorization rules
-
- Once slapd has the authorization DN, the actual approval process
-begins. There are two attributes that the LDAP administrator can put
-into LDAP entries to allow authorization:
-
-> saslAuthzTo
-> saslAuthzFrom
-
-Both can be multivalued. The first is called a source rule, and it is
-placed into a person's authentication DN entry to tell what other
-authorization DN's the person is allowed to change to. The second form
-is called a destination rule, and it is placed into an authorization
-DN's entry to tell what authenticated DN a person must be coming from
-in order to switch to that authorization DN. The choice of which form
-to use is up to the administrator. Source rules are checked first in
-the person's authentication DN entry, and if none of the saslAuthzTo
-rules specify the authorization is permitted, the saslAuthzFrom rules
-in the authorization DN entry are then checked. If neither case
-specifies that the request be honored, the request is denied with an
-"inappropriate access" message. Since the default behaviour 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:saslRegexp}} directive:
-either a DN or an LDAP URI. For example, if a saslAuthzTo value is a
-DN, that DN is one the authenticated user can authorize to. On the
-other hand, if the saslAuthzTo value is an LDAP URI, the URI 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:
+H3: Proxy Authorization Rules
+
+Once slapd has the authorization DN, the actual approval process
+begins. There are two attributes that the LDAP administrator can
+put into LDAP entries to allow authorization:
+
+> authzTo
+> authzFrom
+
+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
+rule, and it is placed into the entry associated with the requested
+authorization DN to tell which authenticated DNs may assume it.
+
+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: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 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: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: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://host/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 Authorization rules
+H4: Notes on Proxy Authorization Rules
- An LDAP URI in a saslAuthzTo or saslAuthzFrom attribute will return
-a list of DN's, and that list must be linearly scanned. Searches
-which return a long list 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 saslAuthzFrom and
-saslAuthzTo, the values of these attributes are allowed to be DN's
-with regular expression characters in them. This means a source rule
-like
+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
-comparison can be evaluated much faster than an LDAP search for "uid=*".
-
- Also note that the values in an authorization rule must be one of the
-two forms: an LDAP URI or a DN (with or without regular expression
-characters). Anything that does not begin with "ldap://" is taken as a
-DN. It is not permissable to enter another authorization identity of
-the form "u:<username>" as an authorization rule.
-
- The decision of which type of rules to use, saslAuthzFrom or
-saslAuthzTo, 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 by a search filter, and the
-set of people is small, it may be better to write a source rule in the
-entries of each of those people who should be allowed to perform the
-authorization.
+comparison can be evaluated much faster than an LDAP search for
+{{EX:(uid=*)}}.
+
+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 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: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
+by a search filter, and the set of people is small, it may be better
+to write a source rule in the entries of each of those people who
+should be allowed to perform the proxy authorization.
+
+By default, processing of proxy authorization rules is disabled.
+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:to}} for
+source rules, {{EX:from}} for destination rules, or {{EX:both}} for
+both source and destination rules.
+
+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.
+