test

Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

Chapter 5 Directory Server Security

Directory Server supports several mechanisms that provide secure and trusted communications over the network. LDAPS is the standard LDAP protocol that runs on top of the Secure Sockets Layer (SSL). LDAPS encrypts data and optionally uses certificates for authentication. When the term SSL is used in this chapter, it means the supported protocols SSL2, SSL3 and TLS 1.0.

Directory Server also supports the Start Transport Layer Security (Start TLS) extended operation to enable TLS on an LDAP connection that was originally not encrypted.

In addition, Directory Server supports the Generic Security Service API (GSSAPI) over the Simple Authentication and Security Layer (SASL). The GSSAPI allows you to use the Kerberos Version 5 security protocol on the Solaris Operating System. An identity mapping mechanism then associates the Kerberos principal with an identity in the directory.

For additional security information, see the NSS web site at http://www.mozilla.org/projects/security/pki/nss/.

This chapter provides procedures for configuring security through SSL. For information about ACIs, see Chapter 6, Directory Server Access Control. For information about user access and passwords, see Chapter 7, Directory Server Password Policy.

This chapter covers the following topics:

Using SSL With Directory Server

The Secure Sockets Layer (SSL) provides encrypted communications and optional authentication between a Directory Server and its clients. SSL can be used over LDAP or with DSML-over-HTTP. SSL is enabled by default over LDAP, but if you are using DSML-over-HTTP, you can easily enable SSL. In addition, replication can be configured to use SSL for secure communications between servers.

Using SSL with simple authentication (bind DN and password) encrypts all data sent to and from the server. Encryption guarantees confidentiality and data integrity. Optionally, clients can use a certificate to authenticate to Directory Server or to a third-party security mechanism through the Simple Authentication and Security Layer (SASL). Certificate-based authentication uses public-key cryptography to prevent forgery and impersonation of either the client or the server.

Directory Server is capable of simultaneous SSL and non-SSL communications on separate ports. For security reasons, you can also restrict all communications to the LDAP secure port. Client authentication is also configurable. You can set client authentication to required or to allowed. This setting determines the level of security you enforce.

SSL enables support for the Start TLS extended operation that provides security on a regular LDAP connection. Clients can bind to the standard LDAP port and then use the Transport Layer Security protocol to secure the connection. The Start TLS operation allows more flexibility for clients, and can help simplify port allocation.

The encryption mechanisms provided by SSL are also used for attribute encryption. Enabling SSL allows you to configure attribute encryption on your suffixes, which protects data while it is stored in the directory. For more information, see Encrypting Attribute Values.

For additional security, you can set access control to directory contents through access control instructions (ACIs). ACIs require a specific authentication method and ensure that data can only be transmitted over a secure channel. Set the ACIs to compliment your use of SSL and certificates. For more information, see Chapter 6, Directory Server Access Control.

SSL is enabled by default over LDAP, and you can easily enable SSL for DSML-over-HTTP. In addition, there are some aspects of the SSL configuration that you might want to modify, as described in the following sections.

Managing Certificates

This section describes how to manage SSL certificates in Directory Server.

To run SSL on Directory Server, you must either use a self-signed certificate or a Public Key Infrastructure (PKI) solution.

The PKI solution involves an external Certificate Authority (CA). For a PKI solution, you need a CA-signed server certificate, which contains both a public key and a private key. This certificate is specific to one Directory Server. You also need a trusted CA certificate, which contains a public key. The trusted CA certificate ensures that all server certificates from your CA are trusted. This certificate is sometimes called a CA root key or root certificate.

Note –

If you are using certificates for test purposes, you probably want to use self-signed certificates. However, in production, using self-signed certificates is not very secure. In production, use trusted Certificate Authority (CA) certificates.

The procedures in this section use the dsadm and dsconf commands. For information about these commands, see the dsadm(1M)and dsconf(1M) man pages.

This section provides the following information about configuring certificates on Directory Server:

ProcedureTo View the Default Self-Signed Certificate

When a Directory Server instance is first created, it contains a default self-signed certificate. A self-signed certificate is a public and private key pair, where the public key is signed by the private key. A self-signed certificate is valid for three months.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

    To view the default self-signed certificate, use this command:


    $ dsadm show-cert instance-path defaultCert

ProcedureTo Manage Self-Signed Certificates

When you create a Directory Server instance, a default self-signed certificate is automatically provided.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To create a self-signed certificate with non-default settings, use this command:


    $ dsadm add-selfsign-cert instance-path cert-alias

    Where cert-alias is a name that you provide to identify your certificate.

    To see all the options for this command, see the dsadm(1M) man page or the command-line help:.


    $ dsadm add-selfsign-cert --help

  2. When your self-signed certificate expires, renew the certificate:


    $ dsadm renew-selfsign-cert instance-path cert-alias

ProcedureTo Request a CA-Signed Server Certificate

This procedure explains how to request and install a CA-signed server certificate for use with Directory Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Generate a CA-signed server certificate request.


    $ dsadm request-cert [-W cert-pwd-file] {-S DN | --name name [--org org] [--org-unit org-unit \
  [--city city] [--state state] [--country country]} [-o output-file] [-F format] instance-path

    For example, to request a CA-signed server certificate for the Example company, use this command:


    $ dsadm request-cert --name host1 --org Example --org-unit Marketing \
 -o my_cert_request_file /local/ds

    In order to completely identify the server, Certificate Authorities might require all of the attributes that are shown in this example. For a description of each attribute, see the dsadm(1M) man page.

    When you request a certificate by using dsadm request-cert, the resulting certificate request is a binary certificate request unless you specify ASCII as output format. If you specify ASCII, the resulting certificate request is a PKCS #10 certificate request in PEM format. PEM is the Privacy Enhanced Mail format specified by RFCs 1421 through 1424 (http://www.ietf.org/rfc/rfc1421.txt) and is used to represent a base64-encoded certificate request in US-ASCII characters. The content of the request looks similar to the following example:


    -----BEGIN NEW CERTIFICATE REQUEST-----
MIIBrjCCARcCAQAwbjELMAkGA1UBhMCVXMxEzARBgNVBAgTCkNBElGT1JOSUExLD
AqBgVBAoTI25ldHNjYXBlIGNvb11bmljYXRpb25zIGNvcnBvcmF0aWuMRwwGgYDV
QQDExNtZWxsb24umV0c2NhcGUuY29tMIGfMA0GCSqGSIb3DQEBAUAA4GNADCBiQK
BgCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7u0EfgSLR0f+K41eNqqWRftGR83e
mqPLDOf0ZLTLjVGJaHJn4l1gG+JDf/n/zMyahxtV7+T8GOFFigFfuxJaxMjr2j7I
vELlxQ4IfZgwqCm4qQecv3G+N9YdbjveMVXW0v4XwIDAQABAAwDQYJKoZIhvcNAQ
EEBQADgYEAZyZAm8UmP9PQYwNy4Pmypk79t2nvzKbwKVb97G+MT/gw1pLRsuBoKi
nMfLgKp1Q38K5Py2VGW1E47/rhm3yVQrIiwV+Z8Lcc=
-----END NEW CERTIFICATE REQUEST-----

  2. Transmit the certificate request to your Certificate Authority, according to its procedures.

    The process for obtaining your Certificate Authority certificate depends on the certificate authority that you use. Some commercial CAs provide a website that allows you to automatically download the certificate. Other CAs will send it to you in email upon request.

    After you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, the CA might only take a day or two to respond to your request. If your selected CA is external to your company, the CA could take several weeks to respond to your request.

  3. Save the certificate that you receive from the Certificate Authority.

    Back up your certificates in a safe location. If you ever lose the certificates, you can reinstall them by using your backup file. You can save them in text files. The PKCS #11 certificate in PEM format looks similar to the following example:


    -----BEGIN CERTIFICATE-----
MIICjCCAZugAwIBAgICCEEwDQYJKoZIhKqvcNAQFBQAwfDELMAkGA1UEBhMCVVMx
IzAhBgNVBAoGlBhbG9a2FWaWxsZGwSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX
aWRnZXQgTW3FrZXJzICdSJyBVczEpMCcGAx1UEAxgVGVzdCBUXN0IFRlc3QgVGVz
dCBUZXN0IFlc3QgQ0EswHhcNOTgwMzEyMDIzMzUWhcNOTgwMzI2MDIzMpzU3WjBP
MQswCYDDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZN0b3J5VIFB1Ymxp
Y2F0aW9uczEWMB4QGA1UEAxMNZHVgh49dq2tLNvbjTBaMA0GCSqGSIb3DQEBAQUA
A0kAMEYkCQCksMR/aLGdfp4m0OiGgijG5KgOsyRNvwGYW7kfW+8mmijDtZaRjYNj
jcgpF3VnlbxbclX9LVjjNLC5737XZdAgEDozYwpNDARBglghkgBhvhCEAQEEBAMC
APAwHkwYDVR0jBBgwFAU67URjwCaGqZHUpSpdLxlzwJKiMwDQYJKoZIhQvcNAQEF
BQADgYEAJ+BfVem3vBOPBveNdLGfjlb9hucgmaMcQa9FA/db8qimKT/ue9UGOJqL
bwbMKBBopsDn56p2yV3PLIsBgrcuSoBCuFFnxBnqSiTS7YiYgCWqWaUA0ExJFmD6
6hBLseqkSWulk+hXHN7L/NrViO+7zNtKcaZLlFPf7d7j2MgX4Bo=
-----END CERTIFICATE-----

ProcedureTo Add the CA-Signed Server Certificate and the Trusted CA Certificate

This procedure explains how to install the CA-signed server certificate and trusted CA certificates for use with Directory Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Add the CA-signed server certificate.


    $ dsadm add-cert instance-path cert-alias cert-file

    Where cert-alias is a name that you provide to identify your certificate, and cert-file is the text file that contains the PKCS #11 certificate in PEM format.

    For example, to install a CA-signed server certificate, you might use a command similar to this:


    $ dsadm add-cert /local/ds server-cert /local/safeplace/serv-cert-file

    The certificate is now installed, but is not yet trusted. To trust the CA-signed server certificate, you must install the Certificate Authority certificate.

  2. Add the trusted Certificate Authority certificate.


    $ dsadm add-cert -C instance-path cert-alias cert-file

    The -C option indicates that the certificate is a trusted Certificate Authority certificate.

    For example, to install a trusted certificate from a Certificate Authority, you might use this command:


    $ dsadm add-cert -C /local/ds CA-cert /local/safeplace/ca-cert-file

  3. (Optional) Verify your installed certificates.

    • To list all server certificates and to display their validity dates and aliases, type:


      $ dsadm list-certs instance-path

      For example:


      $ dsadm list-certs /local/ds1
Enter the certificate database password:
Alias       Valid from Expires on Self-   Issued by          Issued to
                                  signed?                                     
----------- ---------- ---------- ------- -----------------  -----------------
serverCert  2000/11/10 2011/02/10 n       CN=CA-Signed Cert, CN=Test Cert,
            18:13      18:13              OU=CA,O=com        dc=example,dc=com
defaultCert 2006/05/18 2006/08/18 y       CN=host1,CN=DS,    Same as issuer
            16:28      16:28              dc=example,dc=com
2 certificates found

      By default, an instance of Directory Proxy Server contains a default server certificate called defaultCert. The text Same as issuer indicates that the default certificate is a self-signed server certificate.

    • To list trusted CA certificates, type:


      $ dsadm list-certs -C instance-path

      For example: 


      $ dsadm list-certs -C /local/ds1
Enter the certificate database password:
Alias   Valid from Expires on Self-   Issued by           Issued to
                              signed?                                     
------- ---------- ---------- ------- -----------------   -----------------
CA-cert 2000/11/10 2011/02/10 y       CN=Trusted CA Cert, Same as issuer
        18:12      18:12              OU=CA,O=com
1 certificate found

    • To view the details of a certificate, including the certificate expiration date, type:


      $ dsadm show-cert instance-path cert-alias

      For example, to view a server certificate, type:


      $ dsadm show-cert /local/ds1 "Server-Cert"
Enter the certificate database password:
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 2 (0x2)
        Signature Algorithm: PKCS #1 MD5 With RSA Encryption
        Issuer:
            "CN=Server-Cert,O=Sun,C=US"
        Validity:
            Not Before: Fri Nov 10 18:12:20 2000
            Not After : Thu Feb 10 18:12:20 2011
        Subject:
            "CN=CA Server Cert,OU=ICNC,O=Sun,C=FR"
        Subject Public Key Info:
            Public Key Algorithm: PKCS #1 RSA Encryption
            RSA Public Key:
                Modulus:
                    bd:76:fc:29:ca:06:45:df:cd:1b:f1:ce:bb:cc:3a:f7:
                    77:63:5a:82:69:56:5f:3d:3a:1c:02:98:72:44:36:e4:
                    68:8c:22:2b:f0:a2:cb:15:7a:c4:c6:44:0d:97:2d:13:
                    b7:e3:bf:4e:be:b5:6a:df:ce:c4:c3:a4:8a:1d:fa:cf:
                    99:dc:4a:17:61:e0:37:2b:7f:90:cb:31:02:97:e4:30:
                    93:5d:91:f7:ef:b0:5a:c7:d4:de:d8:0e:b8:06:06:23:
                    ed:5f:33:f3:f8:7e:09:c5:de:a5:32:2a:1b:6a:75:c5:
                    0b:e3:a5:f2:7a:df:3e:3d:93:bf:ca:1f:d9:8d:24:ed
                Exponent: 65537 (0x10001)
    Signature Algorithm: PKCS #1 MD5 With RSA Encryption
    Signature:
        85:92:42:1e:e3:04:4d:e5:a8:79:12:7d:72:c0:bf:45:
        ea:c8:f8:af:f5:95:f0:f5:83:23:15:0b:02:73:82:24:
        3d:de:1e:95:04:fb:b5:08:17:04:1c:9d:9c:9b:bd:c7:
        e6:57:6c:64:38:8b:df:a2:67:f0:39:f9:70:e9:07:1f:
        33:48:ea:2c:18:1d:f0:30:d8:ca:e1:29:ec:be:a3:43:
        6f:df:03:d5:43:94:8f:ec:ea:9a:02:82:99:5a:54:c9:
        e4:1f:8c:ae:e2:e8:3d:50:20:46:e2:c8:44:a6:32:4e:
        51:48:15:d6:44:8c:e6:d2:0d:5f:77:9b:62:80:1e:30
    Fingerprint (MD5):
        D9:FB:74:9F:C3:EC:5A:89:8F:2C:37:47:2F:1B:D8:8F
    Fingerprint (SHA1):
        2E:CA:B8:BE:B6:A0:8C:84:0D:62:57:85:C6:73:14:DE:67:4E:09:56

    Certificate Trust Flags:
        SSL Flags:
            Valid CA
            Trusted CA
            User
            Trusted Client CA
        Email Flags:
            User
        Object Signing Flags:
            User

ProcedureTo Renew an Expired CA-Signed Server Certificate

When your CA-signed server certificate (public key and private key) expires, renew it by using this procedure.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Obtain an updated CA-signed server certificate from your Certificate Authority.

  2. After you receive the updated certificate, install it.


    $ dsadm renew-cert instance-path cert-alias cert-file

ProcedureTo Export and Import a CA-Signed Server Certificate

In some cases you might want to export the public and private keys of a certificate so that you can later import the certificate. For example, you might want the certificate to be used by another server.

The commands in this procedure can be used with certificates that contain wild cards, for example "cn=*,o=example".

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Export the certificate.


    $ dsadm export-cert [-o output-file] instance-path cert-alias

    For example:


    $ dsadm export-cert -o /tmp/first-certificate /local/ds1 "First Certificate"
$ dsadm export-cert -o /tmp/first-ca-server-certificate /local/ds1/ defaultCert
Choose the PKCS#12 file password:
Confirm the PKCS#12 file password:
$ ls /tmp
first-ca-server-certificate

  2. Import the certificate.


    $ dsadm import-cert instance-path cert-file

    For example, to import the certificate to a server instance on host1:


    $ dsadm import-cert -h host1 /local/ds2 /tmp/first-ca-server-certificate
Enter the PKCS#12 file password:

  3. (Optional) If you have imported the certificate to a server, configure the server to use the imported certificate.


    $ dsconf set-server-prop -e -h host -p port -w - ssl-rsa-cert-name:server-cert

Configuring the Certificate Database Password

By default, Directory Server manages the SSL certificate database password internally through a stored password. When managing certificates, the user does not need to type a certificate password or specify the password file. This option is not very secure because the password is only hidden, not encrypted.

However, if you want to have more control over the use of certificates, you can configure the server so that the user is prompted for a password on the command line. In this case, the user must type the certificate database password for all dsadm subcommands except autostart, backup, disable-service, enable-service, info, reindex, restore, and stop. The certificate database is located in the directory instance-path/alias.

ProcedureTo Configure the Server So the User is Prompted for a Certificate Password

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Stop the server.


    $ dsadm stop instance-path

  2. Set the password prompt flag to on.


    $ dsadm set-flags instance-path cert-pwd-prompt=on

    You are asked to choose a new certificate password.

  3. Start the server.


    $ dsadm start instance-path

Backing Up and Restoring the Certificate Database for Directory Server

When you back up an instance of Directory Server, you back up the Directory Server configuration and the certificates. The backed up certificates are stored in the archive-path/alias directory.

For information about how to back up and restore Directory Server, see To Make a Backup for Disaster Recovery.

Configuring SSL Communication

This section contains procedures related to disabling and enabling SSL.

Disabling Non Secure Communication

When a server instance is created, both an LDAP clear port and a secure LDAP port (LDAPS) are created by default. However, there might be situations where you want to disable non-SSL communications so that the server communicates only through SSL.

The SSL connection is enabled with a default self-signed certificate. If you want to, you can install your own certificates. For instructions on managing certificates and disabling SSL after the server has been started, see Chapter 5, Directory Server Security. For an overview of certificates, certificate databases, and obtaining a CA-signed server certificate, see Sun Java System Directory Server Enterprise Edition 6.0 Reference.

ProcedureTo Disable the LDAP Clear Port

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Disable the LDAP clear port.

    To disable the non secure point, you must bind to the LDAP secure port. This example shows a bind to the default LDAP secure port, 1636, on the host server host1.


    $ dsconf set-server-prop -h host1 -p 1636 ldap-port:disabled

  2. Restart the server for the change to take effect.


    $ dsadm restart /local/ds

    You can now no longer bind on the non secure port 1389.

Choosing Encryption Ciphers

A cipher is the algorithm used to encrypt and decrypt data. Generally speaking, the more bits that a cipher uses during encryption, the stronger or more secure the encryption is. Ciphers for SSL are also identified by the type of message authentication used. Message authentication is another algorithm that computes a checksum that guarantees data integrity.

When a client initiates an SSL connection with a server, the client and server must agree on a cipher to use to encrypt information. In any two-way encryption process, both parties must use the same cipher. The cipher used depends upon the current order of the cipher list kept by the server. The server chooses the first cipher presented by the client that matches a cipher in its list. The default cipher value for Directory Server is all, which means all known secure ciphers supported by the underlying SSL library. However, you can modify this value to only accept certain ciphers.

For more information about the ciphers that are available with Directory Server, see Sun Java System Directory Server Enterprise Edition 6.0 Reference.

ProcedureTo Choose an Encryption Cipher

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Make sure that SSL is enabled for your server.

    See Configuring SSL Communication.

  2. View the available SSL ciphers.


    $ dsconf get-server-prop -h host -p port ssl-supported-ciphers
ssl-supported-ciphers  :  TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
ssl-supported-ciphers  :  TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
ssl-supported-ciphers  :  TLS_DHE_RSA_WITH_AES_256_CBC_SHA
ssl-supported-ciphers  :  TLS_DHE_DSS_WITH_AES_256_CBC_SHA 
...

  3. (Optional) If you want to keep a copy of non-encrypted data, export the data before setting the SSL ciphers.

    See Exporting to LDIF.

  4. Set the SSL ciphers.


    $ dsconf set-server-prop -h host -p port ssl-cipher-family:cipher

    For example, to set the cipher family to SSL_RSA_WITH_RC4_128_MD5 and SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, type:


    $ dsconf set-server-prop -h host1 -p 1636 ssl-cipher-family:SSL_RSA_WITH_RC4_128_MD5 \
 ssl-cipher-family:SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
Enter "cn=Directory Manager" password:  
Before setting SSL configuration, export Directory Server data. 
Do you want to continue [y/n] ? y
Directory Server must be restarted for changes to take effect.

  5. Restart the server for the changes to take effect.


    $ dsadm restart /local/ds

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.

Configuring LDAP Clients to Use Security

The following sections explain how to configure and use SSL in LDAP clients that want to establish secure connections with the Directory Server. In an SSL connection, the server sends its certificate to the client. The client must first authenticate the server by trusting its certificate. Then, the client can optionally initiate one of the client authentication mechanisms by sending its own certificate or information for one of the two SASL mechanism. The SASL mechanisms are DIGEST-MD5 and GSSAPI using Kerberos V5.

The following sections use the ldapsearch tool as an example of an SSL-enabled LDAP client. The ldapmodify, ldapdelete, and ldapcompare tools provided with Directory Server are configured in the same way. These directory access tools are based on the Directory SDK for C and are further documented in Sun Java System Directory Server Enterprise Edition 6.0 Reference.

To configure SSL connections on other LDAP clients, refer to the documentation provided with your application.

Note –

Some client applications implement SSL but do not verify that the server has a trusted certificate. These client applications use the SSL protocol to provide data encryption but cannot guarantee confidentiality nor protect against impersonation.

The following sections explain how to configure LDAP clients to use security:

Using SASL DIGEST-MD5 in Clients

When using the DIGEST-MD5 mechanism in clients, you do not need to install a user certificate. However, if you want to use encrypted SSL connections, you must still trust the server certificate as described in Managing Certificates.

Specifying a Realm

A realm defines the namespace from which the authentication identity is selected. In DIGEST-MD5 authentication, you must authenticate to a specific realm.

Directory Server uses the fully qualified host name of the machine as the default realm for DIGEST-MD5. The server uses the lowercase value of the host name that is found in the nsslapd-localhost configuration attribute.

If you do not specify a realm, the default realm offered by the server is used.

Specifying Environment Variables

In the UNIX environment, you must set the SASL-PATH environment variable so that the LDAP tools can find the DIGEST-MD5 libraries. The DIGEST-MD5 library is a shared library that is dynamically loaded by the SASL plug-in. Set the SASL_PATH environment variable as follows:


export SASL_PATH=SASL-library

This path assumes that Directory Server is installed on the same host where the LDAP tools are invoked.

Examples of the ldapsearch Command

You can perform DIGEST-MD5 client authentication without using SSL. The following example uses the default DIGEST-MD5 identity mapping to determine the bind DN:


$ ldapsearch -h host1 -p 1389 \
 -o mech=DIGEST-MD5 [ \
 -o realm="example.com"] \
 -o authid="dn:uid=bjensen,dc=example,dc=com" \
 -w - \
 -o authzid="dn:uid=bjensen,dc=example,dc=com" \
 -o secProp="minssf=56,maxssf=256,noplain" \
 -b "dc=example,dc=com" "(givenname=Richard)"

The preceding example shows the use of the -o (lowercase letter o) option to specify SASL options. The realm is optional, but if specified, it must be the fully qualified domain name of the server host machine. The authid and authzid must both be present and identical, although the authzid intended for proxy operations is not used. The -w password option applies to the authid.

The value of authid is the Principal used in identity mapping. The authid should contain either the dn: prefix followed by a valid user DN in the directory, or the u: prefix followed by any string determined by the client. This use of authid allows you to use the mappings that are shown in DIGEST-MD5 Identity Mappings.

The most common configuration is for an SSL connection to provide encryption over the LDAPS secure port and DIGEST-MD5 to provide the client authentication. The following example performs the same operation over SSL:


$ ldapsearch -h host1 -p 1636 \
 -Z -P .mozilla/bjensen/BJE6001.slt/cert8.db \
 -N "cert-example" -w - \
 -o mech=DIGEST-MD5 [-o realm="example.com"] \
 -o authid="dn:uid=bjensen,dc=example,dc=com" \
 -o authzid="dn:uid=bjensen,dc=example,dc=com" \
 -o secProp="minssf=0,maxssf=0,noplain" \
 -b "dc=example,dc=com" "(givenname=Richard)"

In this example, the -N and -w options are required by the ldapsearch command, as the operation is performed over SSL. However , these options are not used for client authentication. Instead, the server performs another DIGEST-MD5 identity mapping of the Principal in the authid value.

Using Kerberos SASL GSSAPI in Clients

When using the GSSAPI mechanism in clients, you do not need to install a user certificate, but you must configure the Kerberos V5 security system. Also, if you want to use encrypted SSL connections, you must trust the server certificate as described in Managing Certificates.

ProcedureTo Configure Kerberos V5 on a Host

You must configure Kerberos V5 on the host machine where your LDAP clients will run.

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

  1. Install Kerberos V5 according to its installation instructions.

    Sun recommends installing the Sun Enterprise Authentication Mechanism 1.0.1 client software.

  2. Configure the Kerberos software.

    Using the Sun Enterprise Authentication Mechanism software, configure the files under /etc/krb5. This configuration sets up the kdc server, and defines the default realm and any other configuration required by your Kerberos system.

  3. If necessary, modify the file /etc/gss/mech so that the first value that is listed is kerberos_v5 .

ProcedureTo Specify SASL Options for Kerberos Authentication

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

  1. Before using a client application that is enabled with the GSSAPI mechanism, initialize the Kerberos security system with your user Principal.


    $ kinit user-principal

    where the user-principal is your SASL identity, for example, bjensen@example.com.

  2. Specify SASL options for using Kerberos.

    Note that in the UNIX environment, you must set the SASL_PATH environment variable to the correct path for the SASL libraries. For example in the Korn shell:


    $ export SASL_PATH=SASL-library

    This path assumes that Directory Server is installed on the same host where the LDAP tools are invoked.

    The following example of the ldapsearch tool shows the use of the -o (lowercase letter o) option to specify SASL options for using Kerberos:


    $ ldapsearch -h www.host1.com -p 1389 -o mech=GSSAPI -o authid="bjensen@EXAMPLE.COM" \
 -o authzid="bjensen@EXAMPLE.COM" -b "dc=example,dc=com" "(givenname=Richard)"

    The authid can be omitted because it is present in the Kerberos cache that was initialized by the kinit command. If authid is present, authid and authzid must be identical, although the authzid intended for proxy operations is not used. The value of authid is the Principal that is used in identity mapping. The Principal must be the full Principal, including the realm. See GSSAPI Identity Mappings.

Example Configuration of Kerberos Authentication Using GSSAPI With SASL

Configuring Kerberos for Directory Server can be complicated. Your first point of reference should be the Kerberos documentation.

For more help, use the following example procedure to get an idea of which steps to follow. Be aware, however, that this procedure is an example. You must modify the procedure to suit your own configuration and your own environment.

Additional information about configuring and using Kerberos in the Solaris OS can be found in System Administration Guide: Security Services. This guide is a part of the Solaris documentation set. You can also consult the man pages.

    Information about this example and the steps used are as follows:

  1. Assumptions for This Example

  2. All Machines: Edit the Kerberos Client Configuration File

  3. All Machines: Edit the Administration Server ACL Configuration File

  4. KDC Machine: Edit the KDC Server Configuration File

  5. KDC Machine: Create the KDC Database

  6. KDC Machine: Create an Administration Principal and Keytab

  7. KDC Machine: Start the Kerberos Daemons

  8. KDC Machine: Add Host Principals for the KDC and Directory Server Machines

  9. KDC Machine: Add an LDAP Principal for the Directory Server

  10. KDC Machine: Add a Test User to the KDC

  11. Directory Server Machine: Install the Directory Server

  12. Directory Server Machine: Configure the Directory Server to Enable GSSAPI

  13. Directory Server Machine: Create a Directory Server Keytab

  14. Directory Server Machine: Add a Test User to the Directory Server

  15. Directory Server Machine: Get a Kerberos Ticket as the Test User

  16. Client Machine: Authenticate to the Directory Server Through GSSAPI

Assumptions for This Example

This example procedure describes the process of configuring one machine to operate as a Key Distribution Center (KDC), and a second machine to run a Directory Server. The result of this procedure is that users can perform Kerberos authentication through GSSAPI.

It is possible to run both the KDC and the Directory Server on the same machine. If you choose to run both on the same machine, use the same procedure, but omit the steps for the Directory Server machine that have already been done for the KDC machine.

This procedure makes a number of assumptions about the environment that is used. When using the example procedure, modify the values accordingly to suit your environment. These assumptions are:

All Machines: Edit the Kerberos Client Configuration File

The /etc/krb5/krb5.conf configuration file provides information that Kerberos clients require in order to communicate with the KDC.

Edit the /etc/krb5/krb5.conf configuration file on the KDC machine, the Directory Server machine, and any client machines that will authenticate to the Directory Server using Kerberos.

The updated /etc/krb5/krb5.conf configuration file should look like the contents of the following example.

Example 5–1 Edited Kerberos Client Configuration File /etc/krb5/krb5.conf 


#pragma ident   "@(#)krb5.conf  1.2     99/07/20 SMI"
# Copyright (c) 1999, by Sun Microsystems, Inc.
# All rights reserved.
#
# krb5.conf template
# In order to complete this configuration file
# you will need to replace the __<name\>__ placeholders
# with appropriate values for your network.
#

[libdefaults]
        default_realm = EXAMPLE.COM
[realms]
        EXAMPLE.COM = {
                kdc = kdc.example.com
                admin_server = kdc.example.com
        }
[domain_realm]
        .example.com = EXAMPLE.COM
[logging]
        default = FILE:/var/krb5/kdc.log
        kdc = FILE:/var/krb5/kdc.log
        kdc_rotate = {

# How often to rotate kdc.log. Logs will get rotated no more
# often than the period, and less often if the KDC is not used
# frequently.
                period = 1d

# how many versions of kdc.log to keep around (kdc.log.0, kdc.log.1, ...)
                versions = 10
        }

[appdefaults]
        kinit = {
                renewable = true
                forwardable= true
        }
        gkadmin = {
                help_url =
 http://docs.sun.com:80/ab2/coll.384.1/SEAM/@AB2PageView/1195
        }

All Machines: Edit the Administration Server ACL Configuration File

Replace "___default_realm___" with "EXAMPLE.COM" in the /etc/krb5/kadm5.acl configuration file. The updated file should look like the following example.

Example 5–2 Edited Administration Server ACL Configuration File


#
# Copyright (c) 1998-2000 by Sun Microsystems, Inc.
# All rights reserved.
#
# pragma ident   "@(#)kadm5.acl  1.1     01/03/19 SMI"
*/admin@EXAMPLE.COM *

KDC Machine: Edit the KDC Server Configuration File

Edit the /etc/krb5/kdc.conf file to replace "___default_realm___" with "EXAMPLE.COM". The updated file should look like the following example.

Example 5–3 Edited KDC Server Configuration File /etc/krb5/kdc.conf 


# Copyright 1998-2002 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#ident  "@(#)kdc.conf   1.2     02/02/14 SMI"

[kdcdefaults]
        kdc_ports = 88,750

[realms]
        EXAMPLE.COM = {
                profile = /etc/krb5/krb5.conf
                database_name = /var/krb5/principal
                admin_keytab = /etc/krb5/kadm5.keytab
                acl_file = /etc/krb5/kadm5.acl
                kadmind_port = 749
                max_life = 8h 0m 0s
                max_renewable_life = 7d 0h 0m 0s
                default_principal_flags = +preauth
        }

KDC Machine: Create the KDC Database


$ /usr/sbin/kdb5_util create -r EXAMPLE.COM -s
Initializing database ’/var/krb5/principal’ for realm ’EXAMPLE.COM’,
master key name ’K/M@EXAMPLE.COM’
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: password
Re-enter KDC database master key to verify: password
$

KDC Machine: Create an Administration Principal and Keytab

Use the following command to create an administration user with a Principal of kws/admin@EXAMPLE.COM and service keys that will be used by the administration daemon.


$ /usr/sbin/kadmin.local
kadmin.local:  add_principal kws/admin
Enter password for principal "kws/admin@EXAMPLE.COM": secret
Re-enter password for principal "kws/admin@EXAMPLE.COM": secret
Principal "kws/admin@EXAMPLE.COM" created.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab kadmin/kdc.example.com
Entry for principal kadmin/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab changepw/kdc.example.com

Entry for principal changepw/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab kadmin/changepw
Entry for principal kadmin/changepw with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  quit$

KDC Machine: Start the Kerberos Daemons

Run the following commands to start the KDC and administration daemons:


$ /etc/init.d/kdc start
$ /etc/init.d/kdc.master start
$

The KDC process will appear in the process list as /usr/lib/krb5/krb5kdc. The administration daemon will appear as /usr/lib/krb5/kadmind.

Note than in the Solaris 10 OS, the daemons are managed by the Service Management Facility (SMF) framework. Start the daemons on the Solaris 10 OS:


$ svcadm disable network/security/krb5kdc
$ svcadm enable network/security/krb5kdc
$ svcadm disable network/security/kadmin
$ svcadm enable network/security/kadmin
$

KDC Machine: Add Host Principals for the KDC and Directory Server Machines

Use the following sequence of commands to add host Principals to the Kerberos database for the KDC and Directory Server machines. The host Principal is used by certain Kerberos utilities such as klist.


$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  add_principal -randkey host/kdc.example.com
Principal "host/kdc.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/kdc.example.com
Entry for principal host/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin:  add_principal -randkey host/directory.example.com
Principal "host/directory.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/directory.example.com
Entry for principal host/directory.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin:  quit
$

KDC Machine: Add an LDAP Principal for the Directory Server

For the Directory Server to be able to validate the Kerberos tickets that are held by authenticating users, the Directory Server must have its own Principal. Currently, the Directory Server is hard coded to require a Principal of ldap/fqdn@realm where fqdn is the fully-qualified domain name of the Directory Server and realm is the Kerberos realm. The fqdn must match the fully qualified name provided when installing the Directory Server. In this case, the Principal for the Directory Server would be ldap/directory.example.com@EXAMPLE.COM.

Use the following sequence of commands to create an LDAP Principal for the Directory Server:


$ /usr/sbin/kadmin -p kws/admin 
Enter Password: secret 
kadmin: add_principal -randkey ldap/directory.example.com 
Principal "ldap/directory.example.com@EXAMPLE.COM" created. 
kadmin: quit 
$

KDC Machine: Add a Test User to the KDC

To perform Kerberos authentication, the user authenticating must exist in the Kerberos database. In this example, the user has the user name kerberos-test, which means that the Kerberos Principal is kerberos-test@EXAMPLE.COM.

Create the user by using the command sequence in this example:


$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  add_principal kerberos-test
Enter password for principal "kerberos-test@EXAMPLE.COM": secret

Re-enter password for principal "kerberos-test@EXAMPLE.COM": secret

Principal "kerberos-test@EXAMPLE.COM" created.
kadmin:  quit
$

Directory Server Machine: Install the Directory Server

Install Directory Server 6.0 and the latest patches. Following are example settings.

Variable Type 

Example Value 

Fully qualified computer name 

directory.example.com

Installation directory 

/opt/SUNWdsee

Instance path 

/local/ds

Server user 

unixuser

Server group 

unixgroup

Server identifier 

directory

Server port 

389

Suffix 

dc=example,dc=com

Administrator ID 

admin

Administration domain 

example.com

Directory Administrator DN 

cn=admin,cn=Administrators,cn=config

Administration port 

390

Directory Server Machine: Configure the Directory Server to Enable GSSAPI

First, create the file /data/ds/shared/bin/gssapi.ldif to define the mapping that should be used by the Directory Server, and to identify which Kerberos user is authenticating, based on the Principal. Create the file contents to be the same as what is shown in the following example.

Example 5–4 gssapi.ldif File Contents


dn: cn=GSSAPI,cn=identity mapping,cn=config
changetype: add
objectClass: top
objectClass: nsContainer
cn: GSSAPI
dn: cn=default,cn=GSSAPI,cn=identity mapping,cn=config
changetype: add
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
objectClass: dsPatternMatching
cn: default
dsMatching-pattern: \${Principal}
dsMatching-regexp: (.*)@EXAMPLE.COM
dsMappedDN: uid=\$1,ou=People,dc=example,dc=com

dn: cn=SASL,cn=security,cn=config
changetype: modify
replace: dsSaslPluginsPath
dsSaslPluginsPath: /usr/lib/mps/sasl2/libsasl.so

Next, use the ldapmodify command to update the Directory Server to enable GSSAPI with the appropriate mappings, as shown in the following example:


$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -a -f /data/ds/shared/bin/gssapi.ldif
adding new entry cn=GSSAPI,cn=identity mapping,cn=config
adding new entry cn=default,cn=GSSAPI,cn=identity mapping,cn=config
modifying entry cn=SASL,cn=security,cn=config
$

Directory Server Machine: Create a Directory Server Keytab

As mentioned previously, to authenticate Kerberos users through GSSAPI, the Directory Server must have its own Principal in the KDC. For authentication to work properly, the Principal information must reside in a Kerberos keytab on the Directory Server machine. This information must be in a file that is readable by the user account under which the Directory Server operates.

Create a keytab file with the correct properties by using the following command sequence:


$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  ktadd -k //local/ds/config/ldap.keytab ldap/directory.example.com
Entry for principal ldap/directory.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab
 WRFILE:/local/ds/config/ldap.keytab.
kadmin:  quit
$

Change the permissions and ownership on this custom keytab. Make the keytab owned by the user account used to run Directory Server and readable only by that user:


$ chown unixuser:unixgroup /local/ds/config /ldap.keytab
$ chmod 600 /local/ds/config/ldap.keytab
$

By default, the Directory Server tries to use the standard Kerberos keytab in the file /etc/kerb5/krb5.keytab. However, making this file readable by the Directory Server user could constitute a security risk, which is why a custom keytab was created for the Directory Server.

Configure the Directory Server to use the new custom keytab. Do this by setting the KRB5_KTNAME environment variable.

Finally, restart the Directory Server to allow these changes to take effect:


$ KRB5_KTNAME=/etc/krb5/ldap.keytab dsadm restart /local/ds

Directory Server Machine: Add a Test User to the Directory Server

To authenticate a Kerberos user to the Directory Server, there must be a directory entry for the user that corresponds to the Kerberos Principal for that user.

In a previous step, a test user was added to the Kerberos database with a Principal of kerberos-test@EXAMPLE.COM. Because of the identity mapping configuration added to the directory, the corresponding directory entry for that user must have a DN of uid=kerberos-test,ou=People,dc=example,dc=com.

Before you can add the user to the directory, you must create the file testuser.ldif with the following contents.

Example 5–5 New testuser.ldif File


dn: uid=kerberos-test,ou=People,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: kerberos-test
givenName: Kerberos
sn: Test
cn: Kerberos Test
description: An account for testing Kerberos authentication through GSSAPI

Next, use ldapmodify to add this entry to the server:


$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -f testuser.ldif
adding new entry uid=kerberos-test,ou=People,dc=example,dc=com
$

Directory Server Machine: Get a Kerberos Ticket as the Test User

The test user exists in the Kerberos database and Directory Server and the KDC. Therefore, it is now possible to authenticate as the test user to the Directory Server over Kerberos through GSSAPI.

First, use the kinit command to get a Kerberos ticket for the user, as shown in the following example:


$ kinit kerberos-test
Password for kerberos-test@EXAMPLE.COM: secret
$

Then, use the klist command to view information about this ticket:


$ klist
Ticket cache: /tmp/krb5cc_0
Default principal: kerberos-test@EXAMPLE.COM

Valid starting            Expires                   Service principal
Sat Jul 24 00:24:15 2004  Sat Jul 24 08:24:15 2004  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        renew until Sat Jul 31 00:24:15 2004
$

Client Machine: Authenticate to the Directory Server Through GSSAPI

The final step is to authenticate to the Directory Server by using GSSAPI. The ldapsearch utility provided with the Directory Server provides support for SASL authentication, including GSSAPI, DIGEST-MD5, and EXTERNAL mechanisms. However, to bind by using GSSAPI you must provide the client with the path to the SASL library. Provide the path by setting the SASL_PATH environment variable to the lib/sasl directory:


$ SASL_PATH=SASL-library
$ export SASL_PATH
$

To actually perform a Kerberos-based authentication to the Directory Server using ldapsearch, you must include the -o mech=GSSAPI and -o authzid=principal arguments.

You must also specify the fully qualified host name, shown here as -h directory.example.com, which must match the value of the nsslapd-localhost attribute on cn=config for the server. This use of the -h option is needed because the GSSAPI authentication process requires the host name provided by the client to match the host name provided by the server.

The following example retrieves the dc=example,dc=com entry while authenticated as the Kerberos test user account created previously:


$ ldapsearch -h directory.example.com -p 389 -o mech=GSSAPI \
 -o authzid="kerberos-test@EXAMPLE.COM" -b "dc=example,dc=com" -s base "(objectClass=*)"
version: 1
dn: dc=example,dc=com
dc: example
objectClass: top
objectClass: domain
$

Check the Directory Server access log to confirm that the authentication was processed as expected:


$ tail -12 /local/ds/logs/access

[24/Jul/2004:00:30:47 -0500] conn=0 op=-1 msgId=-1 - fd=23 slot=23 LDAP 
		connection from 1.1.1.8 to 1.1.1.8
[24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - RESULT err=14 tag=97 
     nentries=0 etime=0, SASL bind in progress
[24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - RESULT err=14 tag=97 
     nentries=0 etime=0, SASL bind in progress
[24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - RESULT err=0 tag=97 
     nentries=0 etime=0 dn="uid=kerberos-test,ou=people,dc=example,dc=com"
[24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - SRCH base="dc=example,dc=com"
     scope=0 filter="(objectClass=*)" attrs=ALL
[24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - RESULT err=0 tag=101 nentries=1 
     etime=0
[24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=5 - UNBIND
[24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=-1 - closing - U1
[24/Jul/2004:00:30:48 -0500] conn=0 op=-1 msgId=-1 - closed.
$

This example shows that the bind is a three-step process. The first two steps return LDAP result 14 (SASL bind in progress), and the third step shows that the bind was successful. The method=sasl and mech=GSSAPI tags show that the bind used the GSSAPI SASL mechanism. The dn="uid=kerberos-test,ou=people,dc=example,dc=com" at the end of the successful bind response shows that the bind was performed as the appropriate user.

Pass-Through Authentication

Pass-through authentication (PTA) is a mechanism by which bind requests are filtered by bind DN. One Directory Server (the delegator) receives the bind request and, based on the filter, can consult another Directory Server (the delegate) to authenticate bind requests. As part of this functionality, the PTA plug-in enables the delegator Directory Server to accept simple password-based bind operations for entries that are not necessarily stored in its local database.

The PTA plug-in is also used by DSCC for private communication with the server. When a server instance is registered in DSCC, the PTA plug-in is enabled and the DSCC URL is added as an argument.


$ dsconf get-plugin-prop -h host -p port "Pass Through Authentication" enabled argument
argument  :  ldap://DSCC_URL:DSCC_PORT/cn=dscc
enabled   :  on
Note –

If possible, avoid modifying the PTA plug-in for your own use. Modifications to the PTA plug-in can cause access problems for DSCC.

If you cannot avoid modifying the PTA plug-in, you must do the following:

If the PTA plug-in is disabled or the DSCC URL is removed from the argument, the server instance will appear as inaccessible in DSCC. If this happens, DSCC will automatically give you the option of resetting the PTA plug-in.