sasl.sdf

OpenLdap是LDAP的开源项目

# Copyright 1999-2007 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:GSSAPI}} for {{TERM:Kerberos}}
V, DIGEST-MD5, and PLAIN and 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.

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

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 {{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 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/[e-mail]

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:[e-mail]}} would have the associated DN:

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

and the principal {{EX:ursula/[e-mail]}} 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

>	[e-mail]

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=adamsom,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 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
>       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: 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.