Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide

Configuring Credential Levels and Authentication Methods

The security model that is applied to clients is defined through a combination of the credential level and the authentication method.

Directory Server supports the following credential levels:

Anonymous. Allowing anonymous access for certain parts of the directory implies that anyone with access to the directory has read access.

If you use an anonymous credential level, you need to allow read access to all the LDAP naming entries and attributes.

Caution –
Do not allow anonymous write access to a directory because anyone could change information in the DIT to which they have write access, including another user's password, or their own identity.
Proxy. The client authenticates or binds to the directory using a proxy account.

This proxy account can be any entry that is allowed to bind to the directory. The proxy account needs sufficient access to perform the naming service functions on the directory. You need to configure the proxyDN and proxyPassword on every client using the proxy credential level. The encrypted proxyPassword is stored locally on the client.
Proxy anonymous. A multivalued entry in which more than one credential level is defined.

A client assigned the proxy anonymous level will first attempt to authenticate with its proxy identity. If the client is unable to authenticate as the proxy user for whatever reason (user lockout, password expired, for example), then the client will use anonymous access. This might lead to a different level of service, depending on how the directory is configured.

Client authentication is a mechanism for the server to verify the identity of the client.

Client authentication can be performed in one of the following ways:

By providing a DN and a password.
Through a certificate presented by the client.

Certificate-based authentication uses the client certificate that is obtained through the SSL protocol to find a user entry for identification. In certificate-based authentication, the client sends an SASL bind request specifying an external mechanism. The bind request relies on the SSL authentication mechanism that has already been established.
Through a SASL-based mechanism.
- On all operating systems, SASL through DIGEST-MD5.
- On the Solaris Operating System, SASL through the GSSAPI mechanism which allows the authentication of a client through Kerberos V5.
When using either of the two SASL mechanisms, the server must also be configured to perform identity mapping. The SASL credentials are called the Principal. Each mechanism must have specific mappings to determine the bind DN from the contents of the Principal. When the Principal is mapped to a single user entry and the SASL mechanism validates that user's identity, the user's DN is the bind DN for the connection.
Through SSL client authentication mode.

Use SSL client authentication when you want all clients to be authorized at the SSL layer. The client application authenticates by sending its SSL certificate to the server. You specify whether the server allows, requires, or does not allow SSL client authentication using the SSL-client-auth-mode flag. By default, clients are allowed to authenticate.

This section provides the following information about configuring the two SASL mechanisms on Directory Server.

For more information about configuring security, see Configuring LDAP Clients to Use Security.

Setting SASL Encryption Levels in Directory Server

Before configuring the SASL mechanism, you must specify whether you require encryption or not. Requirements for SASL encryption are set by the maximum and minimum Strength Security Factor (SSF).

The attributes dsSaslMinSSF(5dsat) and dsSaslMaxSSF(5dsat) represent the encryption key length, and they are stored in cn=SASL, cn=security, cn=config.

The server allows any level of encryption, including no encryption. This means that Directory Server accepts dsSaslMinSSF and dsSaslMaxSSF values greater than 256. However, no SASL mechanisms currently support an SSF greater than 128. Directory Server negotiates these values down to the highest SSF possible (128). Therefore, the highest actual SSF might be less than the configured maximum, depending on the underlying mechanisms available.

SASL security factor authentication depends two main items: the minimum and maximum factors requested by the server and client applications, and the available encryption mechanisms, which are provided by the underlying security components. In summary, the server and client attempt to use the highest available security factor that is less than or equal to the maximum factors set on both, but greater than or equal to the minimum factors on both.

The default minimum SASL security factor for Directory Server, dsSaslMinSSF, is 0, meaning no protection. The actual minimum depends on the client setting, unless you change the minimum for Directory Server. In practice, you should set the minimum to the lowest level that you actually want the server and client to use. If the server and client fail to negotiate a mechanism that meets the minimum requirements, the connection is not established.

To Require SASL Encryption

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

To require SASL encryption, set the dsSaslMinSSF value to the minimum encryption required.

$ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=SASL, cn=security, cn=config
changetype: modify
replace: dsSaslMinSSF
dsSaslMinSSF: 128
^D

To Disallow SASL Encryption

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

To disallow SASL encryption, set both the dsSaslMinSSF and dsSaslMaxSSF values to zero.

$ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=SASL, cn=security, cn=config
changetype: modify
replace: dsSaslMinSSF
dsSaslMinSSF: 0

replace: dsSaslMaxSSF
dsSaslMaxSSF: 0
^D

SASL Authentication Through DIGEST-MD5

The DIGEST-MD5 mechanism authenticates clients by comparing a hashed value sent by the client with a hash of the user’s password. However, because the mechanism must read user passwords, all users that want to be authenticated through DIGEST-MD5 must have {CLEAR} passwords in the directory. When storing {CLEAR} passwords in the directory, you must ensure that access to password values is properly restricted through ACIs, as described in Chapter 6, Directory Server Access Control. In addition, you need to configure attribute encryption in the suffix, as described in Encrypting Attribute Values.

To Configure the DIGEST-MD5 Mechanism

The following procedure explains how to configure Directory Server to use DIGEST-MD5.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Use the ldapsearch command to verify that DIGEST-MD5 is a value of the supportedSASLMechanisms attribute on the root entry.

For example, the following command shows which SASL mechanisms are enabled:

$ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -s base -b "" "(objectclass=*)" supportedSASLMechanisms
Enter bind password:
dn:
supportedSASLMechanisms: EXTERNAL
supportedSASLMechanisms: DIGEST-MD5
supportedSASLMechanisms: GSSAPI
^D

If DIGEST-MD5 is not enabled, enable it.

$ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - 
Enter bind password:
dn: cn=SASL, cn=security, cn=config
changetype: modify
add: dsSaslPluginsEnable
dsSaslPluginsEnable: DIGEST-MD5
-
replace: dsSaslPluginsPath
dsSaslPluginsPath: SASL-library
^D

where SASL-library is one of the following:

JES installation: /usr/lib/mps/sasl2
Zip installation: install-path/dsee6/private/lib

Use the default identity mapping for DIGEST-MD5, or create new ones.

For information, see DIGEST-MD5 Identity Mappings.

Ensure that the password is stored in {CLEAR} for all users who will access the server through SSL using DIGEST-MD5.

See Chapter 7, Directory Server Password Policy for password storage schemes.

If you modified the SASL configuration entry or one of the DIGEST-MD5 identity mapping entries, restart Directory Server.

DIGEST-MD5 Identity Mappings

Identity mappings for SASL mechanisms try to match the credentials of the SASL identity with a user entry in the directory. Authentication fails if the mapping cannot find a DN that corresponds to the SASL identity. See Sun Java System Directory Server Enterprise Edition 6.2 Reference for a complete description of this mechanism.

The SASL identity is a string called the Principal that represents a user in a format specific to each mechanism. In DIGEST-MD5, clients should create a Principal that contains either a dn: prefix and an LDAP DN or a u: prefix followed by any text determined by the client. During the mapping, the Principal that is sent by the client is available in the ${Principal} placeholder.

The following entry in your server configuration is the default identity mapping for DIGEST-MD5:

dn: cn=default,cn=DIGEST-MD5,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
objectClass: dsPatternMatching
cn: default
dsMatching-pattern: \${Principal}
dsMatching-regexp: dn:(.*)
dsMappedDN: \$1

This identity mapping assumes that the dn field of the Principal contains the exact DN of an existing user in the directory.

To Define Your Own Identity Mappings for DIGEST-MD5

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Edit the default mapping entry or create new mapping entries under cn=DIGEST-MD5,cn=identity mapping,cn=config.

The following command shows how this mapping would be defined:

$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=unqualified-username,cn=DIGEST-MD5,cn=identity mapping
cn=config
objectclass: dsIdentityMapping
objectclass: dsPatternMatching
objectclass: nsContainer
objectclass: top
cn: unqualified-username
dsMatching-pattern: \${Principal}
dsMatching-regexp: u:(.*)@(.*)\\.com
dsSearchBaseDN: dc=\$2
dsSearchFilter: (uid=\$1)

Restart Directory Server for your new mappings to take effect.

SASL Authentication Through GSSAPI (Solaris OS Only)

The Generic Security Service API (GSSAPI) over SASL allows you to use a third-party security system such as Kerberos V5 to authenticate clients. The GSSAPI library is available only for the Solaris OS SPARC® platform. Sun recommends that you install the Kerberos V5 implementation on the Sun Enterprise Authentication Mechanism^TM 1.0.1 server.

The server uses the GSSAPI to validate the identity of the user. Then, the SASL mechanism applies the GSSAPI mapping rules to obtain a DN that is the bind DN for all operations during this connection.

To Configure the Kerberos System

Configure the Kerberos software according to the manufacturer’s instructions. If you are using the Sun Enterprise Authentication Mechanism 1.0.1 server, use this procedure.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Configure the files in /etc/krb5.

Create the Kerberos database for storing users and services.

In the database, create the Principal for the LDAP service.
$ ldap/server-FQDN@realm
where server-FQDN is the fully qualified domain name of your Directory Server.

Start the Kerberos daemon processes.

Note –
The DNS must be configured on the host machine.

Refer to your software documentation for detailed instructions for each of these steps. Also, see Example Configuration of Kerberos Authentication Using GSSAPI With SASL.

To Configure the GSSAPI Mechanism

The following procedure explains how to configure Directory Server to use GSSAPI on the Solaris OS:

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Create the default identity mapping for GSSAPI and any custom mappings as described in GSSAPI Identity Mappings.

Create a keytab to store the service keys.

Your LDAP service key is stored in the keytab.
1. Ensure that the keytab is only readable by the Directory Server user.
2. Change the file name to be different from the default /etc/krb5/krb5.keytab.
3. Set the environment variable KRB5_KTNAME to ensure that the new keytab is used rather than the default keytab.

If you modified the SASL configuration entry or one of the GSSAPI identity mapping entries, restart Directory Server.

Note that the DNS must be configured on the host machine.

GSSAPI Identity Mappings

Identity mappings for SASL mechanisms try to match credentials of the SASL identity with a user entry in the directory. Authentication fails if the mapping cannot find a DN that corresponds to the SASL identity.

The SASL identity is a string called the Principal that represents a user in a format specific to each mechanism. In Kerberos using GSSAPI, the Principal is an identity with the format uid [/instance][@ realm]. The uid can contain an optional instance identifier followed by an optional realm that is often a domain name. For example, the following strings are all valid user Principals:

bjensen
bjensen/Sales
bjensen@EXAMPLE.COM
bjensen/Sales@EXAMPLE.COM

Initially, no GSSAPI mappings are defined in the directory. Define a default mapping and any custom mappings that you need according to how your clients define the Principal that your clients use.

To Define Identity Mappings for GSSAPI

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Create new mapping entries under cn=GSSAPI,cn=identity mapping, cn=config.

See Sun Java System Directory Server Enterprise Edition 6.2 Reference for the definition of the attributes in an identity mapping entry. Examples of GSSAPI mappings are located in instance-path/ldif/identityMapping_Examples.ldif.

The default GSSAPI mapping in this file assumes that the Principal contains only a user ID. This mapping determines a user in a fixed branch of the directory:

dn: cn=default,cn=GSSAPI,cn=identity mapping,cn=config
objectclass: dsIdentityMapping
objectclass: nsContainer
objectclass: top
cn: default
dsMappedDN: uid=\${Principal},ou=people,dc=example,dc=com

Another example in this file shows how to determine the user ID when the user ID is contained in a Principal that includes a known realm.

dn: cn=same_realm,cn=GSSAPI,cn=identity mapping,cn=config
objectclass: dsIdentityMapping
objectclass: dsPatternMatching
objectclass: nsContainer
objectclass: top
cn: same_realm
dsMatching-pattern: \${Principal}
dsMatching-regexp: (.*)@EXAMPLE.COM
dsMappedDN: uid=\$1,ou=people,dc=EXAMPLE,dc=COM

Restart Directory Server for your new mappings to take effect.