# Copyright 1999-2000, 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:RFC2222}}. 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 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.
+
+This chapter assumes you have read {{Cyrus SASL for System
+Administrators}}, provided with the {{PRD:Cyrus}} {{PRD:SASL}}
+package (in {{FILE:doc/sysadmin.html}}).
+
+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 "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.
+
+The EXTERNAL mechanism utilizes authentication services provided
+by lower level network services such as {{TERM:TLS}} (TLS). When
+used in conjunction with TLS {{TERM:X.509}}-based public key technology,
+EXTERNAL offers strong authentication. Use of EXTERNAL is discussed
+in the {{SECT:Using TLS}} chapter.
+
+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.
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 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}}.
+
+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.
+
+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, SASL will 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.
+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>
+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
+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 sample_server and 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
+
+
+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".
+
+To use secrets stored in {{sasldb,}} simply add users with the
+{{saslpasswd2}} command:
+
+> saslpasswd2 -c <username>
+
+The passwords for such users must be managed with the {{saslpasswd2}}
+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:
+
+> password-hash {CLEARTEXT}
+
+Passwords stored in this way can be managed either with {{EX:ldappasswd}}
+or by simply modifying the {{EX:userPassword}} attribute.
+
+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:
+
+> 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:
+
+> uid=<username>,cn=digest-md5,cn=auth
+
+See {{SECT: Mapping Authentication identities to LDAP entries}} below
+for information on mapping such IDs to DNs.
+
+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:
+
+> dn: cn=Andrew Findlay+uid=u000997,dc=example,dc=com
+> objectclass: inetOrgPerson
+> objectclass: person
+> sn: Findlay
+> uid: u000997
+> userPassword: secret
+
+can issue commands of the form:
+
+> ldapsearch -U u000997 -b dc=example,dc=com 'cn=andrew*'
+
+or can specify the realm explicitly:
+
+> 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.:
+
+> ldapsearch -Y DIGEST-MD5 -U u000997 -b dc=example,dc=com 'cn=andrew*'
+
+
+
H3: Mapping Authentication identities to LDAP entries
- 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
+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
-> uid=<username>,cn=<realm>,cn=<mechanism>,cn=authzid
+> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
or
-> uid=<username>,cn=<mechanism>,cn=authzid
+> uid=<username>,cn=<mechanism>,cn=auth
-depending on whether or not <mechanism> employs the concept of "realms".
+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.
- It is not intended that you should add LDAP entries of the above
+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.}}
-
- 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:
-
-> saslRegexp <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: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 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.
-
- 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.
-
- For example, suppose the user's authentication identity is written
+each of the people 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 user's authentication username to
+their {{authentication DN}}.
+
+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
+the {{slapd.conf}}(5) file. This directive takes two arguments:
+
+> sasl-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
+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 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 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 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
-> uid=ADAMSON,cn=EXAMPLE.COM,cn=KERBEROS_V4,cn=AUTHZID
+> uid=adamson,cn=example.com,cn=kerberos_v4,cn=auth
-and the user's actual LDAP entry is
+and the user's actual LDAP entry is
-> uid=ADAMSON,ou=PERSON,dc=EXAMPLE,dc=COM
+> uid=adamson,ou=person,dc=example,dc=com
-The {{EX:saslRegexp}} directive in {{slapd.conf}}(5) could be written
+The {{EX:sasl-regexp}} directive in {{slapd.conf}}(5) could be
+written
-> saslRegexp
-> uid=(.*),cn=example.com,cn=kerberos_v4,cn=authzid
+> sasl-regexp
+> uid=(.*),cn=example.com,cn=kerberos_v4,cn=auth
> uid=$1,ou=person,dc=example,dc=com
An even more lenient rule could be written as
-> saslRegexp
-> uid=(.*),.*cn=authzid
+> sasl-regexp
+> uid=(.*),cn=.*,cn=auth
> 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
+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: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 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
+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.
+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:saslRegexp}}
+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 URI. This URI will then be used to perform an internal search of
-the LDAP database to find the person's authentication DN.
+LDAP URL. This URL 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
+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 on the local machine, 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:sasl-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.
+> sasl-regexp
+> uid=(.*),cn=example.com,cn=kerberos_v4,cn=auth
+> ldap:///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 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.
+
+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
+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))
+>
+> # 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))
+>
+> # 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))
+
+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 objectClass=person to avoid matching
+other entries that happen to refer to the UID.
+
+See {{slapd.conf}}(5) for more detailed information.
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.
-
+The SASL 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. By default, the authorization
+features are disabled, and must be explicitly configured by the
+LDAP administrator before use.
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,
+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.
-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.
+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. 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.
H3: Authorization Identities
- The authorization identity is sent to the slapd server via the -X
+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
> 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 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
-> 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:sasl-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:
+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:
+Both can be multivalued. The {{EX:saslAuthzTo}} 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:saslAuthzTo}} rules
+specify the authorization is permitted, the {{EX:saslAuthzFrom}}
+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
+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}}
+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
+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
+> saslAuthzTo: ldap:///dc=example,dc=com??sub?(objectclass=Person)
then any user who authenticated as cn=WebUpdate,dc=example,dc=com
could authorize to any other LDAP entry under the search base
H4: Notes on 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: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.
- 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:saslAuthzFrom}} and
+{{EX:saslAuthzTo}}, 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
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
+"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 "ldap://" is taken
+as a DN. It is not permissable to enter another authorization
+identity of the form "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 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.
+
+By default, processing of authorization rules is disabled. The
+{{EX:sasl-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 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.
projects / openldap / blobdiff