Sync with HEAD

[openldap] / doc / guide / admin / sasl.sdf

# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.

H1: Using SASL

OpenLDAP clients and servers are capable of authenticating via the
{{TERM[expand]SASL}} ({{TERM:SASL}}) framework, which is detailed
in {{REF:RFC2222}}.   This chapter describes how to make use of
SASL in OpenLDAP.

There are several industry standard authentication mechanisms that
can be used with SASL, including {{TERM:Kerberos}} V4, {{TERM:GSSAPI}},
and DIGEST-MD.  The standard client tools provided with OpenLDAP,
such as {{ldapsearch}}(1) and {{ldapmodify}}(1), will by default
attempt to authenticate the user to the {{slapd}}(8) server using
SASL. Basic authentication service can be set up by the LDAP
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}} {{PRD:SASL}}
package (in {{FILE:doc/sysadmin.html}}) and have a working Cyrus
SASL installation.  You should use the Cyrus SASL {{EX:sample_client}}
and {{EX:sample_server}} to test your SASL installation before
attempting to make use of it in OpenLDAP.

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 {{TERM: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 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 {{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 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 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=auth

So in our above example, if the user's name were "adamson", the
authentication request DN would be:

>       uid=adamsom,cn=example.com,cn=kerberos_v4,cn=auth

This authentication request DN by itself could be placed into ACL's
and {{EX:groupOfNames}} "member" attributes, since it is of legitimate
LDAP DN format. The section
{{SECT:Mapping Authentication identities to LDAP entries}},
however, tells how to map that
DN into the DN of a person's own LDAP entry.

Also note that this example, being for Kerberos, shows the <realm>
portion of the DN being filled in with the Kerberos realm of the
company. Several other authentication mechanisms do not employ the
concept of a realm, so the ",cn=<realm>" portion of the authentication
request DN would not appear.


H3: GSSAPI

This section describes the use of the SASL GSSAPI mechanism and
Kerberos V with OpenLDAP. Since Kerberos V is being used, the
information is very similar to the previous section.  It will be
assumed that you have Kerberos V deployed, you are familiar with
the operation of the system, and that your users are trained in its
use.  This section also assumes you have familiarized yourself with
the use of the GSSAPI mechanism by reading {{Configuring GSSAPI and
Cyrus SASL}} (provided with Cyrus SASL in the {{FILE:doc/gssapi}}
file) and successfully experimented with the Cyrus provided
{{EX:sample_server}} and {{EX:sample_client}} applications.  General
information about Kerberos is available at
{{URL:http://web.mit.edu/kerberos/www/}}.

To use the GSSAPI mechanism with {{slapd}}(8) one must create a service
key with a principal for {{ldap}} service within the realm for the host
on which the service runs.  For example, if you run {{slapd}} on
{{EX:directory.example.com}} and your realm is {{EX:EXAMPLE.COM}},
you need to create a service key with the principal:

>       ldap/directory.example.com@EXAMPLE.COM

When {{slapd}}(8) runs, it must have access to this key.  This is
generally done by placing the key into a keytab, such as
{{FILE:/etc/krb5.keytab}}.

To use the GSSAPI mechanism to authenticate to the directory, the
user obtains a Ticket Granting Ticket (TGT) prior to running the
LDAP client.  When using OpenLDAP client tools, the user may mandate
use of the GSSAPI mechanism by specifying {{EX:-Y GSSAPI}} as a
command option.

For the purposes of authentication and authorization, {{slapd}}(8)
associates a non-mapped authentication request DN of the form:

>       uid=<principal>,cn=<realm>,cn=gssapi,cn=auth

Continuing our example, a user
with the Kerberos principal {{EX:kurt@EXAMPLE.COM}} would have
the associated DN:

>       uid=kurt,cn=example.com,cn=gssapi,cn=auth

and the principal {{EX:ursula@FOREIGN.REALM}} would have the
associated DN:

>       uid=ursula,cn=foreign.realm,cn=gssapi,cn=auth


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*'


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).


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 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.

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=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: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=auth

and the user's actual LDAP entry is

>       uid=adamson,ou=person,dc=example,dc=com

The {{EX:sasl-regexp}} directive in {{slapd.conf}}(5) could be
written

>       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

>       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:sasl-regexp}} directive.

Don't forget to allow for the case where the realm is omitted as well
as the case with an explicitly specified realm. This may well
require a separate {{EX:sasl-regexp}} directive for each case, with the
explicit-realm entry being listed first.

Some sites may have people's DN's spread to multiple areas of the
LDAP tree, such as if there were an {{EX:ou=accounting}} tree and an
{{EX:ou=engineering}} tree, with people interspersed between them. Or
there may not be enough information in the authentication identity
to isolate the DN, such as if the above person's LDAP entry looked
like

>       dn: cn=mark adamson,ou=person,dc=example,dc=com
>       objectclass: Person
>       cn: mark adamson
>       uid: adamson

In this case, the information in the authentication identity can
only be used to search for the user's DN, not derive it directly.
For both of these situations, and others, the replacement pattern
in the {{EX:sasl-regexp}} directives will need to produce an LDAP
URL, described in the next section.


H3: Performing searches for a person's DN

When there is not enough information in the authentication identity
to derive a person's authentication DN directly, the {{EX:sasl-regexp}}
directives in the {{slapd.conf}}(5) file will need to produce an
LDAP URL.  This URL will then be used to perform an internal search
of the LDAP database to find the person's authentication DN.

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 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:sasl-regexp}}
directive might be written as

>       sasl-regexp 
>         uid=(.*),cn=example.com,cn=kerberos_v4,cn=auth  
>         ldap:///ou=person,dc=example,dc=com??sub?(uid=$1)

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 {{EX:(objectClass=person)}} to
avoid matching other entries that happen to refer to the UID.

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.

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 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 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.


H3: SASL Authorization Identities

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>

or

>       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

>       uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth

That authorization request DN is then run through the same
{{EX:sasl-regexp}} process to convert it into a legitimate authorization
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 {{EX:"dn:"}} prefix, the string after the prefix is already in
authorization DN form, ready to undergo approval.


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:

>       saslAuthzTo
>       saslAuthzFrom

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:///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
"dc=example,dc=com" which has an objectClass of "Person".


H4: Notes on Proxy Authorization Rules

An LDAP URL in a {{EX:saslAuthzTo}} or {{EX:saslAuthzFrom}} attribute
will return a set of DNs.  Each DN returned will be checked.
Searches which return a large set can cause the authorization
process to take an uncomfortably long time. Also, searches should
be performed on attributes that have been indexed by slapd.

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
{{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 permissable to enter another authorization
identity of the form "{{EX:u:<username>}}" as an authorization rule.


H4: Policy Configuration

The decision of which type of rules to use, {{EX:saslAuthzFrom}}
or {{EX:saslAuthzTo}}, will depend on the site's situation. For
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: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.