Chapter 5   Certificate-Based Authentication


Certificate-based authentication is a means of confirming a user's identity before allowing the user access to Delegated Administrator. When you configure Delegated Administration for certificate-based authentication, administrators and end users log in using digital certificates instead of user names and passwords. Certificate-based authentication is part of the Secure Sockets Layer (SSL) protocol.

This chapter provides instructions for setting up certificate-based authentication in iPlanet Delegated Administrator 4.5. It contains the following sections:

• Before You Begin

• Step 1: (Optional) Install and Configure Netscape Certificate Server

• Step 2: Configure Web Server 4.1

• Step 3: Issue Certificates for Delegated Administrator Users

• Step 4: Configure the Directory Server

• Step 5: Configure Delegated Administrator

• Step 6: Restart Web Server

Before You Begin

---

• Before you can begin setting up certificate-based authentication, Directory Server 4.11, Web Server 4.1, and Delegated Administrator 4.5 must be installed. For detailed information, see Chapter 3 "Basic Installation and Configuration" in this manual.

• Do not disable anonymous access to the Delegated Administrator tree. By default, anonymous access is enabled. It must remain enabled in order for certificate-based authentication to work properly.

• You can obtain certificates from a public or third-party Certificate Authority (CA) such as VeriSign^TM. Or you can install a certificate server such as Netscape Certificate Management System and issue your own user certificates.

• To request certificates from a public or third-party CA, see the documentation provided by the CA, and then skip to Step 2. If you want to use Certificate Server Management System to issue your own certificates, continue to the next section, Install and Configure Certificate Management System.

• The examples in this chapter provides instructions for using Certificate Management System 4.1. If you plan to set up certificate-based authentication using Certificate Management System 4.2, then see the documentation that comes with the server for detailed instructions. You can find online documentation for Certificate Management System at this site: http://docs.iplanet.com/docs/manuals/cms.html

Step 1: (Optional) Install and Configure Certificate Management System

---

When you use Certificate Management System to issue client certificates, you can configure the server to automatically copy the certificates to the Directory Server so that authentication can occur. Use the instructions provided in the following sections to:

• Install Certificate Management System

• Configure Certificate Management System to work with the Directory

Installing Certificate Management System

Follow the instructions in the Netscape Certificate Management System 4.1 Installation and Deployment Guide to install Certificate Management System.

When you install Certificate Management System, you specify configuration Directory Server information and related settings for the Certificate Management System.

Configuration Directory Server	Description
Port name and number	Enter the computer host name and port number for the directory server. Example: spock:489
Admin ID	Enter the user ID for the administrator who can access the directory server with full privileges. Example: admin
Admin Port	Enter the port number of the Administration server that manages the Directory Server. Example: 10310
Suffix	Enter the root suffix in the Directory Server. Example: o=siroe.com
Directory Manager DN	Enter the DN of the administrator who has rights to modify directory entries. Example: cn=Directory Manager
Directory Manager Password	Enter the password of the administrator above. The password must be at least 8 characters in length.
Administration domain	Enter the name of the administration domain this directory server belongs to. Example: siroe.com

Certificate Management System	Description
CMS ID	Enter a unique identifier for the CMS server instance. Example: myCA
Instance ID Port number Directory manager DN Directory manager password	Enter LDAP server information for the CMS internal database. Examples: myCA-db 38900 cn=Directory Manager password
Admin ID Full name Organizational unit suffix Organization suffix Admin password	Enter information about the Administrator with access to CMS window. Examples: certadmin CMS Administrator ou=cert o=siroe.com password
SSL admin port SSL agent port SSL end-entity port	Enter CMS configuration settings. Examples: 8200 8100 443
Certificate subject DN	Example: CN=Certificate Manager, OU=cert, O=siroe.com, L=Santa Clara, ST=California, C=US
Single sign-on password	Example: password

Configuring Certificate Management System

When the Certificate Management System is configured to work with the Directory Server, each time you create a new certificate, Certificate Management System automatically copies it to the Directory Server. After configuration is done, you can use the directory-based enrollment feature in Certificate Management System to automatically request, issue, and copy the new certificate into the directory server user entry.

To Configure Certificate Management System to Work with Directory Server:

1. Log in to the CMS window from within Netscape Console.

2. Click the Configuration tab.

3. In the navigation tree, select Certificate Manager, then select LDAP Publishing.
   1. To enable LDAP publishing, check the Enable LDAP Publishing option.

   2. In the Destination section, modify settings as follows:

      Host Name. Enter Delegated Administrator's Directory Server host name. The Certificate Management System uses this name to locate the Directory Serve. The format for the host name must be as follows: <machine_name>.<your_domain>.<domain>. For example, spock.siroe.com.

      Port Number. Enter Delegated Administrator's Directory Server port number. For example, 4890.

      Use SSL communication. If Directory Server is configured for SSL-enabled communication, select this option.

      Directory Manager DN. Enter the DN of the Directory Manager for the Directory Server. For example, cn=directory manager.

      Password. Enter the password of the Directory Manager for the Directory Server.

      Version. Select the LDAP protocol version. For Netscape Directory Server 3.x and later select 3. For earlier versions, select 2.

      Client certificate. No change is required, make sure it is set to Server-Cert, if you checked the "Use SSL communication" option.

      Authentication. Select the authentication type. The choices are "Basic authentication" and "SSL client authentication." If you select "Basic authentication," you must specify the Bind as parameter. If you select "SSL client authentication," you must check the "Use SSL communication" box and identify the certificate that the Certificate Manager must use for SSL client authentication to the directory.

   3. Click Save.

   4. Configure mapping rules for the CA certificate. Within Configuration/Certificate Manager/LDAP Publishing, click the CA Certificate tab.

      Mapping Rules. Click on Configuration and specify the parameters so that the Certificate Management System can locate the CA's entry in the directory.

      filterComps: Enter CN.

      dnComps. Delete the entry so that the value field is empty.

      baseDN. Set this to the Delegated Administrator root. For example, o=ISP.

      Publishing Rules. Leave this as it is; no changes are required.

   5. Configure mapping rules for user certificates so that components match attributes in the directory entry. Within Configuration/Certificate Manager/LDAP Publishing, click the User Certificate tab.

      Mapping Rules. Click on Configuration and specify the parameters so that the Certificate Management System can locate the user entry in the directory.

      filterComps. Enter UID.

      dnComps. Delete the entry so that the value field is empty.

      baseDN. Set this to the Delegated Administrator root. For example, o=ISP.

      Publishing Rules. Leave this as it is; no changes are required.

4. In the navigation tree, select Authentication.
   1. Click Add

   2. Select uidPwdDirAuth.

   3. Click Next, and then set the values of the following configuration parameters:

      Authentication Instance ID. Make sure this field has UserDirEnrollment.

      dnPattern. Set the dnpattern so that it is identical to the user's full DN in the Delegated Administrator base suffix:

      UID=$attr.uid, CN=$attr.CN, E=$attr.mail, OU=people, o=Siroe, o=ISP

      Note that CN and E are optional.

      ldapStringAttributes. Leave this blank.

      ldapByteAttributes. Leave this blank.

      ldap.ldapconn.host. Enter Delegated Administrator's Directory Server host name. For example, spock.siroe.com.

      ldap.ldapconn.port. Enter Delegated Administrator's Directory Server port number. For example, 4890.

      ldap.ldapconn.secureConn. Enter fasle.

      ldap.ldapconn.version. If the directory is based on Directory Server 1.x, enter 2. For Directory Server versions 3.x and later, enter 3.

      ldap.baseDN. Set this to the Delegated Administrator root. For example, o=ISP.

      ldap.minConns. Enter a value between 1 to 3, indicating the minimum number of connections permitted to the Directory Server.

      ldap.maxConns. Enter a value between 3 to 10, indicating the maximum number of connections permitted to the Directory Server.

   4. Click OK.

5. Click Refresh.

6. Restart Certificate Management System.

Step 2: Configure Web Server 4.1

---

Configure Web Server to work with Directory Server so that proxied authentication can occur. In proxied authentication, the Web Server looks up the user certificate in the Directory, and provides user authentication throughout an entire Delegated Administration session. This saves the user from having to re-authenticate before performing each Delegated Administrator operation. Use the instructions provided in the following sections to:

1. Enable SSL

2. Configure Web Server to work with the Directory Server

3. Modify the certmap.conf file

4. Create ACIs that restrict access to Delegated Administrator servlets

5. Define a servlet alias

6. Restart the Web Server

Enabling SSL

Follow the instructions in the Web Server Administrator's Guide to enable SSL. The instructions include sections on:

• Installing a server certificate

• Trusting the new Certificate Authority

• Turning on encryption

Once SSL is enabled for Web Server, you can follow the steps in the next section to Configure Web Sserver to work with Directory Server.

Installing a server certificate on Web Server 4.1

1. If you have not done so, create a trust database for the Web Server Instance.

2. Request a Certificate; this will generate a server certificate request.

3. Request a Server Certificate using the request code. You can use Certificate Management System to do this.

4. After you received the certificate, install it in the certificate database of the Web Server instance.

Trusting the new Certificate Authority

In Certificate Management System

1. Open a web browser window.

2. Access Certificate Management System on SSL end-entity port, for example on port 443.

3. In the Retrieval tab, select Import CA Certificate Chain.

4. Select "Display the CA certificate chain in PKCS#7 for importing into a server."

5. Click Submit. You should see the CA certificate chain.

6. Copy the CA certificate chain to the clipboard, including headers such as:

   ----BEGIN CERTIFICATE---- and

   ----END CERTIFICATE----

In Web Server

1. Access the Web Server instance.

2. In the Security tab select Install Certificate.

3. In the section "Certificate for," select Trusted Certificate Authority CA, and specify the Key Pair File Password.

4. Select Message Text (with headers).

5. Paste the CA certificate chain that you copied into the edit field (make sure headers are included).

6. Click OK. The trusted CA certificate is displayed.

7. Click Add Server Certificate.

8. Restart your Web Server Instance.

Turning on encryption

Turn encryption on for your Web Server Instance. See the Web Server Administrator's Guide for detailed information.

Configuring Web Server to Work with Directory Server

This configuration tells Web Server where to search for user certificates during the authentication process.

To Configure Web Server to work with Directory Server

1. In Web Server, in the General Administration page, click Global Settings.

2. In the Global Settings page, click Configure Directory Service.

3. In the Configure Directory server page, modify the settings as follows:

   Host Name. Enter the host name for the Delegated Administrator Directory Server. For example, spock.

   Port. Enter the port number for the Delegated Administrator Directory Server. For example, 4890.

   Sockets Layer (SSL). If Directory Server is SSL-enabled, select Yes.

   Base DN. Enter the base DN you selected when you installed Delegated Administrator. For example, o=ISP.

   Bind DN (optional). Specify the DN that will use to initially bind. For example, cn=Directory Manager.

   Bind Password (optional). Specify the password for the given base DN.

4. Click Save Changes.

Modifying the certmap.conf File

The file certmap.conf maps certificates to user entries in the Directory. It is stored in the Web Server installation at <server_root>/userdb, for example /usr/netscape/server/userdb. The following is an example of a default certmap.conf entry:

#default:DNComps

#default:FilterComps e, uid

#default:verifycert on

To enable Web Server to work with Directory Server, the entry is changed to the following:

default:DNComps ou, o, o

default:FilterComps uid

default:verifycert on

Restricting Access to Delegated Administrator Servlets

In the Web Server, append an appropriate ACL rule into this file:

<server_root>/httpacl/generated.https-<hostname>.acl

The following is an example of an appropriate ACL rule:

authenticate (user, group) {

database = "default";

method = "ssl";

prompt = "iPlanet Delegated Administrator4.5";

};

allow absolute (read,execute)(user = "all");

deny (all)(user = "anyone");

The important components of this ACL are the resource (uri=/servlet/) and the access control method corresponding to certificate authentication (method="ssl"). In this example, whenever a client request includes uri=/servlet, Web Server requires certificate authentication before the request can be fulfilled.

Defining a Servlet Alias

1. In the file

   <ES Server_Root>/<Server_Instance>/config/servlet.properties

   make sure the following is uncommented:

   servlet alias definition:

   servlet.cauth.code=netscape.nda.servlets.NDACertAuth

   servlet.cauth.args=

   servlet.cauth.preload=true

2. In the file

   <ES Server_Root>/<Server_Instance>/config/rules.properties,

   make sure the following entry within the rules section exists:

   /servlet/cauth=cauth

Restart the Web Server

In order for the changes to become effective, you must restart the Web Server.

Step 3: Issue Certificates for Delegated Administrator Users

---

Follow these steps for each Delegated Administrator user:

1. Request a user certificate from a trusted CA such as VeriSign, or from Certificate Management System.

2. If you are using Certificate Management System 4.1, follow these steps:
   1. Open a web browser window.

   2. Access the Certificate Management System on the SSL end-entity port. The default port number is 443.

   3. Make sure Certificate Management System is configured correctly for directory-based enrollment and publishing.

   4. From the Enrollment tab, select Directory Based.

   5. Specify User ID and Password of the user to who you want to issue a certificate. For example, id=chris, password=bolton.

3. If you've properly configured Certificate Management System to work with Directory Server, the Certificate Management System automatically copies the user certificate it issues to the user's entry in the directory. No action is required on your part here. But if you obtained the certificate from another Certificate Authority (such as VeriSign), you must manually copy the certificate to the directory.

4. In Directory Server, you can verify that certificates have been added to the directory.
   1. Go to the <Directory_server-root>/shared/bin directory where the Directory Server 4.1 is installed. Examples:

      Unix. cd /usr/netscape/server4/shared/bin

      NT. cd \netscape\server4\shared\bin

   2. Use ldapsearch to search for entries with certificates. For example,

      servlet.cauth.code=netscape.nda.servlets.NDACertAuth

      servlet.cauth.args=

      servlet.cauth.preload=true

      usercertificate;binary::

The following is an example of a user's certificate in the directory:

MIICSDCCAbGgAwIBAgIBBDANBgkqhkiG9w0BAQQFADBCMQswCQYD VQQGEwJVUzERMA8GA1UEChMIbmV0c2NhcGUxDDAKBgNVBAsTA21jYzESMBAGA1UEAxMJaHVycmljYW5lMB4XDTk5MDQxMjIxMTc1M1oXDTk5MTAwOTIxMTc1M1owWjERMA8GA1UEChMIc3VuZGFuY2UxEzARBgNVBAoTCkFpcml1cy5jb20xDjAMBgNVBAsTBVVzZXJzMSAwHgYKCZImiZPyLGQBARMQY2hyaXMtQWlyaXVzLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAtMabUpJuab3hd/jqhopuhwNyRVSVYmJTFmN7af/vQgKoitDXNt3oo9xxuvf3Pyo6s4gKfWlKu4oC1dnDWj8fNy1kA5K9/wX/T3lEiDhzK2a7ynlxJQg6NAv6uUkHURfovw92UhqgZxm5yxNbIvFMAKwpbVd+dOU+1KkGlhjkOw8CAwEAAaM2MDQwEQYJYIZIAYb4QgEBBAQDAgCgMB8GA1UdIwQYMBaAFEKI8NkBSTsMWiO9cOlXDU7un/avMA0GCSqGSIb3DQEBBAUAA4GBAD697bhr0g91nqdmoiGM+BixYCB88/rZp0F4jG3a7AIPmPX+z82u++HJISg+UZHfAdk5+C+OhfwAPsrLBCY2RrecRR7U7+/AUPZk8e0IIemaC7AdcsEH4+4N0ONeSxMWikg2UDcPTmNKKNVe13C0t0ynnRs2O0zKxEZk+tJOBJPv

Step 4: Configure the Directory Server

---

Follow the instructions in this section to:

• Create a proxy user account

• Create an ACI for proxied authentication

Creating a Proxy User Account

The proxy user account will be used to bind to the directory for proxied authentication. This user account must be created in a base suffix other than the Delegated Administrator base suffix.

The following is an example of a proxy user account entry:

objectclass: top

objectclass: person

objectclass: organizationalperson

objectclass: inetorgperson

objectclass: proxy

uid: proxy

givenname: Proxy

sn: Auth

cn: Proxy Auth

To Create a Proxy User Account

1. Go to the <Directory_server_root>/shared/bin directory where the Directory Server 4.1 is installed. Examples:

   Unix. cd /usr/netscape/server4/shared/bin

   Windows NT. cd \netscape\server4\shared\bin

2. Use ldapmodify to add the entry. For example:

   "cn=directory manager" -w password -a

   dn: uid=proxy, o=iplanet.com

   objectclass: top

   objectclass: person

   objectclass: organizationalPerson

   objectclass: inetOrgPerson

   uid: proxy

   givenname: Proxy

   sn: Auth

   userpassword: proxypassword

   cn: Proxy Auth

   Ctrl-D (UNIX)

   Ctrl-Z (NT)

Create an ACI for proxied authentication

1. Go to the <Directory_server_root>/shared/bin directory where the Directory Server 4.1 is installed.

2. Use ldapmodify to add an ACI to the base entry. For example:

   "cn=directory manager" -w password

   dn: o=ISP

   changetype: modify

   add: aci

   aci: (target="ldap:///o=ISP")(targetattr="*")(version 3.0;

   acl

   "proxy";allow (proxy) userdn="ldap:///uid=proxy,

   o=iplanet.com";)

   Ctrl-D (UNIX)

   Ctrl-Z (NT)

Step 5: Configure Delegated Administrator

---

Once the proxy user account has been created in the Directory, you must configure Delegated Administrator for proxied authentication. Use the instructions in this section to add the proxy user DN and password to the resources.properties file. In the file

<DelegatedAdmin_root>/nda/classes/netscape/nda/servlet/resources.properties,

uncomment and modify the following entries:

LDAPDatabaseInterface-ldapauthdn=<Proxy Authentication DN>

LDAPDatabaseInterface-ldapauthpw=<Proxy Authentication Password>

For example:

LDAPDatabaseInterface-ldapauthdn=uid=proxy, o=iplanet.com

LDAPDatabaseInterface-ldapauthpw=proxypassword

Step 6: Restart the Web Server

---

For the changes to take effect, restart the Web Server instance.