Netscape logo Administrator's Guide
Netscape Directory Server                                                                                                                                  
Previous
 Contents
 Index
 DocHome Next



Chapter 11   Managing SSL and SASL



To provide secure communications over the network, Netscape Directory Server (Directory Server) includes the LDAPS communications protocol. LDAPS is the standard LDAP protocol, but it runs on top of Secure Sockets Layer (SSL).

Directory Server also supports SASL authentication using a GSS-API mechanism, allowing Kerberos, rather than certificates, to authenticate sessions and encrypt data.

This chapter describes how to use SSL and SASL with your Directory Server in the following sections:


Introduction to SSL in the Directory Server

You can use SSL to secure communications between LDAP clients and the Directory Server, between Directory Servers that are bound by a replication agreement, or between a database link and a remote database. You can use SSL with simple authentication (bind DN and password) or with certificate-based authentication.

Using SSL with simple authentication ensures confidentiality and data integrity. The benefits of using a certificate to authenticate to the Directory Server instead of a bind DN and password include:

The Directory Server is capable of simultaneous SSL and non-SSL communications. This means that you do not have to choose between SSL or non-SSL communications for your Directory Server; you can use both at the same time. Directory Server also supports SASL client authentication.

Note 

If you are running Directory Server on a UNIX platform, enabling SSL will also enable support the the Start TLS extended operation. The Start TLS extended operation provides security on a regular LDAP connection.


Enabling SSL: Summary of Steps

To configure your Directory Server to use LDAPS, follow these steps:

  1. Obtain and install a certificate for your Directory Server, and configure the Directory Server to trust the certification authority's (CA's) certificate.

    For information, see Obtaining and Installing Server Certificates.

  2. Turn on SSL in your directory.

    For information, see Activating SSL.

  3. Configure the Administration Server to connect to an SSL-enabled Directory Server.

    For information, see Managing Servers with Netscape Console.

  4. Optionally, ensure that each user of the Directory Server obtains and installs a personal certificate for all clients that will authenticate with SSL.

    For information, see Configuring LDAP Clients to Use SSL.

For a complete description of SSL, Internet security, and certificates, check the appendixes included in Managing Servers with Netscape Console.


Command-Line Functions for Start TLS

You can also specify that LDAP operations such as ldapmodify, ldapsearch, and ldapdelete use SSL/TLS when communicating with an SSL-enabled server or to use certificate authentication.

Using the command-line options, you can also specify or enforce Start TLS, which allows a secure connection to be enabled on a cleartext port after a session has been initiated.

In the following example, a network administrator enforces Start TLS for a search for Mike Connor’s identification number:

ldapsearch -p 389 -ZZZ -P certificateDB -N certificate_name -s base -b "uid=mconnors,ou=people,dc=example,dc=com" "(attribute=govIdNumber)"

where  -ZZZ enforces Start TLS, certificateDB gives the filename and path to the certificate database, and certificate_name is the certificate.

Note 

The -ZZZ command enforces the use of Start TLS, and the server must respond that a Start TLS command was successful. If you use the -ZZZ command and the server does not support Start TLS, the operation is aborted immediately.

For information on the command-line options available, see the Netscape Directory Server Configuration, Command, and File Reference.


Troubleshooting Start TLS
With the -ZZ option, the following to errors could occur:

  • If there is no certificate database, the operation fails. See Obtaining and Installing Server Certificates for information on using certificates.

  • If the server does not support Start TLS, the connection proceeds in cleartext. To enforce the use of Start TLS, use the -ZZZ command option.

  • If the certificate database does not have the Certifying Authority (CA) certificate, the connection proceeds in cleartext. See Obtaining and Installing Server Certificates for information on using certificates.

With the -ZZZ option, the following errors could occur, causing the Start TLS operation to fail:
For SDK libraries used in client programs, if a session is already in TLS mode and Start TLS is requested, then the connection continues to be in secure mode but prints the error "DSA is unwilling to perform".


Obtaining and Installing Server Certificates

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

This process is a necessary first step before you can turn on SSL in your directory. If you have already completed these tasks, see Activating SSL.

Obtaining and installing certificates consists of the following steps:

You will use the Certificate Request Wizard to generate a certificate request (Step 1) and send it to a Certificate Authority (Step 2). You then use the Certificate Install Wizard to install the certificate (Step 3) and to trust the Certificate Authority's certificate (Step 4).

These wizards automate the process of creating a certificate database and of installing the key-pair.


Step 1: Generate a Certificate Request

To generate a certificate request and send it to a CA:

  1. In the Directory Server Console, select the Tasks tab, and click Manage Certificates.

    The Manage Certificates window is displayed.

  2. Select the Server Certs tab, and click the Request button.

    The Certificate Request Wizard is displayed.

  3. Click Next.

  4. Enter the Requestor Information in the blank text fields, then click Next.

    Enter the following information:

    • Server Name -- Enter the fully qualified hostname of the Directory Server as it is used in DNS lookups; for example, dir.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 organization 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 (no abbreviations).

    • Country -- Select the two-character abbreviation for your country's name (ISO format). The country code for the United States is US.

  5. Enter the password that will be used to protect the private key, and click Next.

    The Next field is greyed out until you supply a password. When you click Next, the Request Submission dialog box is displayed.

  6. Select Copy to Clipboard or Save to File to save the certificate request information that you must send to the Certificate Authority.

  7. Click Done to dismiss the Certificate Request Wizard.

Once you have generated the request, you are ready to send it to the CA.


Step 2: Send the Certificate Request

Follow these steps to send the certificate information to the CA:

  1. Use your email program to create a new email message.

  2. Copy the certificate request information from the clipboard or the saved file into the body of the message.

    The content will look similar to the following example:

    -----BEGIN NEW CERTIFICATE REQUEST-----
    MIIBrjCCARcCAQAwbjELMAkGA1UEBhMCVXMxEzARBgNVBAgTCkNBTElGT1JOSUEx
    LDAqBgVBAoTI25ldHNjYXBlIGNvbW11bmljYXRpb25zIGNvcnBvcmF0aW9uMRwwG
    gYDVQQDExNtZWxsb24ubmV0c2NhcGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNA
    DCBiQKBgQCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7ug0EfgSLR0f+K41eNqqR
    ftGR83emqPLDOf0ZLTLjVGJaH4Jn4l1gG+JDf/n/zMyahxtV7+mT8GOFFigFfuxa
    xMjr2j7IvELlxQ4IfZgWwqCm4qQecv3G+N9YdbjveMVXW0v4XwIDAQABoAAwDQYK
    -----END NEW CERTIFICATE REQUEST-----

  3. Send the email message to the CA.

Once you have emailed your request, you must wait for the CA to respond with your certificate. Response time for requests 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. You will need the data when you install the 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 receive your certificate, you are ready to install it in your server's certificate database.


Step 3: Install the Certificate

To install a server certificate:

  1. In the Directory Server Console, select the Tasks tab, and click Manage Certificates.

    The Manage Certificates window is displayed.

  2. Select the Server Certs tab, and click Install.

    The Certificate Install Wizard is displayed.

  3. Choose one of the following options for the certificate location, then click Next.

    • In this file -- Enter the absolute path to the certificate in this field.

    • In the following encoded text block -- Copy the text from the CA's email or from the text file you created, and paste it in this field. For example:

    -----BEGIN CERTIFICATE-----
    MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBhMCVVMx
    IzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX
    aWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdCBUZXN0IFRlc3QgVGVz
    dCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3WhcNOTgwMzI2MDIzMzU3WjBP
    MQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZWN0b3J5IFB1Ymxp
    Y2F0aW9uczEWMBQGA1UEAxMNZHVgh49dq2itLmNvbTBaMA0GCSqGSIb3
    -----END CERTIFICATE-----

  4. Check that the certificate information displayed is correct, and click Next.

  5. Specify a name for the certificate, and click Next.

  6. Verify the certificate by providing the password that protects the private key.

This password is the same as the one you provided in Step 1: Generate a Certificate Request.

Now that you have installed your certificate, you need to configure your server to trust the Certificate Authority from which you obtained the server's certificate.


Step 4: Trust the Certificate Authority

Configuring your Directory Server to trust the certificate authority consists of obtaining your CA's 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 web site that allows you to automatically download the certificate. Others will email it to you upon request.

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

  1. In the Directory Server Console, select the Tasks tab, and click Manage Certificates.

    The Manage Certificates window is displayed.

  2. Go to the CA Certs tab, and click Install.

    The Certificate Install Wizard is displayed.

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

  4. Check that the certificate information that is displayed is correct, and click Next.

  5. Specify a name for the certificate, and click Next.

  6. Select the purpose of trusting this Certificate Authority (you can select both):

    • Accepting connections from clients (Client Authentication) -- The server checks that the client's certificate has been issued by a trusted Certificate Authority.

    • Accepting connections to other servers (Server Authentication) -- This server checks that the directory to which it is making a connection (for replication updates, for example) has a certificate that has been issued by a trusted Certificate Authority.

  7. Click Done to dismiss the wizard.

Once you have installed your certificate and trusted the CA's certificate, you are ready to activate SSL. However, you should first make sure that the certificates have been installed correctly.



Step 5: Confirm That Your New Certificates Are Installed

  1. In the Directory Server Console, select the Tasks tab, and click Manage Certificates.

    The Manage Certificates window is displayed.

  2. Select the Server Certs tab.

    A list of all the installed certificates for the server is displayed.

  3. Scroll through the list. You should find the certificates you installed.

    Your server is now ready for SSL activation.

Note 

When you renew a certificate using the Certificate Wizard, the text on the introduction screen (step 1) doesn't clearly indicate that the process is renewal and not requesting a new certificate. Also, the requestor information (step 2) doesn't get filled automatically.




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

Note 

On SSL-enabled servers, be sure to check the file permissions on certificate-database files, key-databases files, and PIN files to protect the sensitive information they contain. Because the server does not enforce read-only permissions on these files, check the file modes (on UNIX) to protect the sensitive information contained in these files.

To activate SSL communications:

  1. Set the secure port you want the server to use for SSL communications. See Changing Directory Server Port Numbers for information.

    The encrypted port number that you specify must not be the same port number you use for normal LDAP communications. By default, the standard port number is 389, and the secure port is 636.

  2. In the Directory Server Console, select the Configuration tab, and then select the topmost entry in the navigation tree in the left pane.

  3. Select the Encryption tab in the right pane.

    The tab displays the current server encryption settings.

  4. Indicate that you want encryption enabled by selecting the "Enable SSL for this Server" checkbox.

  5. Check the "Use this Cipher Family" checkbox.

  6. Select the certificate that you want to use from the drop-down menu.

  7. Click Cipher Settings.

    The Cipher Preference dialog box is displayed.

  8. Select the checkbox next to the cipher you want to use, and click OK to save your changes.

    For more information about specific ciphers, see Setting Security Preferences.

  9. Set your preferences for client authentication.

    • Do not allow client authentication -- With this option, the server will ignore the client's certificate. This does not mean that the bind will fail.

    • 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, seeUsing Certificate-Based Authentication.

    • Require client authentication -- With this option, the server requests authentication from the client.

      Note 

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



  10. If you want Netscape Console to use SSL during communications with Directory Server, select the "Use SSL in Netscape Console" option.

  11. If you configured Directory Server for certificate based client authentication, you can further configure the server to verify the authenticity of requests by selecting the "Check hostname against name in certificate for outbound SSL connections" option. The server does this verification by matching the hostname against the value assigned to the common name (cn) attribute of the subject name in the certificate being presented for authentication.

    By default, this feature is disabled. If it's enabled and if the hostname does not match the cn attribute of the certificate, appropriate error and audit messages are logged. For example, in a replicated environment, messages similar to these are logged in the supplier server's log files if it finds that the peer server's hostname doesn't match the name specified in its certificate:

    [DATE] - SSL alert: ldap_sasl_bind("",LDAP_SASL_EXTERNAL) 81 (Netscape runtime error -12276 - Unable to communicate securely with peer: requested domain name does not match the server's certificate.)

    [DATE] NSMMReplicationPlugin - agmt="cn=to ultra60 client auth" (ultra60:1924): Replication bind with SSL client authentication failed: LDAP error 81 (Can't contact LDAP server)

    It is recommended that you enable this option to protect Directory Server's outbound SSL connections against a Man in the Middle (MITM) attack.

  12. Click Save.

  13. Restart the Directory Server.

    See Starting the Server with SSL Enabled for more information.


Setting Security Preferences

You can choose the type of ciphers you want to use for SSL communications. A cipher is the algorithm used in encryption. Some ciphers are more secure, or stronger, than others. Generally speaking, the more bits a cipher uses during encryption, the more difficult it is to decrypt the key. For a more complete discussion of algorithms and their strength, see Managing Servers with Netscape Console.

When a client initiates an SSL connection with a server, the client tells the server what ciphers it prefers to use to encrypt information. In any two-way encryption process, both parties must use the same ciphers. There are a number of ciphers available. Your server needs to be able to use the ciphers that will be used by client applications connecting to the server.

Directory Server provides the following SSL 3.0 ciphers:

To select the ciphers you want the server to use:

  1. Make sure SSL is enabled for your server.

    For information, see Activating SSL.

  2. In the Directory Server Console, select the Configuration tab, and then select the topmost entry in the navigation tree in the left pane.

  3. Select the Encryption tab in the right pane.

    This displays the current server encryption settings.

  4. Click Cipher Settings.

    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 them from the list, and click OK.

    Unless you have a security reason not to use a specific cipher, you should select all of the ciphers, except for none,MD5 .

  6. In the Encryption tab, click Save.

Caution 

Avoid selecting the none,MD5 cipher because the server will use this option if no other ciphers are available on the client. It is not secure because encryption doesn't occur.

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

  • RC4 cipher with 40-bit encryption and MD5 message authentication.

  • No encryption, only MD5 message authentication.

  • DES with 56-bit encryption and SHA message authentication.

  • RC4 cipher with 128-bit encryption and MD5 message authentication.

  • Triple DES with 168-bit encryption and SHA message authentication.


Using Certificate-Based Authentication

Directory Server allows you to use certificate-based authentication for the command-line tools (which are LDAP clients) and for replication communications. Certificate-based authentication can occur between:

Note 

When specifying the key and certificate database filenames, you may use absolute or relative paths. If using relative paths, ensure that they are relative to the server root (for example, alias/slapd-phonebook-cert8.db and alias/slapd-phonebook-key3.db).

The name of the certificate database has been changed from cert7.db to cert8.db. Directory Server automatically converts the cert7.db to cert8.db and uses the new file. However, the dse.ldif file may not show the new database name. For example, you may still see this entry:

nsCertfile: alias/slapd-testDir-cert7.db

If you want the database filename change reflected in the dse.ldif file, manually edit the filename in the dse.ldif file.


Setting up Certificate-Based Authentication

To set up certificate-based authentication, you must:

  1. Create a certificate database for the client and the server or for both servers involved in replication.

    In the Directory Server, the certificate database creation automatically takes place when you install a certificate. For information on creating a certificate database for a client, see Configuring LDAP Clients to Use SSL.

  2. Obtain and install a certificate on both the client and the server or on both servers involved in replication.

  3. Enable SSL on the server or on both servers involved in replication.

    For information on enabling SSL, refer to Activating SSL.

    Note 

    If Netscape Console connects to Directory Server over SSL, selecting "Require client authentication" disables communication. This is because, although Netscape Console supports SSL, it does not have a certificate to use for client authentication.


  4. Map the certificate's distinguished name to a distinguished name known by your directory.

    This allows you to set access control for the client when it binds using this certificate. This mapping process is described in Managing Servers with Netscape Console.

Allowing/Requiring Client Authentication

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

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

  1. Stop Directory Server.

    For information on stopping and starting the server from the command-line, see Starting and Stopping the Server from the Command-Line.

  2. Modify the cn=encryption,cn=config entry by changing the value of the nsSSLClientAuth attribute from required to allowed.

    For information on modifying entries from the command-line, see chapter 2, "Creating Directory Entries."

  3. Start Directory Server.

    You can now start Netscape Console.


Configuring LDAP Clients to Use SSL

If you want all the users of your Directory Server to use SSL or certificate-based authentication when they connect using LDAP client applications, you must make sure they perform the following tasks:

These operations are sufficient if you want to ensure that LDAP clients recognize the server's certificate. However, if you also want LDAP clients to use their own certificate to authenticate to the directory, make sure that all your directory users obtain and install a personal certificate.

Note 

Some client applications do not verify that the server has a trusted certificate.

The following procedure describes how to use Netscape Communicator to perform these tasks.

  1. To create a certificate, it is sufficient to start Netscape Communicator.

    If it does not already exist, the certificate database will be created.

  2. Use Communicator to connect to your Certificate Authority.

    If you are using an internally deployed Netscape Certificate Management System, you will go to a URL of the form:

    https://hostname: port

    Some Certificate Authorities provide a link that allows you to download the CA's certificate.

  3. Trust the Certificate Authority.

    This task differs depending on the CA. In some cases, such as if you are connecting to a Netscape Certificate Management System, Communicator will automatically prompt you to see if you want to trust the CA.

These steps are sufficient to ensure that your client applications will accept connections to take place with the Directory Server, because the clients recognize that the Directory Server's certificate has been issued by a trusted CA.

However, if you also want the Directory Server to authenticate clients using the clients' certificate, you must perform the following additional steps:

  1. On the client system, obtain a client certificate from the CA.

  2. On your client system, install your client certificate.

    Regardless of how you receive your certificate (either in email or on a web page), there should be a link that you click to install the certificate. Click it, and go through the dialog boxes that Communicator presents to you.

    Make sure you record the certificate information that is sent to you in a file. In particular, you must know the subject DN of the certificate because you must configure the server to map it to an entry in the directory. Your client certificate will be similar to:

    -----BEGIN CERTIFICATE-----
    MIICMjCCAZugAwIBAgICCEEwDQYJKoZIhvcNAQEFBQAwfDELMAkGA1UEBhMCVVMx
    IzAhBgNVBAoTGlBhbG9va2FWaWxsZSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX
    aWRnZXQgTWFrZXJzICdSJyBVczEpMCcGA1UEAxMgVGVzdCBUZXN0IFRlc3QgVGVz
    dCBUZXN0IFRlc3QgQ0EwHhcNOTgwMzEyMDIzMzU3WhcNOTgwMzI2MDIzMzU3WjBP
    MQswCQYDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZWN0b3
    -----END CERTIFICATE-----

  3. You must convert the client certificate into its binary format using the certutil utility. To do this:

    1. Download the certutil utility from http://www.mozilla.org/projects/security/pki/nss/tools/.

    2. Run certutil as follows:

      certutil -L -d certdbPath -n userCertName -r > userCert.bin

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

  4. On the server, map the subject DN of the certificate that you obtained to the appropriate directory entry by editing the certmap.conf file.

    This procedure is described in Managing Servers with Netscape Console.

    Note 

    Do not map your certificate-based-authentication certificate to a distinguished name under cn=monitor. If you map your certificate to a DN under cn=monitor, your bind will fail. Map your certificate to a target located elsewhere in the directory information tree.

    Make sure that the verifyCert parameter is set to on in the certmap.conf file. If this parameter is not set to on, Directory Server simply searches for an entry in the directory that matches the information in the  certmap.conf file. If the search is successful, it grants access without actually checking the value of the userCertificate and userCertificate;binary attributes.

  5. In the Directory Server, modify the directory entry for the user who owns the client certificate to add the userCertificate attribute.

    1. Select the Directory tab, and navigate to the user entry.

    2. Double click the user entry, and use the Property Editor to add the userCertificate attribute, with the binary subtype.

      When you add this attribute, instead of an editable field, the server provides a Set Value button.

    3. Click Set Value.

      A file selector is displayed. Use it to select the binary file you created in Step 6.

    For information on using the Directory Server Console to edit entries, refer to Modifying Directory Entries.

You can now use SSL with your LDAP clients. For information on how to use SSL with ldapmodify, ldapdelete, and ldapsearch, refer to Netscape Directory Server Configuration, Command, and File Reference.


Introduction to SASL

Directory Server supports LDAP client authentication through the Simple Authentication and Security Layer (SASL), an alternative to SSL/TLS and a native way for some applications to share information securely.

SASL is a framework, meaning it sets up a system that allows different mechanisms authenticate a user to the server, depending on what mechanism is enabled in both client and server applications.

SASL can also set up a security layer for an encrypted session. Directory Server utilizes the GSS-API mechanism to encrypt data during sessions.

Note 

SASL data encryption is not supported for client connections that use SSL/TLS.


Authentication Mechanisms

Directory Server supports the following SASL encryption mechanisms:

  • EXTERNAL

    The EXTERNAL authentication mechanism is utilized by services such as SSL/TLS. It can be used with public keys for strong authentication.

  • DIGEST-MD5

    DIGEST-MD5 is a mandatory authentication method for LDAPv3 servers. While it is not as strong as public key systems or Kerberos authentication methods, it is preferred over plaintext passwords and does protect against plaintext attacks.

  • Generic Security Services (GSS-API)

    Generic Security Services (GSS) is a security API that is the native way for UNIX-based operating systems to access and authenticate Kerberos services. GSS-API also supports session encryption via function calls that can be used to wrap and unwrap payload data. This allows LDAP clients to authenticate with the server using Kerberos version 5 credentials.

Note 

GSS-API and, thus, Kerberos are only supported on platforms that have GSS-API support.

DIGEST-MD5 and GSS-API are “shared secret” mechanisms. This means that the server challenge the client attempting to bind with a “secret,” such as a password, that depends on the mechanism. The user sends back the response required by the mechanism.


SASL Identity Mapping

When processing a SASL bind request, the server matches, or maps, the SASL userID used to authenticate to the Directory Server with an LDAP entry stored within the server.

If the userID clearly corresponds to the LDAP entry for a person, it is possible to configure the Directory Server to map the authentication DN automatically to the entry DN. Every branch in the directory tree has a default map, and customized maps can be created. During a bind attempt, a randomly selected custom map is applied. If only one user identity is returned, the bind is successful; if none or more than one are returned, then the next custom map is tried, and so on, until the default is tried. If no map works, then the bind fails.

Note 

SASL proxy authorization is not supported in Directory Server; therefore, the server will ignore any SASL authzid supplied by the client.

SASL is configured by entries under a container entry:

dn: cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: sasl

SASL identity mapping entries are children of this entry:

dn: cn=mapping,cn=sasl,cn=config
objectClass: top
objectClass: nsContainer
cn: mapping

Mapping entries contain three attributes, nsSaslMapRegexString, nsSaslMapBaseDNTemplate, and nsSaslMapFilterTemplate. The nsSaslMapping object class sets these identity mapping parameters.

The nsSaslMapRegexString attribute sets variables of the form $1, $2, $3, etc., for bind IDs which are filled into the template attributes during a search. For example, assume the nsSaslMapping is set up as follows:

dn: cn=mymap,cn=mapping,cn=sasl,cn=config
objectclass: top
objectclass: nsSaslMapping
cn: mymap
nsSaslMapRegexString: (.*)@(.*)\.(.*)
nsSaslFilterTemplate: (objectclass=inetOrgPerson)
nsSaslBaseDNTemplate: uid=\1,ou=people,dc=\2,dc=\3

A bind attempt with mconnors@example.com as the regular expression would “fill in” the base DN template with uid=mconnors,ou=people,dc=example,dc=com as the authentication ID, and authentication would proceed from there.

You could also write a broader mapping scheme, such as the following:

objectclass: top
objectclass: nsSaslMapping
cn: mymap2
nsSaslMapRegexString: .*
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=&)

This will match any userId and map to the result of the the subtree search with base ou=People,dc=example,dc=com and filter cn=userId.


Legacy Identity Mapping

Versions of Directory Server before 7.0 did support limited SASL mechanisms, EXTERNAL and DIGEST-MD5.

These mechanisms have simple username-based identies, so the server implements a simple identity mapping scheme using the uid to find the corresponding directory entries.

A user binds with an authentication DN such as uid=bjensen,ou=people,dc=example,dc=com, and the server searches across the entire directory contents, looking for an entry with a corresponding uid. This identity mapping is hard-coded and cannot be changed.

Because Kerberos has more complicated identities (see Realms), the new regular expression-based mapping scheme was added. In processing a bind request, the server first tries to apply any regular expression mapping, if configured. If no match is found, then the server tries to apply legacy mapping.


Configuring SASL Identity Mapping from the Console

  1. In the Console, open the Directory Server.

  2. Open the “Configuration” tab, and select the “Data” node.

  3. In the “Data” node, select the backend you want to edit, such as dc=example,dc=com.

  4. Next, select the root you want to edit, such as o=userRoot.

  5. Select the “SASL Mapping” tab.

  6. To add new SASL identities, select the “Add” button, and fill in the required values.

  7. Before you can modify a SASL identity, you must have saved that identity. Then, you can click on the “Modify” button, and a text box appears with the current values. Change the values you want, and then close and hit “Save.”

  8. To delete a SASL identity, highlight it and hit the “Delete” button. When you hit “Save,” then as dialog box will appear asking if you want to delete the specified identities. Hit “yes” to continue with the save.

  9. Before you hit save, you can undo a modify or delete by selecting the “Reset” button, which will revert to the last saved SASL identities configuration list.


Configuring SASL Identity Mapping from the Command-Line

To configure SASL identity mapping from the command-line, use the ldapsearch utility to configure an identity mapping scheme, such as the following:

objectclass: top
objectclass: nsSaslMapping
cn: mymap2
nsSaslMapRegexString: .*
nsSaslMapBaseDNTemplate: ou=People,dc=example,dc=com
nsSaslMapFilterTemplate: (cn=&)  

This will match any userId and map to the result of the the subtree search with base ou=People,dc=example,dc=com and filter cn=userId. For more information on the ldapsearch utility, see Using ldapsearch.



Configuring Kerberos

Kerberos v5 must be deployed on your system to utilize the GSS-API mechanism for SASL authentication. Table 11-1 summarizes the Kerberos applications supported by various platforms. GSS-API must be enabled as a SASL mechanism in the Directory Server to take advantage of Kerberos services.

Table 11-1   Supported Kerberos Systems

Linux MIT Kerberos version 5
HP-UX 11i HP Kerberos version 2.1
Sun Solaris 9
 SEAM 1.0.1

Note 

Kerberos services are not supported in Windows systems.



Realms

A realm is a set of users and the authentication methods for those users to access the realm. A realm resembles a fully-qualified domain name and can be distributed across either a single server or a single domain across multiple machines. A single server instance can also support multiple realms.

Realms are used by the server to associate the DN of the client in the following form, which looks like an LDAP URL:

uid=<user_name/[server_instance]>,cn=realm,cn=mechanism,cn=auth

Note 

Kerberos systems treat the Kerberos realm as the default realm; other systems default to the server.

Mike Connors in the engineering realm of the European division of example.com would have the following association if he tried to access a different server, such as cyclops:

uid=mconnors/cn=Europe.example.com, cn=engineering,cn=gssapi,cn=auth

Babs Jensen in the accounting realm of US.example.com would not have to specify server_instance:

uid=bjensen,cn=accounting,cn=gssapi,cn=auth

If realms are supported by the mechanism and the default realm was not used, realm must be specified; otherwise, it is omitted. Currently, only GSS-API supports the concept of realms.


Configuring the KDC Server

For Unix and Linux only.

To use GSS-API, the user first obtains a ticket granting ticket (TGT). The ticket and the ticket’s lifetime are parameters in the kdc server configuration in the /etc/krb5/krb5.conf file. See Example.

Note 

The HP server and client are separate packages with their own configuration. The server stores config files in /opt/krb5. The client is classic MIT and uses /etc/krb5.conf. You need to configure both to have a working Kerberos system.


In order to respond to Kerberos operations, the Directory Server requires access to its own cryptographic key. This key is read by the Kerberos libraries that the server calls, via GSSAPI, and the details of how it is found are implementation-dependent. However, in current releases of the supported Kerberos implementations, the mechanism is the same: the key is read from a file called a keytab file. This file is created by the Kerberos administrator by exporting the key from the KDC. Either the system default keytab file (typically /etc/krb5.keytab) is used, or a service-specific keytab file determined by the value of the KRB5_KTNAME environment variable. 

The Directory Server uses the service name ldap. Its Kerberos principal is ldap/host-fqdn@realm. A key with this identity must be stored in the server's keytab in order for Kerberos to work.

For information on setting up the service key, see your Kerberos documentation.

Example

Code Example 11-1 is an example code for a KDC server configured with the company.example.com realm.

Code Example 11-1   Configuring an Example KDC Server
[libdefaults]
         ticket_lifetime = 24000
         default_realm = COMPANY.EXAMPLE.COM
         dns_lookup_realm = false
         dns_lookup_kdc = false
         ccache_type = 1
         forwardable = true
         proxiable = true
         default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc
         default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc
         permitted_enctypes = des3-hmac-sha1 des-cbc-crc
[realms]
  COMPANY.EXAMPLE.COM = {
     kdc = kdcserver.company.example.com:88
     admin_server = adminserver.company.example.com:749
     default_domain = company.example.com
  }
[appdefaults]
  pam = {
    debug = true
    ticket_lifetime = 36000
    renew_lifetime = 36000
    forwardable = true
    krb4_convert = false
 }
[logging]
        default = FILE:/var/krb5/kdc.log
        kdc = FILE:/var/krb5/kdc.log
        admin_server = FILE:/var/log/kadmind.log




Previous
 Contents
 Index
 DocHome Next
© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

 last updated Noember 26, 2004