-# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved.
+# $OpenLDAP$
+# Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Using SASL
OpenLDAP clients and servers are capable of authenticating via the
{{TERM[expand]SASL}} ({{TERM:SASL}}) framework, which is detailed
-in {{REF:RFC2222}}. This chapter describes how to make use of
+in {{REF:RFC4422}}. This chapter describes how to make use of
SASL in OpenLDAP.
There are several industry standard authentication mechanisms that
can be used with SASL, including {{TERM:GSSAPI}} for {{TERM:Kerberos}}
-V, DIGEST-MD5, and PLAIN and EXTERNAL for use with {{TERM[expand]TLS}}
-(TLS).
+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 {{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.
+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}} {{PRD:SASL}}
+Administrators}}, provided with the {{PRD:Cyrus SASL}}
package (in {{FILE:doc/sysadmin.html}}) and have a working Cyrus
SASL installation. You should use the Cyrus SASL {{EX:sample_client}}
and {{EX:sample_server}} to test your SASL installation before
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), 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 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 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.
+systems (such as {{TERM:Kerberos}} or public key systems), it does
+offer significant protections against a number of attacks. Unlike
+the {{TERM:CRAM-MD5}} mechanism, it prevents chosen plaintext
+attacks. DIGEST-MD5 is favored over the use of plaintext password
+mechanisms. The CRAM-MD5 mechanism is deprecated in favor of
+DIGEST-MD5. Use of {{SECT:DIGEST-MD5}} is discussed below.
+
+The GSSAPI mechanism utilizes {{TERM:GSS-API}} {{TERM:Kerberos}} V
+to provide secure authentication services. The KERBEROS_V4 mechanism
+is available for those using Kerberos IV. Kerberos is viewed as a
+secure, distributed authentication system suitable for both small
+and large enterprises. Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}}
+are discussed below.
The EXTERNAL mechanism utilizes authentication services provided
by lower level network services such as {{TERM:TLS}} (TLS). When
H2: SASL Authentication
Getting basic SASL authentication running involves a few steps.
-The first step configures your slapd server environment so
-that it can communicate with client programs using the security
-system in place at your site. This usually involves setting up a
-service key, a public key, or other form of secret. The second step
-concerns mapping authentication identities to LDAP DN's, which
+The first step configures your slapd server environment so that it
+can communicate with client programs using the security system in
+place at your site. This usually involves setting up a service key,
+a public key, or other form of secret. The second step concerns
+mapping authentication identities to LDAP {{TERM:DN}}'s, which
depends on how entries are laid out in your directory. An explanation
of the first step will be given in the next section using Kerberos
V4 as an example mechanism. The steps necessary for your site's
authentication mechanism will be similar, but a guide to every
mechanism available under SASL is beyond the scope of this chapter.
-The second step is described in the section
-{{SECT:Mapping Authentication Identities}}.
+The second step is described in the section {{SECT:Mapping
+Authentication Identities}}.
H3: GSSAPI
same principal, either from the ticket cache or by obtaining a new
one from the Kerberos server. This will require the TGT to be
available and valid in the cache as well. If it is not present or
-has expired, SASL will print out the message
+has expired, the client may print out the message:
> ldap_sasl_interactive_bind_s: Local error
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 Software 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".
+The server's copy of the shared-secret may be stored in Cyrus SASL's
+own {{sasldb}} database, in an external system accessed via
+{{saslauthd}}, or in LDAP database itself. In either case it is
+very important to apply file access controls and LDAP access controls
+to prevent exposure of the passwords. The configuration and commands
+discussed in this section assume the use of Cyrus SASL 2.1.
To use secrets stored in {{sasldb}}, simply add users with the
{{saslpasswd2}} command:
command.
To use secrets stored in the LDAP directory, place plaintext passwords
-in the {{EX:userPassword}} attribute. It will be necessary to add
-an option to {{EX:slapd.conf}} to make sure that passwords changed
-through LDAP are stored in plaintext:
+in the {{EX:userPassword}} attribute. It will be necessary to add
+an option to {{EX:slapd.conf}} to make sure that passwords set using
+the LDAP Password Modify Operation are stored in plaintext:
> password-hash {CLEARTEXT}
-Passwords stored in this way can be managed either with {{EX:ldappasswd}}
-or by simply modifying the {{EX:userPassword}} attribute.
+Passwords stored in this way can be managed either with {{ldappasswd}}(1)
+or by simply modifying the {{EX:userPassword}} attribute. Regardless of
+where the passwords are stored, a mapping will be needed from
+authentication request DN to user's DN.
-Wherever the passwords are stored, a mapping will be needed from SASL
-authentication IDs to regular DNs. The DIGEST-MD5 mechanism produces
-authentication IDs of the form:
+The DIGEST-MD5 mechanism produces authentication IDs of the form:
> uid=<username>,cn=<realm>,cn=digest-md5,cn=auth
-NOTE that if the default realm is used, the realm name is omitted from
-the ID, giving:
+If the default realm is used, the realm name is omitted from the ID,
+giving:
> uid=<username>,cn=digest-md5,cn=auth
on optional mapping of identities.
With suitable mappings in place, users can specify SASL IDs when
-performing LDAP operations, and the password stored in {{sasldb}} or in
-the directory itself will be used to verify the authentication.
-For example, the user identified by the directory entry:
+performing LDAP operations and sldb}} and 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
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*'
-
+> ldapsearch -Y DIGEST-MD5 -U u000997 ...
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).
+{{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
> uid=<username>,cn=<mechanism>,cn=auth
depending on whether or not <mechanism> employs the concept of
-"realms". Note also that the realm part will be omitted if the default
-realm was used in the authentication.
+"realms". Note also that the realm part will be omitted if the
+default realm was used in the authentication.
+
+The {{ldapwhoami}}(1) command may be used to determine the identity
+associated with the user. It is very useful for determining proper
+function of mappings.
It is not intended that you should add LDAP entries of the above
form to your LDAP database. Chances are you have an LDAP entry for
The LDAP administrator will need to tell the slapd server how to
map an authentication request DN to a user's authentication DN.
-This is done by adding one or more {{EX:sasl-regexp}} directives to
+This is done by adding one or more {{EX:authz-regexp}} directives to
the {{slapd.conf}}(5) file. This directive takes two arguments:
-> sasl-regexp <search pattern> <replacement pattern>
+> authz-regexp <search pattern> <replacement pattern>
The authentication request DN is compared to the search pattern
using the regular expression functions {{regcomp}}() and {{regexec}}(),
and if it matches, it is rewritten as the replacement pattern. If
-there are multiple {{EX:sasl-regexp}} directives, only the first
+there are multiple {{EX:authz-regexp}} directives, only the first
whose search pattern matches the authentication identity is used.
The string that is output from the replacement pattern should be
the authentication DN of the user or an LDAP URL. If replacement
or pattern, and terms in parenthesis are remembered for the replacement
pattern.
-The replacement pattern will produce either a DN or URL refering
+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
> uid=adamson,ou=people,dc=example,dc=com
-then the following {{EX:sasl-regexp}} directive in {{slapd.conf}}(5)
+then the following {{EX:authz-regexp}} directive in {{slapd.conf}}(5)
would provide for direct mapping.
-> sasl-regexp
+> authz-regexp
> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
> uid=$1,ou=people,dc=example,dc=com
An even more lenient rule could be written as
-> sasl-regexp
+> authz-regexp
> uid=([^,]*),cn=[^,]*,cn=auth
> uid=$1,ou=people,dc=example,dc=com
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.
+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:sasl-regexp}} directive for each case, with
+require a separate {{EX:authz-regexp}} directive for each case, with
the explicit-realm entry being listed first.
H3: Search-based mappings
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:sasl-regexp}}
+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.
Suppose that the person in the example from above did in fact have
an authentication username of "adamson" and that information was
-kept in the attribute "uid" in their LDAP entry. The {{EX:sasl-regexp}}
+kept in the attribute "uid" in their LDAP entry. The {{EX:authz-regexp}}
directive might be written as
-> sasl-regexp
+> authz-regexp
> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
> ldap:///ou=people,dc=example,dc=com??one?(uid=$1)
statements of the form:
> # Match Engineering realm
-> sasl-regexp
+> authz-regexp
> uid=([^,]*),cn=engineering.example.com,cn=digest-md5,cn=auth
> ldap:///dc=eng,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
>
> # Match Accounting realm
-> sasl-regexp
+> authz-regexp
> uid=([^,].*),cn=accounting.example.com,cn=digest-md5,cn=auth
> ldap:///dc=accounting,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
>
> # Default realm is customers.example.com
-> sasl-regexp
+> authz-regexp
> uid=([^,]*),cn=digest-md5,cn=auth
> ldap:///dc=customers,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
the realm name becoming part of the UID. Also note the use of scope
and filters to limit matching to desirable entries.
+Note as well that {{EX:authz-regexp}} internal search are subject
+to access controls. Specifically, the authentication identity
+must have {{EX:auth}} access.
+
See {{slapd.conf}}(5) for more detailed information.
become that DN, users must first authenticate as one of the persons
on the list. This allows for better auditing of who made changes
to the LDAP database. If people were allowed to authenticate
-directly to the priviliged account, possibly through the {{EX:rootpw}}
+directly to the privileged account, possibly through the {{EX:rootpw}}
{{slapd.conf}}(5) directive or through a {{EX:userPassword}}
attribute, then auditing becomes more difficult.
In the first form, the <username> is from the same namespace as
the authentication identities above. It is the user's username as
-it is refered to by the underlying authentication mechanism.
+it is referred to by the underlying authentication mechanism.
Authorization identities of this form are converted into a DN format
by the same function that the authentication process used, producing
an {{authorization request DN}} of the form
> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
That authorization request DN is then run through the same
-{{EX:sasl-regexp}} process to convert it into a legitimate authorization
+{{EX:authz-regexp}} process to convert it into a legitimate authorization
DN from the database. If it cannot be converted due to a failed
search from an LDAP URL, the authorization request fails with
"inappropriate access". Otherwise, the DN string is now a legitimate
begins. There are two attributes that the LDAP administrator can
put into LDAP entries to allow authorization:
-> saslAuthzTo
-> saslAuthzFrom
+> authzTo
+> authzFrom
-Both can be multivalued. The {{EX:saslAuthzTo}} attribute is a
+Both can be multivalued. The {{EX:authzTo}} attribute is a
source rule, and it is placed into the entry associated with the
authentication DN to tell what authorization DNs the authenticated
DN is allowed to assume. The second attribute is a destination
The choice of which authorization policy attribute to use is up to
the administrator. Source rules are checked first in the person's
-authentication DN entry, and if none of the {{EX:saslAuthzTo}} rules
-specify the authorization is permitted, the {{EX:saslAuthzFrom}}
+authentication DN entry, and if none of the {{EX:authzTo}} rules
+specify the authorization is permitted, the {{EX:authzFrom}}
rules in the authorization DN entry are then checked. If neither
case specifies that the request be honored, the request is denied.
-Since the default behaviour is to deny authorization requests, rules
+Since the default behavior is to deny authorization requests, rules
only specify that a request be allowed; there are no negative rules
telling what authorizations to deny.
The value(s) in the two attributes are of the same form as the
-output of the replacement pattern of a {{EX:sasl-regexp}} directive:
-either a DN or an LDAP URL. For example, if a {{EX:saslAuthzTo}}
+output of the replacement pattern of a {{EX:authz-regexp}} directive:
+either a DN or an LDAP URL. For example, if a {{EX:authzTo}}
value is a DN, that DN is one the authenticated user can authorize
-to. On the other hand, if the {{EX:saslAuthzTo}} value is an LDAP
+to. On the other hand, if the {{EX:authzTo}} value is an LDAP
URL, the URL is used as an internal search of the LDAP database,
and the authenticated user can become ANY DN returned by the search.
If an LDAP entry looked like:
> dn: cn=WebUpdate,dc=example,dc=com
-> saslAuthzTo: ldap:///dc=example,dc=com??sub?(objectclass=person)
+> authzTo: ldap:///dc=example,dc=com??sub?(objectclass=person)
then any user who authenticated as {{EX:cn=WebUpdate,dc=example,dc=com}}
could authorize to any other LDAP entry under the search base
H4: Notes on Proxy Authorization Rules
-An LDAP URL in a {{EX:saslAuthzTo}} or {{EX:saslAuthzFrom}} attribute
+An LDAP URL in a {{EX:authzTo}} or {{EX:authzFrom}} attribute
will return a set of DNs. Each DN returned will be checked. Searches
which return a large set can cause the authorization process to
take an uncomfortably long time. Also, searches should be performed
on attributes that have been indexed by slapd.
-To help produce more sweeping rules for {{EX:saslAuthzFrom}} and
-{{EX:saslAuthzTo}}, the values of these attributes are allowed to
+To help produce more sweeping rules for {{EX:authzFrom}} and
+{{EX:authzTo}}, the values of these attributes are allowed to
be DNs with regular expression characters in them. This means a
source rule like
-> saslAuthzTo: uid=[^,]*,dc=example,dc=com
+> authzTo: dn.regex=^uid=[^,]*,dc=example,dc=com$
would allow that authenticated user to authorize to any DN that
matches the regular expression pattern given. This regular expression
Also note that the values in an authorization rule must be one of
the two forms: an LDAP URL or a DN (with or without regular expression
characters). Anything that does not begin with "{{EX:ldap://}}" is
-taken as a DN. It is not permissable to enter another authorization
+taken as a DN. It is not permissible to enter another authorization
identity of the form "{{EX:u:<username>}}" as an authorization rule.
H4: Policy Configuration
-The decision of which type of rules to use, {{EX:saslAuthzFrom}}
-or {{EX:saslAuthzTo}}, will depend on the site's situation. For
+The decision of which type of rules to use, {{EX:authzFrom}}
+or {{EX:authzTo}}, will depend on the site's situation. For
example, if the set of people who may become a given identity can
easily be written as a search filter, then a single destination
rule could be written. If the set of people is not easily defined
should be allowed to perform the proxy authorization.
By default, processing of proxy authorization rules is disabled.
-The {{EX:sasl-authz-policy}} directive must be set in the
+The {{EX:authz-policy}} directive must be set in the
{{slapd.conf}}(5) file to enable authorization. This directive can
-be set to {{EX:none}} for no rules (the default), {{EX:from}} for
-source rules, {{EX:to}} for destination rules, or {{EX:both}} for
+be set to {{EX:none}} for no rules (the default), {{EX:to}} for
+source rules, {{EX:from}} for destination rules, or {{EX:both}} for
both source and destination rules.
-Destination rules are extremely powerful. If ordinary users have
-access to write the {{EX:saslAuthzTo}} attribute in their own
+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 destination rules, the
-{{EX:saslAuthzTo}} attribute should be protected with an ACL that
+as anyone else. As such, when using source rules, the
+{{EX:authzTo}} attribute should be protected with an ACL that
only allows privileged users to set its values.
projects / openldap / blobdiff