mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
732 lines
31 KiB
Plaintext
732 lines
31 KiB
Plaintext
# $OpenLDAP$
|
|
# Copyright 1999-2018 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:RFC4422}}. This chapter describes how to make use of
|
|
SASL in OpenLDAP.
|
|
|
|
There are several industry standard authentication mechanisms that
|
|
can be used with SASL, including {{TERM:GSSAPI}} for {{TERM:Kerberos}}
|
|
V, {{TERM:DIGEST-MD5}}, and {{TERM:PLAIN}} and {{TERM:EXTERNAL}}
|
|
for use with {{TERM[expand]TLS}} (TLS).
|
|
|
|
The standard client tools provided with OpenLDAP Software, such as
|
|
{{ldapsearch}}(1) and {{ldapmodify}}(1), will by default attempt
|
|
to authenticate the user to the {{TERM:LDAP}} directory server using
|
|
SASL. Basic authentication service can be set up by the LDAP
|
|
administrator with a few steps, allowing users to be authenticated
|
|
to the slapd server as their LDAP entry. With a few extra steps,
|
|
some users and services can be allowed to exploit SASL's proxy
|
|
authorization feature, allowing them to authenticate themselves and
|
|
then switch their identity to that of another user or service.
|
|
|
|
This chapter assumes you have read {{Cyrus SASL for System
|
|
Administrators}}, provided with the {{PRD:Cyrus SASL}}
|
|
package (in {{FILE:doc/sysadmin.html}}) and have a working Cyrus
|
|
SASL installation. You should use the Cyrus SASL {{EX:sample_client}}
|
|
and {{EX:sample_server}} to test your SASL installation before
|
|
attempting to make use of it with OpenLDAP Software.
|
|
|
|
Note that in the following text the term {{user}} is used to describe
|
|
a person or application entity who is connecting to the LDAP server
|
|
via an LDAP client, such as {{ldapsearch}}(1). That is, the term
|
|
{{user}} not only applies to both an individual using an LDAP client,
|
|
but to an application entity which issues LDAP client operations
|
|
without direct user control. For example, an e-mail server which
|
|
uses LDAP operations to access information held in an LDAP server
|
|
is an application entity.
|
|
|
|
|
|
H2: SASL Security Considerations
|
|
|
|
SASL offers many different authentication mechanisms. This section
|
|
briefly outlines security considerations.
|
|
|
|
Some mechanisms, such as PLAIN and LOGIN, offer no greater security
|
|
over LDAP {{simple}} authentication. Like LDAP {{simple}}
|
|
authentication, such mechanisms should not be used unless you have
|
|
adequate security protections in place. It is recommended that
|
|
these mechanisms be used only in conjunction with {{TERM[expand]TLS}}
|
|
(TLS). Use of PLAIN and LOGIN are not discussed further in this
|
|
document.
|
|
|
|
The DIGEST-MD5 mechanism is the mandatory-to-implement authentication
|
|
mechanism for LDAPv3. Though DIGEST-MD5 is not a strong authentication
|
|
mechanism in comparison with trusted third party authentication
|
|
systems (such as {{TERM:Kerberos}} or public key systems), it does
|
|
offer significant protections against a number of attacks. Unlike
|
|
the {{TERM:CRAM-MD5}} mechanism, it prevents chosen plaintext
|
|
attacks. DIGEST-MD5 is favored over the use of plaintext password
|
|
mechanisms. The CRAM-MD5 mechanism is deprecated in favor of
|
|
DIGEST-MD5. Use of {{SECT:DIGEST-MD5}} is discussed below.
|
|
|
|
The GSSAPI mechanism utilizes {{TERM:GSS-API}} {{TERM:Kerberos}} V
|
|
to provide secure authentication services. The KERBEROS_V4 mechanism
|
|
is available for those using Kerberos IV. Kerberos is viewed as a
|
|
secure, distributed authentication system suitable for both small
|
|
and large enterprises. Use of {{SECT:GSSAPI}} and {{SECT:KERBEROS_V4}}
|
|
are discussed below.
|
|
|
|
The EXTERNAL mechanism utilizes authentication services provided
|
|
by lower level network services such as {{TERM[expand]TLS}} ({{TERM:TLS}}). When
|
|
used in conjunction with {{TERM:TLS}} {{TERM:X.509}}-based public
|
|
key technology, EXTERNAL offers strong authentication.
|
|
TLS is discussed in the {{SECT:Using TLS}} chapter.
|
|
|
|
EXTERNAL can also be used with the {{EX:ldapi:///}} transport, as
|
|
Unix-domain sockets can report the UID and GID of the client process.
|
|
|
|
There are other strong authentication mechanisms to choose from,
|
|
including {{TERM:OTP}} (one time passwords) and {{TERM:SRP}} (secure
|
|
remote passwords). These mechanisms are not discussed in this
|
|
document.
|
|
|
|
|
|
H2: SASL Authentication
|
|
|
|
Getting basic SASL authentication running involves a few steps.
|
|
The first step configures your slapd server environment so that it
|
|
can communicate with client programs using the security system in
|
|
place at your site. This usually involves setting up a service key,
|
|
a public key, or other form of secret. The second step concerns
|
|
mapping authentication identities to LDAP {{TERM:DN}}'s, which
|
|
depends on how entries are laid out in your directory. An explanation
|
|
of the first step will be given in the next section using Kerberos
|
|
V4 as an example mechanism. The steps necessary for your site's
|
|
authentication mechanism will be similar, but a guide to every
|
|
mechanism available under SASL is beyond the scope of this chapter.
|
|
The second step is described in the section {{SECT:Mapping
|
|
Authentication Identities}}.
|
|
|
|
|
|
H3: GSSAPI
|
|
|
|
This section describes the use of the SASL GSSAPI mechanism and
|
|
Kerberos V with OpenLDAP. It will be assumed that you have Kerberos
|
|
V deployed, you are familiar with the operation of the system, and
|
|
that your users are trained in its use. This section also assumes
|
|
you have familiarized yourself with the use of the GSSAPI mechanism
|
|
by reading {{Configuring GSSAPI and Cyrus SASL}} (provided with
|
|
Cyrus SASL in the {{FILE:doc/gssapi}} file) and successfully
|
|
experimented with the Cyrus provided {{EX:sample_server}} and
|
|
{{EX:sample_client}} applications. General information about
|
|
Kerberos is available at {{URL:http://web.mit.edu/kerberos/www/}}.
|
|
|
|
To use the GSSAPI mechanism with {{slapd}}(8) one must create a service
|
|
key with a principal for {{ldap}} service within the realm for the host
|
|
on which the service runs. For example, if you run {{slapd}} on
|
|
{{EX:directory.example.com}} and your realm is {{EX:EXAMPLE.COM}},
|
|
you need to create a service key with the principal:
|
|
|
|
> ldap/directory.example.com@EXAMPLE.COM
|
|
|
|
When {{slapd}}(8) runs, it must have access to this key. This is
|
|
generally done by placing the key into a keytab file,
|
|
{{FILE:/etc/krb5.keytab}}. See your Kerberos and Cyrus SASL
|
|
documentation for information regarding keytab location settings.
|
|
|
|
To use the GSSAPI mechanism to authenticate to the directory, the
|
|
user obtains a Ticket Granting Ticket (TGT) prior to running the
|
|
LDAP client. When using OpenLDAP client tools, the user may mandate
|
|
use of the GSSAPI mechanism by specifying {{EX:-Y GSSAPI}} as a
|
|
command option.
|
|
|
|
For the purposes of authentication and authorization, {{slapd}}(8)
|
|
associates an authentication request DN of the form:
|
|
|
|
> uid=<primary[/instance]>,cn=<realm>,cn=gssapi,cn=auth
|
|
|
|
Continuing our example, a user with the Kerberos principal
|
|
{{EX:kurt@EXAMPLE.COM}} would have the associated DN:
|
|
|
|
> uid=kurt,cn=example.com,cn=gssapi,cn=auth
|
|
|
|
and the principal {{EX:ursula/admin@FOREIGN.REALM}} would have the
|
|
associated DN:
|
|
|
|
> uid=ursula/admin,cn=foreign.realm,cn=gssapi,cn=auth
|
|
|
|
|
|
The authentication request DN can be used directly ACLs and
|
|
{{EX:groupOfNames}} "member" attributes, since it is of legitimate
|
|
LDAP DN format. Or alternatively, the authentication DN could be
|
|
mapped before use. See the section {{SECT:Mapping Authentication
|
|
Identities}} for details.
|
|
|
|
|
|
H3: KERBEROS_V4
|
|
|
|
This section describes the use of the SASL KERBEROS_V4 mechanism
|
|
with OpenLDAP. It will be assumed that you are familiar with the
|
|
workings of the Kerberos IV security system, and that your site has
|
|
Kerberos IV deployed. Your users should be familiar with
|
|
authentication policy, how to receive credentials in
|
|
a Kerberos ticket cache, and how to refresh expired credentials.
|
|
|
|
Note: KERBEROS_V4 and Kerberos IV are deprecated in favor of GSSAPI
|
|
and Kerberos V.
|
|
|
|
Client programs will need to be able to obtain a session key for
|
|
use when connecting to your LDAP server. This allows the LDAP server
|
|
to know the identity of the user, and allows the client to know it
|
|
is connecting to a legitimate server. If encryption layers are to
|
|
be used, the session key can also be used to help negotiate that
|
|
option.
|
|
|
|
The slapd server runs the service called "{{ldap}}", and the server
|
|
will require a srvtab file with a service key. SASL aware client
|
|
programs will be obtaining an "ldap" service ticket with the user's
|
|
ticket granting ticket (TGT), with the instance of the ticket
|
|
matching the hostname of the OpenLDAP server. For example, if your
|
|
realm is named {{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, the client may print out the message:
|
|
|
|
> ldap_sasl_interactive_bind_s: Local error
|
|
|
|
When the service ticket is obtained, it will be passed to the LDAP
|
|
server as proof of the user's identity. The server will 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=adamson,cn=example.com,cn=kerberos_v4,cn=auth
|
|
|
|
This authentication request DN can be used directly ACLs or,
|
|
alternatively, mapped prior to use. See the section {{SECT:Mapping
|
|
Authentication Identities}} for details.
|
|
|
|
|
|
H3: DIGEST-MD5
|
|
|
|
This section describes the use of the SASL DIGEST-MD5 mechanism
|
|
using secrets stored either in the directory itself or in Cyrus
|
|
SASL's own database. DIGEST-MD5 relies on the client and the server
|
|
sharing a "secret", usually a password. The server generates a
|
|
challenge and the client a response proving that it knows the shared
|
|
secret. This is much more secure than simply sending the secret
|
|
over the wire.
|
|
|
|
Cyrus SASL supports several shared-secret mechanisms. To do this,
|
|
it needs access to the plaintext password (unlike mechanisms which
|
|
pass plaintext passwords over the wire, where the server can store
|
|
a hashed version of the password).
|
|
|
|
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:
|
|
|
|
> 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 set using
|
|
the LDAP Password Modify Operation are stored in plaintext:
|
|
|
|
> password-hash {CLEARTEXT}
|
|
|
|
Passwords stored in this way can be managed either with {{ldappasswd}}(1)
|
|
or by simply modifying the {{EX:userPassword}} attribute. Regardless of
|
|
where the passwords are stored, a mapping will be needed from
|
|
authentication request DN to user's DN.
|
|
|
|
The DIGEST-MD5 mechanism produces authentication IDs of the form:
|
|
|
|
> uid=<username>,cn=<realm>,cn=digest-md5,cn=auth
|
|
|
|
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}} below for information
|
|
on optional mapping of identities.
|
|
|
|
With suitable mappings in place, users can specify SASL IDs when
|
|
performing LDAP operations, and the password stored in {{sasldb}} or in
|
|
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 -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).
|
|
|
|
|
|
H3: EXTERNAL
|
|
|
|
The SASL EXTERNAL mechanism makes use of an authentication performed
|
|
by a lower-level protocol: usually {{TERM:TLS}} or Unix {{TERM:IPC}}
|
|
|
|
Each transport protocol returns Authentication Identities in its own
|
|
format:
|
|
|
|
H4: TLS Authentication Identity Format
|
|
|
|
This is the Subject DN from the client-side certificate.
|
|
Note that DNs are displayed differently by LDAP and by X.509, so
|
|
a certificate issued to
|
|
> C=gb, O=The Example Organisation, CN=A Person
|
|
|
|
will produce an authentication identity of:
|
|
|
|
> cn=A Person,o=The Example Organisation,c=gb
|
|
|
|
Note that you must set a suitable value for TLSVerifyClient to make the server
|
|
request the use of a client-side certificate. Without this, the SASL EXTERNAL
|
|
mechanism will not be offered.
|
|
Refer to the {{SECT:Using TLS}} chapter for details.
|
|
|
|
H4: IPC (ldapi:///) Identity Format
|
|
|
|
This is formed from the Unix UID and GID of the client process:
|
|
|
|
> gidNumber=<number>+uidNumber=<number>,cn=peercred,cn=external,cn=auth
|
|
|
|
Thus, a client process running as {{EX:root}} will be:
|
|
|
|
> gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
|
|
|
|
|
|
H3: Mapping Authentication Identities
|
|
|
|
The authentication mechanism in the slapd server will use SASL
|
|
library calls to obtain the authenticated user's "username", based
|
|
on whatever underlying authentication mechanism was used. This
|
|
username is in the namespace of the authentication mechanism, and
|
|
not in the normal LDAP namespace. As stated in the sections above,
|
|
that username is reformatted into an authentication request DN of
|
|
the form
|
|
|
|
> uid=<username>,cn=<realm>,cn=<mechanism>,cn=auth
|
|
|
|
or
|
|
|
|
> uid=<username>,cn=<mechanism>,cn=auth
|
|
|
|
depending on whether or not <mechanism> employs the concept of
|
|
"realms". Note also that the realm part will be omitted if the
|
|
default realm was used in the authentication.
|
|
|
|
The {{ldapwhoami}}(1) command may be used to determine the identity
|
|
associated with the user. It is very useful for determining proper
|
|
function of mappings.
|
|
|
|
It is not intended that you should add LDAP entries of the above
|
|
form to your LDAP database. Chances are you have an LDAP entry for
|
|
each of the persons that will be authenticating to LDAP, laid out
|
|
in your directory tree, and the tree does not start at cn=auth.
|
|
But if your site has a clear mapping between the "username" and an
|
|
LDAP entry for the person, you will be able to configure your LDAP
|
|
server to automatically map a authentication request DN to the
|
|
user's {{authentication DN}}.
|
|
|
|
Note: it is not required that the authentication request DN nor the
|
|
user's authentication DN resulting from the mapping refer to an
|
|
entry held in the directory. However, additional capabilities
|
|
become available (see below).
|
|
|
|
The LDAP administrator will need to tell the slapd server how to
|
|
map an authentication request DN to a user's authentication DN.
|
|
This is done by adding one or more {{EX:authz-regexp}} directives to
|
|
the {{slapd.conf}}(5) file. This directive takes two arguments:
|
|
|
|
> authz-regexp <search pattern> <replacement pattern>
|
|
|
|
The authentication request DN is compared to the search pattern
|
|
using the regular expression functions {{regcomp}}() and {{regexec}}(),
|
|
and if it matches, it is rewritten as the replacement pattern. If
|
|
there are multiple {{EX:authz-regexp}} directives, only the first
|
|
whose search pattern matches the authentication identity is used.
|
|
The string that is output from the replacement pattern should be
|
|
the authentication DN of the user or an LDAP URL. If replacement
|
|
string produces a DN, the entry named by this DN need not be held
|
|
by this server. If the replace string produces an LDAP URL, that
|
|
LDAP URL must evaluate to one and only one entry held by this server.
|
|
|
|
The search pattern can contain any of the regular expression
|
|
characters listed in {{regexec}}(3C). The main characters of note
|
|
are dot ".", asterisk "*", and the open and close parenthesis "("
|
|
and ")". Essentially, the dot matches any character, the asterisk
|
|
allows zero or more repeats of the immediately preceding character
|
|
or pattern, and terms in parenthesis are remembered for the replacement
|
|
pattern.
|
|
|
|
The replacement pattern will produce either a DN or URL referring
|
|
to the user. Anything from the authentication request DN that
|
|
matched a string in parenthesis in the search pattern is stored in
|
|
the variable "$1". That variable "$1" can appear in the replacement
|
|
pattern, and will be replaced by the string from the authentication
|
|
request DN. If there were multiple sets of parentheses in the search
|
|
pattern, the variables $2, $3, etc are used.
|
|
|
|
H3: Direct Mapping
|
|
|
|
Where possible, direct mapping of the authentication request DN to
|
|
the user's DN is generally recommended. Aside from avoiding the
|
|
expense of searching for the user's DN, it allows mapping to
|
|
DNs which refer to entries not held by this server.
|
|
|
|
Suppose the authentication request DN is written as:
|
|
|
|
> uid=adamson,cn=example.com,cn=gssapi,cn=auth
|
|
|
|
and the user's actual LDAP entry is:
|
|
|
|
> uid=adamson,ou=people,dc=example,dc=com
|
|
|
|
then the following {{EX:authz-regexp}} directive in {{slapd.conf}}(5)
|
|
would provide for direct mapping.
|
|
|
|
> authz-regexp
|
|
> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
|
|
> uid=$1,ou=people,dc=example,dc=com
|
|
|
|
An even more lenient rule could be written as
|
|
|
|
> authz-regexp
|
|
> uid=([^,]*),cn=[^,]*,cn=auth
|
|
> uid=$1,ou=people,dc=example,dc=com
|
|
|
|
Be careful about setting the search pattern too leniently, however,
|
|
since it may mistakenly allow persons to become authenticated as a
|
|
DN to which they should not have access. It is better to write
|
|
several strict directives than one lenient directive which has
|
|
security holes. If there is only one authentication mechanism in
|
|
place at your site, and zero or one realms in use, you might be
|
|
able to map between authentication identities and LDAP DN's with a
|
|
single {{EX:authz-regexp}} directive.
|
|
|
|
Don't forget to allow for the case where the realm is omitted as
|
|
well as the case with an explicitly specified realm. This may well
|
|
require a separate {{EX:authz-regexp}} directive for each case, with
|
|
the explicit-realm entry being listed first.
|
|
|
|
H3: Search-based mappings
|
|
|
|
There are a number of cases where mapping to a LDAP URL may be
|
|
appropriate. For instance, some sites may have person objects
|
|
located in multiple areas of the LDAP tree, such as if there were
|
|
an {{EX:ou=accounting}} tree and an {{EX:ou=engineering}} tree,
|
|
with persons interspersed between them. Or, maybe the desired
|
|
mapping must be based upon information in the user's information.
|
|
Consider the need to map the above authentication request DN to
|
|
user whose entry is as follows:
|
|
|
|
> dn: cn=Mark Adamson,ou=People,dc=Example,dc=COM
|
|
> objectclass: person
|
|
> cn: Mark Adamson
|
|
> uid: adamson
|
|
|
|
The information in the authentication request DN is insufficient
|
|
to allow the user's DN to be directly derived, instead the user's
|
|
DN must be searched for. For these situations, a replacement pattern
|
|
which produces a LDAP URL can be used in the {{EX:authz-regexp}}
|
|
directives. This URL will then be used to perform an internal
|
|
search of the LDAP database to find the person's authentication DN.
|
|
|
|
An LDAP URL, similar to other URL's, is of the form
|
|
|
|
> ldap://<host>/<base>?<attrs>?<scope>?<filter>
|
|
|
|
This contains all of the elements necessary to perform an LDAP
|
|
search: the name of the server <host>, the LDAP DN search base
|
|
<base>, the LDAP attributes to retrieve <attrs>, the search scope
|
|
<scope> which is one of the three options "base", "one", or "sub",
|
|
and lastly an LDAP search filter <filter>. Since the search is for
|
|
an LDAP DN within the current server, the <host> portion should be
|
|
empty. The <attrs> field is also ignored since only the DN is of
|
|
concern. These two elements are left in the format of the URL to
|
|
maintain the clarity of what information goes where in the string.
|
|
|
|
Suppose that the person in the example from above did in fact have
|
|
an authentication username of "adamson" and that information was
|
|
kept in the attribute "uid" in their LDAP entry. The {{EX:authz-regexp}}
|
|
directive might be written as
|
|
|
|
> authz-regexp
|
|
> uid=([^,]*),cn=example.com,cn=gssapi,cn=auth
|
|
> ldap:///ou=people,dc=example,dc=com??one?(uid=$1)
|
|
|
|
This will initiate an internal search of the LDAP database inside
|
|
the slapd server. If the search returns exactly one entry, it is
|
|
accepted as being the DN of the user. If there are more than one
|
|
entries returned, or if there are zero entries returned, the
|
|
authentication fails and the user's connection is left bound as the
|
|
authentication request DN.
|
|
|
|
The attributes that are used in the search filter <filter> in the
|
|
URL should be indexed to allow faster searching. If they are not,
|
|
the authentication step alone can take uncomfortably long periods,
|
|
and users may assume the server is down.
|
|
|
|
A more complex site might have several realms in use, each mapping
|
|
to a different subtree in the directory. These can be handled with
|
|
statements of the form:
|
|
|
|
> # Match Engineering realm
|
|
> authz-regexp
|
|
> uid=([^,]*),cn=engineering.example.com,cn=digest-md5,cn=auth
|
|
> ldap:///dc=eng,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
|
|
>
|
|
> # Match Accounting realm
|
|
> authz-regexp
|
|
> uid=([^,].*),cn=accounting.example.com,cn=digest-md5,cn=auth
|
|
> ldap:///dc=accounting,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
|
|
>
|
|
> # Default realm is customers.example.com
|
|
> authz-regexp
|
|
> uid=([^,]*),cn=digest-md5,cn=auth
|
|
> ldap:///dc=customers,dc=example,dc=com??one?(&(uid=$1)(objectClass=person))
|
|
|
|
Note that the explicitly-named realms are handled first, to avoid
|
|
the realm name becoming part of the UID. Also note the use of scope
|
|
and filters to limit matching to desirable entries.
|
|
|
|
Note as well that {{EX:authz-regexp}} internal search are subject
|
|
to access controls. Specifically, the authentication identity
|
|
must have {{EX:auth}} access.
|
|
|
|
See {{slapd.conf}}(5) for more detailed information.
|
|
|
|
|
|
H2: SASL Proxy Authorization
|
|
|
|
The SASL offers a feature known as {{proxy authorization}}, which
|
|
allows an authenticated user to request that they act on the behalf
|
|
of another user. This step occurs after the user has obtained an
|
|
authentication DN, and involves sending an authorization identity
|
|
to the server. The server will then make a decision on whether or
|
|
not to allow the authorization to occur. If it is allowed, the
|
|
user's LDAP connection is switched to have a binding DN derived
|
|
from the authorization identity, and the LDAP session proceeds with
|
|
the access of the new authorization DN.
|
|
|
|
The decision to allow an authorization to proceed depends on the
|
|
rules and policies of the site where LDAP is running, and thus
|
|
cannot be made by SASL alone. The SASL library leaves it up to the
|
|
server to make the decision. The LDAP administrator sets the
|
|
guidelines of who can authorize to what identity by adding information
|
|
into the LDAP database entries. By default, the authorization
|
|
features are disabled, and must be explicitly configured by the
|
|
LDAP administrator before use.
|
|
|
|
|
|
H3: Uses of Proxy Authorization
|
|
|
|
This sort of service is useful when one entity needs to act on the
|
|
behalf of many other users. For example, users may be directed to
|
|
a web page to make changes to their personal information in their
|
|
LDAP entry. The users authenticate to the web server to establish
|
|
their identity, but the web server CGI cannot authenticate to the
|
|
LDAP server as that user to make changes for them. Instead, the
|
|
web server authenticates itself to the LDAP server as a service
|
|
identity, say,
|
|
|
|
> cn=WebUpdate,dc=example,dc=com
|
|
|
|
and then it will SASL authorize to the DN of the user. Once so
|
|
authorized, the CGI makes changes to the LDAP entry of the user,
|
|
and as far as the slapd server can tell for its ACLs, it is the
|
|
user themself on the other end of the connection. The user could
|
|
have connected to the LDAP server directly and authenticated as
|
|
themself, but that would require the user to have more knowledge
|
|
of LDAP clients, knowledge which the web page provides in an easier
|
|
format.
|
|
|
|
Proxy authorization can also be used to limit access to an account
|
|
that has greater access to the database. Such an account, perhaps
|
|
even the root DN specified in {{slapd.conf}}(5), can have a strict
|
|
list of people who can authorize to that DN. Changes to the LDAP
|
|
database could then be only allowed by that DN, and in order to
|
|
become that DN, users must first authenticate as one of the persons
|
|
on the list. This allows for better auditing of who made changes
|
|
to the LDAP database. If people were allowed to authenticate
|
|
directly to the privileged account, possibly through the {{EX:rootpw}}
|
|
{{slapd.conf}}(5) directive or through a {{EX:userPassword}}
|
|
attribute, then auditing becomes more difficult.
|
|
|
|
Note that after a successful proxy authorization, the original
|
|
authentication DN of the LDAP connection is overwritten by the new
|
|
DN from the authorization request. If a service program is able to
|
|
authenticate itself as its own authentication DN and then authorize
|
|
to other DN's, and it is planning on switching to several different
|
|
identities during one LDAP session, it will need to authenticate
|
|
itself each time before authorizing to another DN (or use a different
|
|
proxy authorization mechanism). The slapd server does not keep
|
|
record of the service program's ability to switch to other DN's.
|
|
On authentication mechanisms like Kerberos this will not require
|
|
multiple connections being made to the Kerberos server, since the
|
|
user's TGT and "ldap" session key are valid for multiple uses for
|
|
the several hours of the ticket lifetime.
|
|
|
|
|
|
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 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:authz-regexp}} process to convert it into a legitimate authorization
|
|
DN from the database. If it cannot be converted due to a failed
|
|
search from an LDAP URL, the authorization request fails with
|
|
"inappropriate access". Otherwise, the DN string is now a legitimate
|
|
authorization DN ready to undergo approval.
|
|
|
|
If the authorization identity was provided in the second form, with
|
|
a {{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:
|
|
|
|
> authzTo
|
|
> authzFrom
|
|
|
|
Both can be multivalued. The {{EX:authzTo}} attribute is a
|
|
source rule, and it is placed into the entry associated with the
|
|
authentication DN to tell what authorization DNs the authenticated
|
|
DN is allowed to assume. The second attribute is a destination
|
|
rule, and it is placed into the entry associated with the requested
|
|
authorization DN to tell which authenticated DNs may assume it.
|
|
|
|
The choice of which authorization policy attribute to use is up to
|
|
the administrator. Source rules are checked first in the person's
|
|
authentication DN entry, and if none of the {{EX:authzTo}} rules
|
|
specify the authorization is permitted, the {{EX:authzFrom}}
|
|
rules in the authorization DN entry are then checked. If neither
|
|
case specifies that the request be honored, the request is denied.
|
|
Since the default behavior is to deny authorization requests, rules
|
|
only specify that a request be allowed; there are no negative rules
|
|
telling what authorizations to deny.
|
|
|
|
The value(s) in the two attributes are of the same form as the
|
|
output of the replacement pattern of a {{EX:authz-regexp}} directive:
|
|
either a DN or an LDAP URL. For example, if a {{EX:authzTo}}
|
|
value is a DN, that DN is one the authenticated user can authorize
|
|
to. On the other hand, if the {{EX:authzTo}} value is an LDAP
|
|
URL, the URL is used as an internal search of the LDAP database,
|
|
and the authenticated user can become ANY DN returned by the search.
|
|
If an LDAP entry looked like:
|
|
|
|
> dn: cn=WebUpdate,dc=example,dc=com
|
|
> 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
|
|
{{EX:dc=example,dc=com}} which has an objectClass of {{EX:Person}}.
|
|
|
|
|
|
H4: Notes on Proxy Authorization Rules
|
|
|
|
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: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
|
|
|
|
> authzTo: dn.regex:^uid=[^,]*,dc=example,dc=com$
|
|
|
|
would allow that authenticated user to authorize to any DN that
|
|
matches the regular expression pattern given. This regular expression
|
|
comparison can be evaluated much faster than an LDAP search for
|
|
{{EX:(uid=*)}}.
|
|
|
|
Also note that the values in an authorization rule must be one of
|
|
the two forms: an LDAP URL or a DN (with or without regular expression
|
|
characters). Anything that does not begin with "{{EX:ldap://}}" is
|
|
taken as a DN. It is not permissible to enter another authorization
|
|
identity of the form "{{EX:u:<username>}}" as an authorization rule.
|
|
|
|
|
|
H4: Policy Configuration
|
|
|
|
The decision of which type of rules to use, {{EX:authzFrom}}
|
|
or {{EX:authzTo}}, will depend on the site's situation. For
|
|
example, if the set of people who may become a given identity can
|
|
easily be written as a search filter, then a single destination
|
|
rule could be written. If the set of people is not easily defined
|
|
by a search filter, and the set of people is small, it may be better
|
|
to write a source rule in the entries of each of those people who
|
|
should be allowed to perform the proxy authorization.
|
|
|
|
By default, processing of proxy authorization rules is disabled.
|
|
The {{EX:authz-policy}} directive must be set in the
|
|
{{slapd.conf}}(5) file to enable authorization. This directive can
|
|
be set to {{EX:none}} for no rules (the default), {{EX:to}} for
|
|
source rules, {{EX:from}} for destination rules, or {{EX:both}} for
|
|
both source and destination rules.
|
|
|
|
Source rules are extremely powerful. If ordinary users have
|
|
access to write the {{EX:authzTo}} attribute in their own
|
|
entries, then they can write rules that would allow them to authorize
|
|
as anyone else. As such, when using source rules, the
|
|
{{EX:authzTo}} attribute should be protected with an ACL that
|
|
only allows privileged users to set its values.
|
|
|