test

Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

Configuring Client Authentication

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:

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.

ProcedureTo 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

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

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

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

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

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

    For information, see DIGEST-MD5 Identity Mappings.

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

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

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

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

    An example mapping for DIGEST-MD5 is located in instance-path/ldif/identityMapping_Examples.ldif.

    This example assumes that the unqualified text field of the Principal contains the user name of the desired identity. The following command shows how this mapping would be defined:


    $ ldapmodify -a -h host1 -p 1636 -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)

  2. Restart Directory Server for your new mappings to take effect.

SASL Authentication Through GSSAPI (SPARC 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 MechanismTM 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.

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

  1. Configure the files in /etc/krb5.

  2. Create the Kerberos database for storing users and services.

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

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

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

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

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

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

ProcedureTo Define Identity Mappings for GSSAPI

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

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

    See Sun Java System Directory Server Enterprise Edition 6.0 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

  2. Restart Directory Server for your new mappings to take effect.