Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Guide 

Chapter 11
Managing Authentication and Encryption

Directory Server supports several mechanisms to provide secure and trusted communications over the network. LDAPS is the standard LDAP protocol that runs on top of the Secure Sockets Layer (SSL) to encrypt data and optionally use certificates for authentication.

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 Services API (GSSAPI) over the Simple Authentication and Security Layer (SASL). This 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, refer to the NSS website at:

http://www.mozilla.org/projects/security/pki/nss/

This chapter contains the following sections:


Introduction to SSL in Directory Server

The Secure Sockets Layer (SSL) provides encrypted communications and optional authentication between a Directory Server and its clients. SSL may be enabled for both the LDAP and DSML-over-HTTP protocols to provide security for any connection to the server. In addition, the replication and chaining suffix mechanisms may be configured to use SSL for secure communications between servers.

Using SSL with simple authentication (bind DN and password) will encrypt all data sent to and from the server to guarantee confidentiality and data integrity. Optionally, clients may use a certificate to authenticate to Directory Server or 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 client or server.

Directory Server is capable of simultaneous SSL and non-SSL communications on separate ports. For security reasons, you may also restrict all communications to the secure port. Client authentication is also configurable and may be either required or simply allowed to determine the level of security you enforce.

Enabling SSL also enables support for the Start TLS extended operation that provides security on a regular LDAP connection. Clients may bind to the non-SSL port and then use the Transport Layer Security protocol to initiate an SSL connection. The Start TLS operation allows more flexibility for clients and may help simplify port allocation.

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

For additional security, access control to directory contents may be configured according to the client's use of SSL and certificates. You may define access control instructions (ACIs) which require a specific authentication method, and will thus ensure that data can only be transmitted over a secure channel. For more information, see Bind Rules.

For a complete description of SSL, internet security, and certificates, including how to configure SSL in your Administration Server as well, see the Administration Server Administration Guide.


Summary of Steps for Enabling SSL

Each of the following steps are covered in the subsequent sections of this chapter:

  1. Obtain and install a certificate for your Directory Server, and configure Directory Server to trust the certification authority's certificate. This procedure includes:
    1. Creating a certificate database if necessary.
    2. Generating and sending a certificate request from your server to your Certificate Authority who will provide your server certificate.
    3. Installing your new certificate in the server.
    4. Trusting your Certificate Authority and all certificates it issues.
  2. Activate and configure SSL in your directory, including the secure ports for LDAP and DSML operations. You may also configure Directory Server Console to access the server using SSL.
  3. Optionally, configure the server for one or more of the following client authentication mechanisms:
    1. The default certificate-based authentication.
    2. The DIGEST_MD5 authentication mechanism over SASL.
    3. The GSSAPI authentication over SASL that allows use of the Kerberos V5 security mechanism.

Once you have finished these steps, configure your clients to use SSL when communicating with Directory Server, including any of the optional authentication mechanisms you wish to use. Refer to tools such as ldapsearch and ldapmodify.

Some of the steps above may also be performed with the certutil tool to manage certificates through the command line. This tool is provided in the SUNWtlsu package.


Obtaining and Installing Server Certificates

This section describes the process of creating a certificate database, obtaining and installing a certificate for use with Directory Server, and configuring Directory Server to trust the Certificate Authority's (CA) certificate.

Creating a Certificate Database

The first time you configure SSL on your server, you must set the password for your security device. If you are not using an external hardware security device, the internal security device is a certificate and key database stored in the following files:

ServerRoot/alias/slapd-serverID-cert8.db
ServerRoot/alias/slapd-serverID-key3.db

If your serverID contains upper-case letters, you must use the command-line procedure below to create your certificate database.

Using the Console

When using the console, the server will create the certificate database files automatically the first time you invoke the certificate manager dialog:

  1. On the top-level Tasks tab of Directory Server Console, click the Manage Certificates button. Alternatively, with the Tasks tab showing, select the Manage Certificates item from the Console>Security menu.
  2. The server will automatically create a certificate and key database, and you will be asked to set its password for the security device. This password protects the private keys of the certificates stored in your server. Enter the password twice to confirm it, then click OK.

Using the Command Line

When creating the certificate database files from the command line, you must use the path and file name prefixes shown in the following procedure so that the server can find them.

  1. On the server host machine, create a certificate database with the following command:
  2. certutil -N -d ServerRoot/alias -P slapd-LCserverID-

    where LCserverID is your server name in all lower-case letters.

    The tool will prompt you for a password to protect the keys of the certificates.

Generating a Certificate Request

Use one of the following procedures to generate 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 used to represent a base64-encoded certificate request in US-ASCII characters. The content of the request will look 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-----

Using the Console

  1. On the top-level Tasks tab of Directory Server Console, click the Manage Certificates button. Alternatively, with the Tasks tab showing, select the Manage Certificates item from the Console>Security menu.
  2. The Manage Certificates dialog is displayed.

  3. Select the Server Certs tab, and click the Request button.
  4. The Certificate Request Wizard is displayed.

  5. If you have installed a plug-in allowing the server to communicate directly with the CA, you may select it now. Otherwise, you must request a certificate manually by transmitting the generated request via email or a website. Click Next to continue.
  6. Enter the Requestor Information in the blank text fields:
  7. Server Name. Enter the fully qualified hostname of the Directory Server as it is used in DNS lookups, for example, east.example.com.

    Organization. Enter the legal name of your company or institution. Most CAs require you to verify this information with legal documents such as a copy of a business license.

    Organizational Unit. (Optional). Enter a descriptive name for your division or business unit within your company.

    Locality. (Optional). Enter your company's city name.

    State or Province. Enter the full name of your company's state or province, with no abbreviations.

    Country. Select the two-character abbreviation for your country's name in ISO format. The country code for the United States is US. The Directory Server Administration Reference contains a list of ISO Country Codes.

    Click Next to continue.

  8. Enter the password of your security device, then click Next. This is the password set in Creating a Certificate Database.
  9. Select Copy to Clipboard or Save to File to save the certificate request information that you must send to the Certificate Authority.
  10. Click Done to dismiss the Certificate Request Wizard.

Using the Command Line

  1. Create a request for a server certificate with the following command:
  2. certutil -R \
    -s "cn=serverName,ou=division,o=company,l=city,st=state,c=country" \
    -a -d ServerRoot/alias -P slapd-serverID-

    The -s option specifies the DN of the requested server certificate. Certificate Authorities usually require all of the attributes shown in this example in order to completely identify the server. See Step 4 above for a description of each attribute.

  3. The certutil tool will prompt you for the password to the server's key database. This is the password set in Creating a Certificate Database. The tool will then generate a PKCS #10 certificate request in the PEM encoded text format.

Installing the Server Certificate

Transmit the request from the previous section to your Certificate Authority, according to its procedures. For example, you may be asked to send the certificate request in an email, or you may be able to enter the request through the CA's website.

Once 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, it may only take a day or two to respond to your request. If your selected CA is external to your company, it could take several weeks to respond to your request.

When the CA sends a response, be sure to save the information in a text file. The PKCS #11 certificate in PEM format will look 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-----

You should also back up the certificate data in a safe location. If your system ever loses the certificate data, you can reinstall the certificate using your backup file.

Once you have your server certificate, you are ready to install it in your server's certificate database.

Using the Console

  1. On the top-level Tasks tab of Directory Server Console, click the Manage Certificates button. Alternatively, with the Tasks tab showing, select the Manage Certificates item from the Console>Security menu.
  2. The Manage Certificates window is displayed.

  3. Select the Server Certs tab, and click Install.
  4. The Certificate Install Wizard is displayed.

  5. Choose one of the following options for the certificate location:
  1. Verify that the certificate information displayed is correct, then click Next.
  2. Specify a name for the certificate, then click Next. This is the name that will appear in the table of certificates.
  3. Verify the certificate by providing the password that protects the private key. This password is the same as the one you provided in Step 2 of Creating a Certificate Database. Click Done when you are finished.
  4. Your new certificate appears in the list on the Server Certs tab. Your server is now ready for SSL activation.

Using the Command Line

  1. Install the new server certificate in your certificate database with the following command:
  2. certutil -A -n "certificateName" -t "u,," -a -i certFile \
             -d ServerRoot/alias -P slapd-serverID-

    where certificateName is a name you give to identify your certificate, and certFile is the text file containing the PKCS #11 certificate in PEM format. The -t "u,," option indicates that this is a server certificate for SSL communications.

  3. Optionally, you may also use the following certutil command to verify your installed certificates:
  4. certutil -L -d ServerRoot/alias -P slapd-serverID-

    The certificates listed with a trust attribute of u,, are the server certificates.

Trusting the Certificate Authority

Configuring your Directory Server to trust the Certificate Authority consists of obtaining its certificate and installing it into your server's certificate database. This process differs depending on the certificate authority you use. Some commercial CAs provide a website that allows you to automatically download the certificate, and others will email it to you upon request.

Using the Console

Once you have the CA certificate, you can use the Certificate Install Wizard to configure Directory Server to trust the Certificate Authority.

  1. On the top-level Tasks tab of Directory Server Console, click the Manage Certificates button. Alternatively, with the Tasks tab showing, select the Manage Certificates item from the Console>Security menu.
  2. The Manage Certificates window is displayed.

  3. Select the CA Certs tab, and click Install.
  4. The Certificate Install Wizard is displayed.

  5. If you saved the CA's certificate to a file, enter the path in the field provided. If you received the CA's certificate via email, copy and paste the certificate including the headers into the text field provided. Click Next.
  6. Verify that the certificate information displayed is correct for your Certificate Authority, then click Next.
  7. Specify a name for the certificate, then click Next.
  8. Select the purpose of trusting this CA. You may select either or both:
  9. Accepting connections from clients (Client Authentication). Select this checkbox if your LDAP clients perform certificate-based client authentication by presenting certificates issued by this CA.

    Accepting connections to other servers (Server Authentication). Select this checkbox if your server will play a replication supplier or chaining multiplexor role over SSL with another server that has a certificate issued by this CA.

  10. Click Done to dismiss the wizard.

Using the Command Line

  1. You may also use the following command to install a trusted CA certificate:
  2. certutil -A -n "CAcertificateName" -t "trust,," -a -i certFile \
             -d ServerRoot/alias -P slapd-serverID-

    where CAcertificateName is a name you give to identify the trusted CA, certFile is the text file containing the PKCS #11 certificate of the CA in PEM encoded text format, and the trust is one of the following codes:

    • T - This CA is trusted to issue client certificates. Use this code if your LDAP clients perform certificate-based client authentication by presenting certificates issued by this CA.
    • C - This CA is trusted to issue server certificates. Use this code if your server will play a replication supplier or chaining multiplexor role over SSL with another server that has a certificate issued by this CA.
    • CT - This CA is trusted to issue both client and server certificates. Use this code if both cases above apply to this CA.
  3. Optionally, you may also use the following certutil command to verify your installed certificates:
  4. certutil -L -d ServerRoot/alias -P slapd-serverID-

    The certificates listed with a trust attribute of u,, are the server certificates and those with CT,, are trusted CA certificates.


Activating SSL

Once you have installed your server certificate and trusted the CA's certificate, you are ready to activate SSL. Most of the time, you want your server to run with SSL enabled. If you temporarily disable SSL, make sure you re-enable it before processing operations that require confidentiality, authentication, or data integrity.

Before you can activate SSL, you must create a certificate database, obtain and install a server certificate and trust the CA's certificate as described in Obtaining and Installing Server Certificates.

Then, the following procedure will activate SSL communications and enable encryption mechanisms in the Directory Server:

  1. On the top-level Configuration tab of Directory Server Console, select the root node with the server name, and then select the Encryption tab in the right-hand panel.
  2. The tab displays the current server encryption settings.

  3. Indicate that you want encryption enabled by selecting the "Enable SSL for this Server" checkbox.
  4. Check the "Use this Cipher Family" checkbox.
  5. Select the certificate that you want to use from the drop-down menu.
  6. Click Cipher Settings and select the ciphers you want to use in the Cipher Preference dialog. For more information about specific ciphers, see Choosing Encryption Ciphers.
  7. Set your preferences for client authentication:
  8. Do not allow client authentication. With this option, the server will ignore the client's certificate and will refuse authentication based on it.

    Allow client authentication. This is the default setting. With this option, authentication is performed on the client's request. For more information about certificate-based authentication, see Configuring Client Authentication.


    Note

    If you are using certificate-based authentication with replication, then you must configure the consumer server to either allow or require client authentication.


    Require client authentication. With this option, the client connection will be refused if the client does not respond to the server's request for authentication.


    Note

    If Server Console connects to Directory Server over SSL, selecting "Require client authentication" disables communication because the Server Console does not have a certificate to use for client authentication. To modify this attribute from the command line, see Allowing Client Authentication.


  9. Optionally, select Use SSL in Server Console if you want the Console to use SSL when communicating with Directory Server.
  10. Click Save when done.
  11. Optionally, set the secure port you want the server to use for SSL communications in both LDAP and DSML-over-HTTP protocols. See Changing Directory Server Port Numbers for information.
  12. All connections to the secure port must use SSL. Regardless of whether you configure the secure port, once SSL is activated, clients may use the Start TLS operation to perform SSL encryption over the non-secure port.

  13. Restart Directory Server.
  14. See Starting the Server with SSL Enabled for more information.

Choosing Encryption Ciphers

A cipher is the algorithm used to encrypt and decrypt data. Generally speaking, the more bits a cipher uses during encryption, the stronger or more secure it is. Ciphers for SSL are also identified by the type of message authentication used. Message authentication is another algorithm which computes a checksum that guarantees data integrity. For a more complete discussion of cipher algorithms and their strengths, see the Administration Server Administration Guide.

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, normally the strongest one supported by both parties.

Directory Server provides the following ciphers for SSL 3.0 and TLS:

Table 11-1 Ciphers Provided with Directory Server 

Cipher Name

Description

None

No encryption, only MD5 message authentication (rsa_null_md5).

RC4 (128 bits)

RC4 cipher with 128-bit encryption and MD5 message authentication (rsa_rc4_128_md5).

RC4 (Export)

RC4 cipher with 40-bit encryption and MD5 message authentication (rsa_rc4_40_md5).

RC2 (Export)

RC2 cipher with 40-bit encryption and MD5 message authentication (rsa_rc2_40_md5).

DES or DES (Export)

DES with 56-bit encryption and SHA message authentication (rsa_des_sha).

DES (FIPS)

FIPS DES with 56-bit encryption and SHA message authentication. This cipher meets the FIPS 140-1 U.S. government standard for implementations of cryptographic modules (rsa_fips_des_sha).

Triple-DES

Triple DES with 168-bit encryption and SHA message authentication (rsa_3des_sha).

Triple-DES (FIPS)

FIPS Triple DES with 168-bit encryption and SHA message authentication. This cipher meets the FIPS 140-1 U.S. government standard for implementations of cryptographic modules (rsa_fips_3des_sha).

Fortezza

Fortezza cipher with 80-bit encryption and SHA message authentication.

RC4 (Fortezza)

Fortezza RC4 cipher with 128-bit encryption and SHA message authentication.

None (Fortezza)

No encryption, only Fortezza SHA message authentication.

In order to continue using Server Console with SSL, you must select at least one of the following ciphers:

Use the following procedure to choose the ciphers you want the server to use:

  1. On the top-level Configuration tab of Directory Server Console, select the root node with the server name, and then select the Encryption tab in the right-hand panel.
  2. The tab displays the current server encryption settings. Make sure SSL is enabled for your server as described in Activating SSL.

  3. Click Cipher Settings.
  4. The Cipher Preference dialog box is displayed.

  5. In the Cipher Preference dialog box, specify which ciphers you want your server to use by selecting or deselecting the checkbox beside their name.
  6. Unless you have a security reason to not use a specific cipher, you should select all of the ciphers, except for none,MD5.


    Caution

    Avoid selecting the cipher with no encryption and only MD5 message authentication, because the server will use this option if no other ciphers are available on the client. In this situation, the connection is not secure because no encryption is used.


  7. Click OK in the Cipher Preference dialog, then click Save in the Encryption Tab.

Allowing Client Authentication

If you have configured Directory Server to require client authentication and Server Console to connect using SSL, you can no longer use Server Console to manage any of your Sun Java System servers. You will have to use the appropriate command-line utilities instead.

However, if you wish to change your directory configuration so that you can use Server Console, you must follow these steps to no longer require but allow client authentication:

  1. Modify the cn=encryption,cn=config entry with the following command:
  2. ldapmodify -h host -p port -D "cn=Directory Manager" -w password
    dn: cn=encryption,cn=config
    changetype: modify
    replace: nsSSLClientAuth
    nsSSLClientAuth: allowed
    ^D

  3. Restart Directory Server as described in Starting and Stopping the Server From the Command Line.
  4. You can now start Server Console.


Configuring Client Authentication

Client authentication is a mechanism for the server to verify the identity of the client. Client authentication may be performed simply (by providing a dn and a password), using a certificate presented by the client, or through a SASL-based mechanism such as DIGEST-MD5. On the Solaris operating system, the Directory Server now supports the GSSAPI mechanism through SASL, which allows the authentication of a client through Kerberos V5.

Certificate-based authentication uses the client certificate obtained through the SSL protocol to find a user entry for identification. This mechanism is also known as EXTERNAL because it relies on an authentication mechanism that has already been established at a lower layer. (External authentication may be used with the IP Security Protocol (ipsec) in a future release.)

Certificate-based authentication is fully described in the Administration Server Administration Guide.

The following sections describe how to configure the two SASL mechanisms on Directory Server. See also Configuring LDAP Clients to Use Security.


Note

Identity mapping does not support chained suffixes.


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 wishing 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, "Managing Access Control". You may wish to further protect {CLEAR} passwords by configuring attribute encryption in that suffix, as described in Encrypting Attribute Values.

Configuring the DIGEST-MD5 Mechanism

The following procedure explains the steps necessary to configure Directory Server to use DIGEST-MD5:

  1. Using either the console or the ldapsearch command, verify that DIGEST-MD5 is a value of the supportedSASLMechanisms attribute on the root entry. For example, the following command will show which SASL mechanisms are enabled:
  2. ldapsearch -h host -p port -D "cn=Directory Manager" -w password \
    -s base -b "" "(objectclass=*)" supportedSASLMechanisms

    dn:
    supportedSASLMechanisms: EXTERNAL
    supportedSASLMechanisms: DIGEST-MD5
    supportedSASLMechanisms: GSSAPI
    ^D

  3. If DIGEST-MD5 is not enabled, use the following ldapmodify command to enable it:
  4. ldapmodify -h host -p port -D "cn=Directory Manager" -w password
    dn: cn=SASL, cn=security, cn=config
    changetype: modify
    add: dsSaslPluginsEnable
    dsSaslPluginsEnable: DIGEST-MD5
    -
    replace: dsSaslPluginsPath
    dsSaslPluginsPath: ServerRoot/lib/sasl
    ^D

  5. Use the default identity mapping for DIGEST-MD5, or create new ones as described inDIGEST-MD5 Identity Mappings.
  6. Ensure that the password is stored in {CLEAR} for all users who will access the server through SSL using DIGEST-MD5. See Chapter 7, "Managing User Accounts and Passwords," for instructions on how to configure password storage schemes.
  7. Restart the Directory Server if you modified the SASL configuration entry or one of the DIGEST-MD5 identity mapping entries.

DIGEST-MD5 Identity Mappings

Identity mappings for SASL mechanisms try to match credentials of the SASL identity with a user entry in the directory. See Identity Mapping for a complete description of this mechanism. Authentication will fail 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 DIGEST-MD5, it is recommended that clients create a Principal which 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 sent by the client is available in the ${Principal} place-holder.

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

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 the dn field of the Principal contains the exact DN of an existing user in the directory.

To define you own identity mappings for DIGEST-MD5:

  1. Edit the default mapping entry or create new mapping entries under cn=DIGEST-MD5,cn=identity mapping,cn=config. See Identity Mapping for the definition of the attributes in an identity mapping entry. An example mapping for DIGEST-MD5 is located in the following file:
  2. ServerRoot/slapd-serverID/ldif/identityMapping_Examples.ldif

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

    ldapmodify -a -h host -p port -D "cn=Directory Manager" -w 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)

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

SASL Authentication Through GSSAPI (Solaris Only)

The Generic Security Services 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 on Solaris SPARC-based platforms. Sun recommends you install the Kerberos V5 implementation in the Sun Enterprise Authentication Mechanism (SEAM) 1.0.1 server.

The server uses this API 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.

Configuring the Kerberos System

Configure the Kerberos software according to the manufacturer's instructions. If you are using the SEAM 1.0.1 server, this includes the following steps:

  1. Configure the files in /etc/krb5.
  2. Create the Kerberos database to store users and services, and in it create the principal for the LDAP service. The LDAP service principal is:
  3. ldap/serverFQDN@REALM

    where the serverFQDN is the fully qualified domain name of your Directory Server.

  4. Start the Kerberos daemon processes.
  5. Note that the DNS must be configured on the host machine.

Please refer to your software documentation for detailed instructions for each of these steps. Refer also to the example Configuring Kerberos Authentication using GSSAPI with SASL: Example procedure.

Configuring the GSSAPI Mechanism

The following procedure explains the steps necessary to configure Directory Server to use GSSAPI on the Solaris platform:

  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, including one for the LDAP service.
    • Ensure that the keytab is only readable by the Directory Server user.
    • Make the filename different from the default /etc/krb5/krb5.keytab.
    • Set the environment variable KRB5_KTNAME in the start-slapd script, in order to ensure the new keytab is used rather than the default.

  3. Restart the Directory Server if you modified the SASL configuration entry or one of the GSSAPI identity mapping entries.
  4. 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. See Identity Mapping for complete description of this mechanism. Authentication will fail 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], where the uid may contain an optional instance identifier followed by an optional realm that is often a domain name. For example, the following are all valid user Principals:

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

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

To define identity mappings for GSSAPI:

  1. Create new mapping entries under cn=GSSAPI,cn=identity mapping, cn=config. See Identity Mapping for the definition of the attributes in an identity mapping entry.
  2. Examples of GSSAPI mappings are located in the following file:

    ServerRoot/slapd-serverID/ldif/identityMapping_Examples.ldif

    The default GSSAPI mapping suggested in this file assumes that the Principal contains only a user ID, and this 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 it 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

  3. Restart the Directory Server for your new mappings to take effect.


Identity Mapping

Several authentication mechanisms in Directory Server require a mapping from credentials of another protocol to a DN in the directory. Currently, this is the case for the DSML-over-HTTP protocol and the DIGEST-MD5 and GSSAPI SASL mechanisms. Each of these uses identity mapping to determine a bind DN based on protocol-specific credentials provided by the client.

Identity mapping uses the entries in the cn=identity mapping, cn=config configuration branch. This branch includes a container for each of the protocols which must perform identity mapping:

A mapping entry defines a way of extracting the elements of the protocol-specific credentials to use them in a search of the directory. If that search returns a single user entry, the mapping has succeeded and the connection will use this entry as the bind DN for all operations. If the search returns zero or more than one entry, the mapping fails and any other mappings are applied.

Each branch should contain a default mapping for that protocol and any number of custom mappings. The default mapping has the RDN cn=default, and custom mappings may have any other RDN that uses cn as the naming attribute. All of the custom mappings are evaluated first, in a non-deterministic order until one of them succeeds. If all custom mappings fail, the default mapping is applied last. If the default mapping also fails, authentication of the client fails.

A mapping entry must contain the top, Container, and dsIdentityMapping object classes. The entry may then contain the following attributes:

Additionally, a mapping entry may also contain the dsPatternMatching object class which allows it to use the following attributes:

All of the attribute values above, except for dsSearchScope may contain place-holders of the format ${keyword} where keyword is the name of an element in the protocol specific credentials. During the mapping, the place-holder will be substituted for the actual value of the element as provided by the client.

After all place-holders have been substituted, any pattern matching that is defined will be performed. The matching pattern will be compared to the regular expression. If the regular expression does not match the pattern string, this mapping fails. If it does match, the matching values of regular expression terms in parentheses will be available as numbered place-holders for use in other attribute values. For example, the following mapping could be defined for SASL:

dsMatching-pattern: ${Principal}
dsMatching-regexp: (.*)@(.*)\.(.*)
dsMappedDN: uid=$1,ou=people,dc=$2,dc=$3

If a client authenticates with the Principal of bjensen@example.com, this mapping will define the bind DN uid=bjensen,ou=people,dc=example,dc=com. If this DN exists in the directory, the mapping will succeed, the client will be authenticated, and all operations performed during this connection will use this bind DN.

The dsMatching-pattern is compared to the dsMatching-regexp using the Posix regexec(3C) and regcomp(3C) function calls. Directory Server uses extended regular expressions and all comparisons are case insensitive. For more information, please refer to the man pages for these functions in the Directory Server Man Page Reference.

The attribute values that may contain place-holders must encode any $, {, and } characters that are not part of a place-holder, even if no place-holder is used. You must encode these characters with the following values: $ as \24, { as \7B, and } as \7D.

Using place-holders and substitutions allows you to create mappings that extract a username or any other value from the protocol-specific credentials and use its value to define a mapped DN or perform a search for a corresponding DN anywhere in the directory. You should define the mappings that extract the expected credentials provided by your directory clients and map them to your specific directory structure.


Caution

Creating a poorly defined mapping is a security hole. For example, a mapping to a hard-coded DN without pattern matching will always succeed, thereby authenticating clients who might not be directory users.

It is safer to define several mappings to handle different client credential formats than to create a single, overly-generic and permissive mapping. You should always try to map client connections to specific users according to the client credentials.



Configuring LDAP Clients to Use Security

The following sections explain how to configure and use SSL in LDAP clients that wish 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 may optionally initiate one of the client authentication mechanisms by sending its own certificate or information for one of the two SASL mechanism, either DIGEST-MD5 or 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 the 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 the Directory Server Resource Kit Tools Reference.

To configure SSL connections on other LDAP clients, please 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. They use the SSL protocol to provide data encryption but cannot guarantee confidentiality nor protect against impersonation.


Configuring Server Authentication in Clients

When a client establishes an SSL connection with a server, it must trust the certificate presented by the server. In order to do so, the client must:

Mozilla is a client application that uses SSL to communicate with web servers over the HTTP protocol. You can use Mozilla to manage the certificates that your LDAP client will also use. Alternatively, you may use the certutil tool to manage certificate databases.

Managing Client Certificates Through Mozilla

The following procedure describes how to use Mozilla to manage a certificate database on the client machine.

  1. Upon startup, Mozilla will ensure that a certificate database exists, or it will create one if needed. The certificate database will be stored in a file along with other Mozilla preferences, for example .mozilla/username/string.slt/cert8.db
  2. If you use this procedure, find the certificate database created by Mozilla and remember the path for use by your client applications.

  3. Use Mozilla to browse the website of the Certificate Authority that issued the certificate for the Directory Server you wish to access. Mozilla will automatically retrieve the Certificate Authority's certificate and ask you if it should be trusted.
  4. For example, if you are using an internally deployed Sun Java System Certificate Server, you will go to a URL of the form https://hostname:444.

  5. Trust the Certificate Authority's certificate when prompted to do so by Mozilla. You should trust the CA certificate for server authentication.
  6. This step may not be possible depending on the CA's website. If Mozilla does not automatically prompt you to trust the CA certificate, use the following procedure to do it manually.

Managing Client Certificates Through the Command Line

Use the certutil tool to manage certificates through the command line. This tool is provided in the SUNWtlsu package.

  1. On the client host machine, create a certificate database with the following command:
  2. certutil -N -d path -P prefix

    The tool will prompt the user for a password to protect the certificates. The tool will then create the following files: path/prefixcert8.db and path/prefixkey3.db.

    The certificate database should be created individually by the users of the LDAP client application in a location that is accessible only to them, for example a protected subdirectory of their home directory.

  3. Contact the Certificate Authority that issued the certificate for Directory Server that you wish to access and request their CA certificate. You may send email or access their website to obtain a PEM encoded text version of their PKCS #11 certificate. Save this certificate in a file.
  4. For example, if you are using an internally deployed Sun Java System Certificate Server, you will go to a URL of the form https://hostname:444. From the top-level Retrieval tab, select Import CA Certificate Chain and copy the encoded certificate there.

    Alternatively, if you obtain your client and server certificates from the same CA, you may reuse the CA certificate obtained through the procedure for Trusting the Certificate Authority.

  5. Import the CA certificate as a trusted CA for issuing server certificates used in SSL connections. Use the following command:
  6. certutil -A -n "certificateName" -t "C,," -a -i certFile -d path -P prefix

    where certificateName is a name you give to identify this certificate, certFile is the text file containing the PKCS #11 certificate of the CA in PEM encoded text format, and path and prefix are the same as in Step 1.

    Every user of the LDAP client application must import the CA certificate into his or her certificate database. All users may import the same certificate located in certFile.

Specifying SSL Options for Server Authentication

To perform server authentication in SSL with the ldapsearch tool, users only need to specify the path of their certificate database. When establishing the SSL connection through the secure port, the server will send its certificate. The ldapsearch tool will then find in the user's certificate database the trusted CA certificate of the CA that issued the server certificate.

The following command shows how a user would specify his or her certificate database if it was created by Mozilla:

ldapsearch -h host -p securePort \
           -D "uid=bjensen,dc=example,dc=com" -w bindPassword \
           -Z -P .mozilla/bjensen/string.slt/cert8.db \
           -b "dc=example,dc=com" "(givenname=Richard)"

Configuring Certificate-Based Authentication in Clients

The default mechanism for client authentication uses certificates to securely identify users to the Directory Server. In order to perform certificate-based authentication of clients, you must:

These procedures require the certutil tool to manage certificates through the command line. This tool is provided in the SUNWtlsu package.

Obtaining and Installing a User Certificate

Client certificates must be requested and installed by each user wishing to access the directory with certificate-based authentication. This procedure assumes the user has already configured a certificate database as described in Configuring Server Authentication in Clients.

  1. Create a request for a user certificate with the following command:
  2. certutil -R \
    -s "cn=Babs Jensen,ou=Sales,o=example.com,l=city,st=state,c=country"\
    -a -d path -P prefix

    The -s option specifies the DN of the requested certificate. Certificate Authorities usually require all of the attributes shown in this example in order to completely identify the owner of the certificate. The certificate DN will be mapped to the user's directory DN through the certificate mapping mechanism in Step 9.

    The path and prefix locate the user's certificate and key databases. The certutil tool will prompt the user for the password to their key database. The tool will then generate a PKCS #10 certificate request in PEM encoded text format.

  3. Save the encoded certificate request in a file and transmit it to your Certificate Authority, according to its procedures. For example, you may be asked to send the certificate request in an email, or you may be able to enter the request through the CA's website.
  4. Once 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, it may only take a day or two to respond to your request. If your selected CA is external to your company, it could take several weeks to respond to your request.
  5. When the CA sends a response, download or copy the PEM encoded text of your new certificate to a text file.
  6. Install the new user certificate in your certificate database with the following command:
  7. certutil -A -n "certificateName" -t "u,," -a -i certFile -d path -P prefix

    where certificateName is a name you give to identify your certificate, certFile is the text file containing the PKCS #11 certificate in PEM format, and path and prefix are the same as in Step 1.

    Alternatively, if you are managing your certificate database through Mozilla, there may be a link on your CA's website to install the certificate directly. Click this link and step through the dialog boxes that Mozilla presents to you.

  8. Create a binary copy of your certificate with the following command:
  9. certutil -L -n "certificateName" -d path -r > userCert.bin

    where certificateName is the name you gave to your certificate when you installed it, path is the location of your certificate database, and userCert.bin is the name of the output file that will contain the certificate in binary format.

  10. On the Directory Server, add the userCertificate attribute to the directory entry for the user who owns the client certificate.
  11. To add the certificate through the console:
    1. From the top-level Directory tab of Directory Server Console, locate the user entry in the directory tree, right click on it, and select Edit with Generic Editor from the pop-up menu.
    2. In the Generic Editor, click Add Attribute.
    3. Select the userCertificate attribute from the pop-up dialog and binary from the Subtype drop-down list. You must specify the binary subtype, otherwise certificate mapping will fail.
    4. Locate the new userCertificate field in the Generic Editor. Click the corresponding Set Value button to set a binary value for this attribute.
    5. In the Set Value dialog, enter the name of the userCert.bin file created in Step 6, or click Browse to locate the file.
    6. Click OK in the Set Value dialog and then click Save in the Generic Editor.
  12. To add the certificate from the command line, use the ldapmodify command as shown in the following example. This command uses SSL to send the certificate over a secure connection:
  13. ldapmodify -h host -p securePort \
               -D "uid=bjensen,dc=example,dc=com" -w bindPassword \
               -Z -P .mozilla/bjensen/string.slt/cert8.db
    version: 1
    dn: uid=bjensen,dc=example,dc=com
    changetype: modify
    add: userCertificate
    userCertificate;binary: < file:///path/userCert.bin

    You must include the binary subtype, otherwise certificate mapping will fail. The spaces before and after < are significant and must be used exactly as shown. In order to use the < syntax to specify a filename, you must begin the LDIF statement with the line version: 1. When ldapmodify processes this statement, it will set the attribute to the value read from the entire contents of the given file.

  14. On Directory Server, install and trust the certificate of the CA that issued your user certificate, if necessary. This CA must be trusted for accepting connections from clients. See Trusting the Certificate Authority.
  15. Configure Directory Server for certificate-based authentication as described in the Administration Server Administration Guide. In this procedure, you will edit the certmap.conf file so that the server maps the user certificate presented through the LDAP client to the corresponding user DN.
  16. Make sure that the verifyCert parameter is set to on in the certmap.conf file. The server will then verify that the user entry contains the same certificate, thereby positively identifying the user.

Specifying SSL Options for Certificate-Based Client Authentication

To perform certificate-based client authentication in SSL with the ldapsearch tool, users need to specify several command-line options to use their certificate. When establishing the SSL connection through the secure port, the tool will authenticate the server's certificate and then send the user certificate to the server.

The following command shows how a user would specify the options to access his or her certificate database if it was created by Mozilla:

ldapsearch -h host -p securePort \
           -Z -P .mozilla/bjensen/string.slt/cert8.db \
           -N "certificateName" \
           -K .mozilla/bjensen/string.slt/key3.db -W keyPassword \
           -b "dc=example,dc=com" "(givenname=Richard)"

The -Z option indicates certificate-based authentication, the certificateName specifies which certificate to send, and the -K and -W options allow the client application to access the certificate so that it can be sent. By not specifying the -D and -w options, the bind DN will be determined from the certificate mapping.

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 wish to use encrypted SSL connections, you must still trust the server certificate as described in Configuring Server Authentication in Clients.

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 hostname of the machine as the default realm for DIGEST-MD5. The server uses the lower-case value of the hostname found in the nsslapd-localhost configuration attribute.

If you do not specify a realm, then the default realm offered by the server will be used.

Specifying Environment Variables

In the UNIX environment, you must set the SASL_PATH environment variable so the LDAP tools will find the DIGEST-MD5 libraries. The DIGEST-MD5 library is a shared library dynamically loaded by the SASL plug-in, and therefore you should set the SASL_PATH variable as follows (for example in the Korn shell):

export SASL_PATH=ServerRoot/lib/sasl

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

Examples of the ldapsearch Command

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

ldapsearch -h host -p nonSecurePort -D "" -w bindPassword \
           -o mech=DIGEST-MD5 [-o realm="hostFQDN"] \
           -o authid="dn:uid=bjensen,dc=example,dc=com" \
           -o authzid="dn:uid=bjensen,dc=example,dc=com" \
           -b "dc=example,dc=com" "(givenname=Richard)"

The example above 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 value of authid is the Principal used in identity mapping. It is recommended that the authid contain 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 allow you to use the mappings shown in DIGEST-MD5 Identity Mappings.

Usually, you will want an SSL connection to provide encryption over secure port and DIGEST-MD5 to provide the client authentication. The following example will perform the same operation over SSL:

ldapsearch -h host -p securePort \
           -Z -P .mozilla/bjensen/string.slt/cert8.db \
           -N "certificateName" -W keyPassword \
           -o mech=DIGEST-MD5 [-o realm="hostFQDN"] \
           -o authid="dn:uid=bjensen,dc=example,dc=com" \
           -o authzid="dn:uid=bjensen,dc=example,dc=com" \
           -b "dc=example,dc=com" "(givenname=Richard)"

In this example, the -N and -W options are required by the ldapsearch command, but they are not used for client authentication. Instead, the server will again perform a 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 wish to use encrypted SSL connections, you must trust the server certificate as described in Configuring Server Authentication in Clients.

Configuring Kerberos V5 on a Client Host

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

  1. Install Kerberos V5 according to its installation instructions. Sun recommends installing the Sun Enterprise Authentication Mechanism (SEAM) 1.0.1 client software.
  2. Configure the Kerberos software. With SEAM, configure the files under /etc/krb5 in order to setup the kdc server, define 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 listed is kerberos_v5.

Specifying SASL Options for Kerberos Authentication

  1. Before using a GSSAPI-enabled client application, you must initialize the Kerberos security system with your user Principal using the following command:
  2. kinit userPrincipal

    The userPrincipal is your SASL identity, for example bjensen@EXAMPLE.COM.

  3. Specify SASL options for using Kerberos.
  4. Note that in the UNIX environment, you must set the SASL_PATH environment variable to ServerRoot/lib/sasl in order for the correct libraries to be found. For example in the Korn shell:

    export SASL_PATH=ServerRoot/lib/sasl

    This path assumes that Directory Server is installed on the same host where the LDAP tools will be 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 host -p Port \
               -o mech=GSSAPI \
               -o authid="bjensen@EXAMPLE.COM" \
               -o authzid="bjensen@EXAMPLE.COM" \
               -b "dc=example,dc=com" "(givenname=Richard)"

    The authid may be omitted because they are present in the Kerberos cache which 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 used in identity mapping. The Principal must be the full Principal, including the realm. See GSSAPI Identity Mappings, for more information.

Configuring Kerberos Authentication using GSSAPI with SASL: Example procedure

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

For more help, use the example procedure below to get an idea of which steps to follow. Please be aware however, that this procedure is an example, and you must modify it to suit your own configuration and environment.

Additional information on configuring and using Kerberos in Solaris can be found in the Security Services System Administration Guide, which is a part of the Solaris documentation set. You can also consult the man pages.

The steps in this example procedure are as follows:

Assumptions

This example procedure describes the process of configuring one machine to operate as a KDC, and a second machine to run a Directory Server that will allow users to perform Kerberos authentication via GSSAPI.

It is possible to run both the KDC and the Directory Server on the same machine. If you choose to do this, use the same procedure, but omit the steps listed 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 will be used. These are listed below. When using the example procedure, modify the values accordingly to suit your environment.

All Machines - Edit the Kerberos Client Configuration File

The /etc/krb5/krb5.conf configuration file provides information required by Kerberos clients 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, as follows:

The updated /etc/krb5/krb5.conf configuration file should look like the contents of Code Example 11-1:

Code Example 11-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 file /etc/krb5/kadm5.acl configuration file. The updated /etc/krb5/kadm5.acl file should look like Code Example 11-3:

Code Example 11-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 file /etc/krb5/kdc.conf file to replace "___default_realm___" with "EXAMPLE.COM".

The updated /etc/krb5/kdc.conf file should look like Code Example 11-3:

Code Example 11-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

Create the KDC database with the command used in Code Example 11-4:

Code Example 11-4 Command for creating the KDC database


bash-2.05# /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: master-password
Re-enter KDC database master key to verify: master-password
bash-2.05#

KDC Machine - Create an Admin Principal and Keytab

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

Code Example 11-5 Command for creating an Admin Principal and Keytab


bash-2.05# /usr/sbin/kadmin.local
kadmin.local: add_principal kws/admin
Enter password for principal "kws/admin@EXAMPLE.COM": kws-password
Re-enter password for principal "kws/admin@EXAMPLE.COM": kws-password
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
bash-2.05#

KDC Machine - Start the Kerberos Daemons

Run the following commands to start the KDC and admin daemons. The KDC process will appear in the process list as /usr/lib/krb5/krb5kdc and the admin daemon will appear as /usr/lib/krb5/kadmind.

Code Example 11-6 Commands for starting the Kerberos daemons on Solaris 9


bash-2.05# /etc/init.d/kdc start
bash-2.05# /etc/init.d/kdc.master start
bash-2.05#

Note than on Solaris 10, the daemons are managed by the SMF framework. Start the daemons on Solaris 10 as follows:

Code Example 11-7 Commands for starting the Kerberos daemons on Solaris 10


bash-2.05# svcadm disable network/security/krb5kdc
bash-2.05# svcadm enable network/security/krb5kdc
bash-2.05# svcadm disable network/security/kadmin
bash-2.05# svcadm enable network/security/kadmin
bash-2.05#

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.

Code Example 11-8 Commands for adding host principals


bash-2.05# /usr/sbin/kadmin -p kws/admin
Enter Password: kws-password
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
bash-2.05#

KDC Machine - Add an LDAP Principal for the Directory Server

In order for the Directory Server to be able to validate the Kerberos tickets 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 (which must match the fully qualified name provided when installing the Directory Server) and realm is the Kerberos realm. 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:

Code Example 11-9 Commands for adding an LDAP Principal to the KDC


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

KDC Machine - Add a Test User to the KDC

In order to be able to perform Kerberos authentication, the user authenticating must exist in the Kerberos database. In this example, the user will have the username kerberos-test, which means that the Kerberos principal will be kerberos-test@EXAMPLE.COM.

Create the user using command sequence provided in Code Example 11-10.

Code Example 11-10 Commands for adding an test user to the KDC


bash-2.05# /usr/sbin/kadmin -p kws/admin
Enter Password: kws-password
kadmin: add_principal kerberos-test
Enter password for principal "kerberos-test@EXAMPLE.COM": test-password
Re-enter password for principal "kerberos-test@EXAMPLE.COM": test-password
Principal "kerberos-test@EXAMPLE.COM" created.
kadmin: quit
bash-2.05#

Directory Server Machine - Install the Directory Server

Install Directory Server 5.2 and patches. Example settings are provided below:

Fully Qualified Computer Name

directory.example.com

Install Root

/data/ds52p2

Server User

unixuser

Server Group

unixgroup

Server Identifier

directory

Server Port

389

Suffix

dc=example,dc=com

Administrator ID

admin

Administrator Password

dsadmin-password

Administration Domain

example.com

Directory Manager DN

cn=Directory Manager

Directory Manager Password

dm-password

Administration Port

390

Directory Server Machine - Configure the Directory Server to Enable GSSAPI

First, create the file /data/ds52p2/shared/bin/gssapi.ldif to define the mapping that should be used by the Directory Server to identify which Kerberos user is authenticating, based on the principal. Create file contents to be the same as what is shown in Code Example 11-11:

Code Example 11-11 gssapi.ldif file contents


n: 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: /data/ds52p2/lib/sasl

Next, use the ldapmodify command to update the Directory Server to enable GSSAPI with the appropriate mappings, as shown in Code Example 11-12.

Code Example 11-12 Commands for updating the Directory Server to enable GSSAPI


bash-2.05# ./ldapmodify -D 'cn=Directory Manager' -w dm-password -a -f
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
bash-2.05#

Directory Server Machine -- Create a Directory Server Keytab

As mentioned previously, in order to authenticate Kerberos users via GSSAPI, the Directory Server must have its own principal in the KDC. In order for this to work properly, this principal information must reside in a Kerberos keytab on the Directory Server machine 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:

Code Example 11-13 Commands for creating a keytab for Directory Server

bash-2.05# /usr/sbin/kadmin -p kws/admin
Enter Password: kws-password
kadmin: ktadd -k /data/ds52p2/slapd-directory/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:/data/ds52p2/slapd-directory/config/ldap.keytab.
kadmin: quit
bash-2.05#

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

Code Example 11-14 Commands for altering keytab permissions and ownership


bash-2.05# chown unixuser:unixgroup /data/ds52p2/slapd-directory/config/ldap.keytab
bash-2.05# chmod 600 /data/ds52p2/slapd-directory/config/ldap.keytab
bash-2.05#

By default, the Directory Server will try 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 editing the start-slapd script to use the KRB5_KTNAME environment variable as shown in Code Example 11-15.

Code Example 11-15 Updated start-slapd script to use a custom Kerberos keytab


#!/bin/sh

# Configure the server to use a custom Kerberos keytab.
KRB5_KTNAME=/data/ds52p2/slapd-directory/config/ldap.keytab
export KRB5_KTNAME

unset LD_LIBRARY_PATH

# Script that starts the ns-slapd server.
# Exit status can be:
# 0: Server started successfully
# 1: Server could not be started
# 2: Server was already started

NETSITE_ROOT=/data/ds52p2
export NETSITE_ROOT

{The remainder of this file has been omitted to conserve space}

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

Code Example 11-16 Command for restarting the Directory Server


bash-2.05# cd /data/ds52p2/slapd-directory
bash-2.05# ./stop-slapd
bash-2.05# ./start-slapd
bash-2.05#

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

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

Add the user to the directory by first creating the file /data/ds52p2/shared/bin/testuser.ldif with the following contents:

Code Example 11-17 New file testuser.ldif


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:

Code Example 11-18 Command for adding the test entry to the server


bash-2.05# ./ldapmodify -D 'cn=Directory Manager' -w dm-password -f
testuser.ldif
adding new entry uid=kerberos-test,ou=People,dc=example,dc=com
bash-2.05#

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

Now that the test user exists in both the Kerberos database and Directory Server and the KDC, it is possible to authenticate as that user to the Directory Server over Kerberos using GSSAPI.

Firstly, use the kinit command to get a Kerberos ticket for the user, as shown in Code Example 11-19.

Code Example 11-19 Command for getting a Kerberos ticket


bash-2.05# kinit kerberos-test
Password for kerberos-test@EXAMPLE.COM: test-password
bash-2.05#

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

Code Example 11-20 Command for viewing information about the test ticket


bash-2.05# 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
bash-2.05#

Client Machine - Authenticate to the Directory Server via GSSAPI

The final step is to authenticate to the Directory Server using GSSAPI. The ldapsearch utility provided with the Directory Server provides support for SASL authentication, including GSSAPI, DIGEST-MD5, and EXTERNAL mechanisms. However, to do this it is necessary to provide the client with the path to the SASL library it should use. This can be done by setting the SASL_PATH environment variable to the lib/sasl directory under the Directory Server install root:

Code Example 11-21 Command for setting the SASL_PATH environment variable


bash-2.05# SASL_PATH=/data/ds52p2/lib/sasl
bash-2.05# export SASL_PATH
bash-2.05#

To actually perform a Kerberos-based authentication to the Directory Server using ldapsearch, it is necessary to include the -o mech=GSSAPI and -o authzid=principal arguments. The following example retrieves the dc=example,dc=com entry while authenticated as the Kerberos test user account created previously:

Code Example 11-22 Retrieving the dc=example,dc=com entry after authenticating via GSSAPI


bash-2.05# ./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
bash-2.05#

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

Code Example 11-23


bash-2.05# tail -12 /data/ds52p2/slapd-directory/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.
bash-2.05#

From this, we can see that the bind is a three step process, with the first two returning LDAP result 14 (SASL bind in progress) and the third showing that the bind was successful. The method=sasl and mech=GSSAPI tags show that the bind used the GSSAPI SASL mechanism, and 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.



Previous      Contents      Index      Next     


Part No: 817-7613-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.