Previous     Contents     Index     Next     
iPlanet Certificate Management System Installation and Setup Guide



Chapter 15   Setting Up End-User Authentication


iPlanet Certificate Management Server (CMS) provides a customizable authentication component that supports various methods for authenticating end users. This chapter provides an introduction to various parts of Certificate Management System that require authentication and explains how to configure a Certificate Manager and Registration Manager to use specific authentication plug-in modules for authenticating end users during certificate enrollment.

The chapter has the following sections:



Introduction to Authentication

Authentication is the process of verifying the identity of a user that is requesting a service from iPlanet Certificate Management Server (CMS). More specifically, authentication involves acquiring and verifying the values of the configured attributes of the user. For example, the user might be prompted to log in with a user name and password, and then the server would look in a preconfigured database to verify that the user's password was correct.

Service requests to Certificate Management System come from any of the following users:

  • End entities—general users or applications that make certificate issuance, renewal, and revocation requests

  • Administrators—privileged users who connect to the server to do system or server administration tasks

  • Agents—privileged users who connect to the server to do agent operations

This section explains how Certificate Management System identifies and authenticates these users, and it provides details about the various authentication methods supported by the server.

This section has the following sections:


Privileged-User Authentication

For authenticating privileged users, such as administrators and agents, Certificate Management System uses built-in authentication mechanisms.


Authentication of Administrators

When an administrator makes an administrative request to Certificate Management System (from the CMS window within iPlanet Console or from any command-line tool), the server needs to authenticate the administrator before processing the request. To facilitate this, Certificate Management System supports an authentication method that includes user ID- and password-based authentication from the client and SSL server authentication from the server.

Certificate Management System identifies and authenticates users with administrator privileges by checking their user IDs and passwords in its internal database. These are the user IDs and passwords you entered in the internal database when you created these user entries. For details, see Setting Up Administrators.

Figure 15-1 illustrates the authentication process.

Figure 15-1    CMS authentication of a user with administrator privileges

These are the steps shown in Figure 15-1:

  1. An administrator opens iPlanet Console and attempts to log in to the CMS window by entering the user ID and password at the login prompt. The server takes the administrator's user ID and password and binds them to privileged-user entries in its internal database.

  2. If the user ID and password bind successfully to a user entry, authentication succeeds; otherwise, it fails.

    • If authentication fails, the server logs an error message and sends a rejection notification. See Chapter , .

    • If authentication succeeds, the server checks the user's access rights (based on group memberships) to determine whether the user is authorized to perform the requested operation.

    If both authentication and authorization succeed, the server services the request. Otherwise, it rejects the request and logs the reason for the rejection.


    Note Authentication for administrators is hardcoded; it is not configurable.



Authentication of Agents

When an agent makes a request to Certificate Management System (from the appropriate Agent Services interface), the server needs to authenticate the agent before processing the request. To facilitate this, Certificate Management System supports a certificate-based authentication method.

Certificate Management System identifies and authenticates a user with agent privileges by checking the user's SSL client certificate in its internal database. The certificates it checks are the ones you imported and stored in the internal database while creating or modifying the user entry. You create agent users for a CMS instance by adding their client certificates into the internal database and associating them with the corresponding users' identification information; for details, see Setting Up Agents.

When an agent makes a request to perform a privileged operation, the server requests SSL client authentication from the client that the agent has used to connect to the server. The server then uses the successfully SSL client-authenticated certificate to map to internal user entries for further checks. The server checks the certificate's subject name and issuer name against the list of privileged-user certificates stored in its internal database. If the certificate belongs to a privileged user who is authorized (based on group membership) to perform agent operations, the server allows the user to perform the requested operation. Otherwise, the server rejects the request and logs an appropriate message; for details, see , Managing CMS Logs.


Note Authentication for agents is hardcoded; it is not configurable.


Figure 15-2 shows how a Registration Manager authenticates and authorizes a Registration Manager agent.

Figure 15-2    Registration Manager authentication of a user with Registration Manager agent privileges

This example shows these steps:

  1. An agent opens a web browser and enters the URL to the Registration Manager Agent Services interface hosted by the Registration Manager. The server requests the client for SSL client authentication. The client in turn prompts the agent to specify the certificate that it should present to the server for authentication. The successfully SSL client authenticated certificate is presented to the Registration Manager.

  2. Upon receiving the certificate, the Registration Manager performs the following authentication and authorization process:

    • First, it verifies that the certificate exists in its internal database. Next, it verifies that the certificate is a valid client certificate. If the certificate is valid, the Registration Manager proceeds. Otherwise (for example, if the certificate has expired or been revoked or was signed by an untrusted authority), the Registration Manager rejects the request, sends an error message to the agent, and logs a reason for the rejection.

      Note that the Registration Manager verifies the revocation status of the agent certificate if it has been issued by the Certificate Manager to which the Registration Manager is connected to; the Certificate Manager keeps a record of all the certificates it has issued and their current status in its internal database. However, if the agent certificate is issued by any other CA, the Registration Manager cannot verify the revocation status of the certificate; it can only verify that the certificate is valid and that it has been issued by a CA that the Registration Manager trusts. For details on configuring the Certificate Manager or Registration Manager to check the revocation status of its agents' certificates, see Revocation Status Checking of Agent Certificates.

      If the internal database contains an invalid certificate for an agent, the server rejects all requests from that agent. For the server to accept requests from that agent, you would have to replace the agent's invalid certificate in the internal database with a valid one. For details on how to do this, see Changing a Privileged User's Certificate.

    • The Registration Manager reads the user's subject name (in DN form) and the issuer name from the certificate. This combination is unique. It then finds the login name corresponding to this unique combination in its privileged-users list, which is stored in the internal database. If a login name is associated with the certificate, the Registration Manager proceeds. Otherwise, it rejects the request.

      The Registration Manager then checks the group memberships of the login name and the corresponding access rights to determine whether the user is authorized to perform the requested service.

    If both authentication and authorization succeed, the Registration Manager services the request. Otherwise, it rejects the request and logs a reason for the rejection.


End-Entity Authentication

This section provides an overview of how Certificate Management System authenticates end entities during certificate enrollment, renewal, and revocation processes.


Authentication of End Entities During Certificate Enrollment

When an end entity submits a certificate request, a Certificate Manager or Registration Manager's first task is to identify and authenticate the end entity. The server must perform this task before it can register the end entity for certificate issuance. This task includes verifying the end entity's identity based on information the end entity provides and returning enough information about the end entity so that the subject name for the certificate can be constructed.

To cater to a variety of end-entity enrollment scenarios, Certificate Management System supports both manual and automated certificate issuance. For detailed description of authentication methods supported by the Certificate Manager and Registration Manager, see Chapter 1, "Authentication Plug-in Modules" of CMS Plug-Ins Guide.


Authentication of End Users During Certificate Renewal

When an end user submits a certificate renewal request, the first step in the renewal process is for the Certificate Manager or Registration Manager to identify and authenticate the end user. This step includes making sure that the end user's current certificate is either "valid" or "expired" ("revoked" is not acceptable).

Certificate Management System verifies the authenticity of a certificate renewal request by mapping the subject name in the certificate being presented for renewal to certificates in its internal database. The server renews the certificate only if the subject name maps successfully to a certificate in its internal database. If the internal database contains more than one certificate with matching subject name as that the one presented by the end entity for client authentication, the server lists all the matching certificates and expects the end entity to pick one for renewal.

Here are a few things to keep in mind about certificate renewal:

  • The certificate being presented by the end user for renewal must be issued by a Certificate Manager.

  • If the renewal request is processed by a Registration Manager, the end-user certificate presented must be issued by a Certificate Manager that the Registration Manager knows and is connected to; the Registration Manager forwards certificate requests to this Certificate Manager for signing.

  • The certificate being presented by the end user for renewal must be currently valid or must have expired; it cannot have been revoked.

  • The validity period of a renewed certificate is determined by the policy rule explained in "RenewalValidityConstraints Plug-in Module" of CMS Plug-Ins Guide. If the renewal lead time does not permit renewing, the server rejects the renewal request. Also, if the policy is disabled, renewal of certificates fails.

  • If the certificate being presented by the end user has already been renewed, the server displays the URL for downloading the certificate.

    This situation may occur if the end user forgets to download the renewed certificate. It can also happen if the end user maintains two identical certificate databases on two machines, renews the certificate from one machine, and then tries to renew the same certificate from the other machine.


Challenge Password-Based Renewal
A challenge password is a unique, alphanumeric string that the end user specifies when requesting a certificate; the user is expected to keep this password confidential and use it to authenticate to the server when renewing the certificate. When the server issues the certificate, it associates the password with the certificate, stores both the certificate and password in its internal database, and uses them later for authenticating any renewal requests.

If a challenge phrase was set during certificate enrollment, a user can renew the certificate even though he may no longer have access to the actual certificate. This may be useful when, for example, the certificate was stored on a disk that failed. Another example is when the certificate is a server or object-signing certificate which cannot be used for SSL client authentication. In order to renew the certificate, the user must either present the certificate to the server (the web browser will do this automatically if the certificate is installed in it) or he must know the secret challenge phrase and the certificate serial number.

The server verifies the authenticity of a renewal request by mapping the serial number to the list of certificates in its internal database followed by mapping the challenge password specified to the one associated with the matching certificate it detects in the internal database.

The server renews the certificate only if the certificate maps successfully to one or more valid or expired certificates in its internal database. If the server detects only one valid or expired certificate with a matching serial number and challenge password, it automatically renews the certificate. If the server detects more than one valid or expired certificates with matching serial numbers, it lists all those certificates. The user can then select the certificate to be renewed, or renew all certificates in the list.

Here are a few things, to keep in mind about the challenge-password-based renewal:

  • The certificate being presented by the user for renewal must be issued by a Certificate Manager.

  • The user must have requested the certificate using the manual enrollment method—only the default manual enrollment form includes fields for entering the challenge password when requesting a certificate.

  • The user can renew only those certificates that contain the specified serial number with the corresponding challenge password. For example, if there is a mismatch between the challenge password and serial number, the server rejects the renewal request.


Certificate Renewal Form
The End Entity Services interface of the Certificate Manager and Registration Manager includes a default HTML form for renewing end users' certificates. The form is accessible from the Renewal tab as shown in Figure 15-3.

Figure 15-3    Certificate renewal form for end users


The default renewal form is preconfigured for SSL client authentication, enabling end users to renew their personal or client certificates by presenting valid or expired certificates.

If you want to change the form content to suit your organization's requirements, edit the following file:

<server_root>/cert-<instance_id>/web/ee/UserRenewal.html

For details on individual form elements, see the online help available by clicking the Help button on the form. For more information on customizing the form, see CMS Customization Guide.


Authentication of End Users During Certificate Revocation

Certificates can be revoked by administrators, agents, and end users. When an end user submits a certificate revocation request, the first step in the revocation process is for the Certificate Manager or Registration Manager to identify and authenticate the end user. The reason for this is when an end user attempts to revoke a certificate, the server needs to verify that the user is attempting to revoke his or her own certificate, not a certificate belonging to someone else.

Both Certificate Manager and Registration Manager support the following methods of revocation:

  • SSL Client Authenticated Revocation

    This method requires an end user to present a valid or revoked certificate that has the same subject name as the one he or she wants to revoke. Without the certificate, the user won't be able to revoke the certificate.

  • Challenge-Password-Based Revocation

    This method requires an end user to enroll for a personal certificate using the manual enrollment method. The reason for this is, by default, only the manual enrollment form includes fields for entering the challenge password when requesting a certificate. None of the other enrollment forms, for example directory-based or NIS server-based forms, by default allow end users to specify a challenge password.

    You can use the manual-enrollment form (ManUserEnroll.html) as a model and introduce the input fields for entering the challenge password in any of the other end user enrollment forms. Keep in mind that this feature is available for end-user certificates only; the feature is not available for other types of certificates.

    Revoking a certificate using the challenge password is useful in certain situations. For example, if you issue a single certificate to a user and the user is unable to use the certificate due to loss of corresponding key pair, it's not possible for the user to revoke his or her own certificate using the SSL client authenticated revocation method. If the user has a challenge password for the certificate, he or she can use it to revoke the certificate the server maintains in its database.

Forms for both methods are available through the End Entity Services interface (HTTPS only) of the Certificate Manager and Registration Manager; see Certificate Revocation Forms.

Here are a few common points to keep in mind about the automated revocation of end users' certificates:

  • A Certificate Manager can revoke only those certificates that it has issued; it cannot revoke certificates issued by other CAs.

  • If the revocation request is processed by a Registration Manager, it must be connected as a trusted manager to the Certificate Manager that has issued the certificate the user is attempting to revoke; the Registration Manager forwards certificate revocation requests to this Certificate Manager. For information on trusted managers, see Trusted Managers.

  • The certificate the user attempts to revoke must be currently valid or must have expired; it cannot have been already revoked.

  • At the time of revocation, the user can also specify additional details, such as the date of revocation and revocation reason, for each certificate or for the list as a whole.


SSL Client Authenticated Revocation
In an SSL client authenticated revocation method, the server expects the end user to present a certificate that has the same subject name as the one he or she wants to revoke and uses that for authentication purposes. The server verifies the authenticity of a revocation request by mapping the subject name in the certificate being presented for client authentication to certificates in its internal database. The server revokes the certificate only if the certificate maps successfully to one or more valid or expired certificates in its internal database.

After successful authentication, if the server detects only one valid or expired certificate with matching subject name as that of the one presented for client authentication, it revokes the certificate. If the server detects more than one valid or expired certificate with matching subject name, it lists all those certificates. The user can then either select the certificate to be revoked or revoke all certificates in the list.

Here are a few things, in addition to the ones listed on page541, to keep in mind about SSL client authenticated revocation:

  • The certificate being presented by the user for revocation must be issued by a Certificate Manager.

  • If the revocation request is processed by a Registration Manager, the certificate presented for SSL client authentication must be issued by a Certificate Manager that the Registration Manager knows about and is connect to (the Registration Manager forwards certificate requests to this Certificate Manager for signing).

  • The certificate being presented by the user for revocation must be currently valid or must have expired; it cannot have been already revoked.

  • The user can revoke only certificates that contain the same subject name as the one in the certificate presented for authentication.


Challenge-Password-Based Revocation
A challenge password is a unique, alphanumeric string that the end user specifies when requesting a certificate; the user is expected to keep this password confidential and use it to authenticate to the server when revoking the certificate. When the server issues the certificate, it associates the password with the certificate, stores both the certificate and password in its internal database, and uses them later for authenticating any revocation requests.

In the challenge-password-based revocation method, the server expects the end user to specify the serial number of the certificate the user wants to revoke and the challenge password associated with the certificate. The server verifies the authenticity of a revocation request by mapping the serial number to the list of certificates in its internal database followed by mapping the challenge password specified to the one associated with the matching certificate it detects in the internal database.

The server revokes the certificate only if the certificate maps successfully to one or more valid or expired certificates in its internal database. If the server detects only one valid or expired certificate with a matching serial number and challenge password, it automatically revokes the certificate. If the server detects more than one valid or expired certificates with matching serial numbers, it lists all those certificates. The user can then select the certificate to be revoked or revoke all certificates in the list.

Here are a few things, in addition to the ones listed on page541, to keep in mind about the challenge-password-based revocation:

  • The certificate being presented by the user for revocation must be issued by a Certificate Manager.

  • The user must have requested the certificate using the manual enrollment method—only the default manual enrollment form includes fields for entering the challenge password when requesting a certificate.

  • The user can revoke only those certificates that contain the specified serial number with the corresponding challenge password. For example, if there is a mismatch between the challenge password and serial number, the server rejects the revocation request.


Certificate Revocation Forms
The End Entity Services interface of the Certificate Manager and Registration Manager includes default HTML forms for both the SSL client authenticated revocation and challenge-password-based revocation. The forms are accessible from the Revocation tab. Figure 15-4 shows the form that enables end users to revoke their certificates using a challenge password. You can view the form that enables SSL client authenticated revocation by clicking the User Certificate link.

Figure 15-4    Form for SSL client authenticated certificate revocation


If you want to change the forms to suit your organization's requirements, you can edit the following files:

  • ChallengeRevoke1.html (the form that allows challenge password based revocation of client or personal certificates)

  • UserRevocation.html (the form that allows SSL client authenticated revocation of client or personal certificates)

Both the files are located here: <server_root>/cert-<instance_id>/web/ee

For details on individual form elements, see the online help available by clicking the Help button on the form. For more information on customizing the form, see CMS Customization Guide.



Configuring Authentication for End-User Enrollment


To set up a Certificate Manager or Registration Manager to authenticate end users based on a specific criteria, follow these steps:


Step 1. Before You Begin

Before setting up a Certificate Manager or Registration Manager to use a specific authentication method:

  • Determine the authentication module you want to use. To find out about the modules that are installed with the server, see Chapter 1, "Authentication Plug-in Modules" of CMS Plug-Ins Guide. If you want to develop and use a custom plug-in module, be sure to check the tutorials provided in this directory: <server_root>/cms_sdk/cms_jdk/samples/authentication

    • If you decided to use the directory-based authentication module, note the authentication directory credentials, such as the host name, port number, base DN, the user entry to bind as and the corresponding password, the DN pattern to retrieve from the directory to construct certificate subject names, LDAP version number, and minimum and maximum number of connections permitted.

    • If you decided to use the directory- and PIN-based authentication module, note the authentication directory credentials, such as the host name, port number, based DN, the user entry to bind as and the corresponding password, LDAP version number, and minimum and maximum number of connections permitted.

      Next, read Chapter 4 , "PIN Generator Tool" of CMS Command-Line Tools Guide. Determine the options you want to use to generate PINs and construct the command for generating the PINs. Note that the optfile option enables you to put all the arguments in a file (instead of typing the arguments at the command prompt) and then point the tool to read arguments from the file.

    • If you decided to use the NIS server-based authentication module, note the NIS server host name and domain name. If you have an LDAP directory deployed and want to use that for formulating the certificate subject names, note the directory-specific information.

    • If you decided to use the portal authentication module, note the LDAP directory-specific information.

  • Determine the enrollment form you want your users to use. Decide whether you want to customize it.

The next step depends on the authentication module you chose:


Step 2. Set Up the Directory for PIN-Based Enrollment

Complete this step only if you want to configure the server to use the directory- and PIN-based authentication method (with or without PIN removal). Otherwise, skip to the next step.

To set up a directory for PIN-based authentication method:


Step A. Check the Directory for User Entries

Before you run the PIN Generator tool, make sure that the directory you intend to use for generating PINs has been populated with end-user entries that require PINs. It is also a good idea to confirm with that directory's administrator that all pending directory requests have been processed before the PIN Generator starts its operation.


Step B. Update the Directory

By default, the PIN Generator modifies the pin attribute in a directory's user entry. Because this attribute is not part of the standard organizationalPerson, it's likely that the user entries in your directory do not contain the pin attribute. This means, before you run the PIN Generator, you'll need to add the pin attribute to the user entries in your directory—that is, you'll need to create a new object class (named pinPerson) in your authentication directory's schema.

In general, you'll need to update the slapd.user_at.conf file to include the pin attribute and the slapd.user_oc.conf file to include the object-class definition. The modified schema should look similar to this:

attribute pin bin
objectclass pinPerson
   superior organizationalPerson
   allows
      pin

In addition, if you want to make use of the PIN-removal feature—that is, remove a user's PIN from the directory after Certificate Management System successfully authenticates that user and thus prevents the user from enrolling for another certificate—ACIs must be set up on the directory to prevent end users from creating new PINs for themselves. To do this, you'll need to create an entry for a PIN manager user with read-write permission to the pin attribute.

For your convenience, the PIN Generator tool comes with a configuration file, named setpin.conf, which enables you to automate the process of updating the authentication directory with changes required for setting up PIN-based authentication. The configuration file is located in this directory: <server_root>/bin/cert/tools

To make the required schema changes and add an entry for the PIN manager user (using the configuration file):

  1. Go to this directory: <server_root>/bin/cert/tools

  2. Open the setpin.conf file in a text editor.

  3. Follow the instructions outlined in the file and make the appropriate changes.

    Typically, you will need to update the Directory Server's host name, Directory Manager's bind password, and PIN manager's password.

  4. Run the setpin command with its optfile option pointing to the setpin.conf file (setpin optfile=setpin.conf).

    The tool modifies the schema with a new attribute (by default, pin) and a new object class (by default, pinPerson), creates a pinmanager user, and sets the ACI to allow only the pinmanager user to modify the pin attribute.

    If the tool is able to update the directory with all the changes, you should see a status-update message, similar to the sample shown below:


    Adding attribute: ( pin-oid NAME 'pin' DESC 'User Defined
    Attribute' SYNTAX '1.3.6.1.4.1.1466.115.121.1.5' SINGLE-VALUE )
    .. successful

    Adding objectclass: ( pinPerson-oid NAME 'pinPerson' DESC 'User
    Defined ObjectClass' SUP 'top' MUST ( objectclass ) MAY ( aci $
    pin )
    .. successful

    Adding user: cn=pinmanager,o=siroe.com
    .. successful

    modifying ACI for: ou=people,o=siroe.com
    .. successful



Step C. Prepare the Input File

This step is optional.

If you want to generate PINs for specific user entries or want to provide your own PINs, use an input file (to provide the tool with such information). For information on constructing an input file, check the PIN Generator documentation.


Step D. Run the Command Without the Write Option

Run the setpin command without the write option. Be sure to include the output option and bind to the directory as the PIN manager user.

The tool will write PINs to the specified output file; no changes are made to the directory yet. This will give you the opportunity to check the PINs (by looking at the output file) before updating the directory.

To run the command:

  1. Open a terminal window.

  2. Go to this directory: <server_root>/bin/cert/tools

  3. Run the setpin command with the appropriate arguments; be sure to point the optfile option to the file you've created (and not to the setpin.conf file).


Step E. Check the Output File

Check the output file to be sure it contains PINs for your users; the output should look similar to the one specified in PIN Generator documentation.

Next, verify that the tool has assigned PINs to the correct users and that the PINs conform to the length and character-set restrictions you specified. If the output isn't what you want, run the command again with appropriate arguments. Repeat the process until the output file shows the results you want.


Step F. Run the Command Again with the Write Option

When you are sure about the results, run the command again (with exactly the same arguments) with the write option and the output option. The tool stores the hashed PINs in the directory. For information on how PINs are stored in the directory, see section "How PINs Are Stored in the Directory" of the PIN Generator tool documentation.

Use the output file for delivering PINs to users after you complete setting up the required authentication method; see Step 9. Deliver PINs to End Users.


Step 3. Enable the AttributePresentConstraints Policy

This step is required for PIN-based enrollment with PIN removal only in certain deployment scenarios. Here's some information that will help you decide whether you need to enable this policy.

In the password and PIN-based enrollment method, users enroll for a certificate using their directory user ID, password and PIN. After a PIN has been used to successfully authenticate a user, the Certificate Manager calls the PinRemovalListener module. This module removes the PIN from the authentication directory when the Certificate Manager issues the requested certificate.

Note that listeners in Certificate Management System are objects which register themselves as interested in knowing about certain events—for example, change in the state of a request—and carry out a specific task. For more information on listeners, check the samples directory:

<server_root>/cms_sdk/cms_jdk/samples/listeners

Once the PIN is removed from the authentication directory, it prevents the user from enrolling for another certificate.

The above mentioned process works smoothly if a Certificate Manager or Registration Manager is configured to use the master directory for authenticating users. The process may not work smoothly in deployment scenarios that involve replicated directories. In these scenarios, you need to use the Attribute Present Constraints policy to verify that the PIN has been removed from the directory. Here's an example of such a scenario:

A Registration Manager acts as an enrollment authority, passing authenticated certificate requests to a Certificate Manager; the users have no direct interaction with the Certificate Manager. The Certificate Manager (CA) and the master corporate directory are behind the firewall. The Registration Manager and a replica of the corporate directory are outside the firewall. The Certificate Manager is configured to communicate with the master corporate directory. The Registration Manager has read-only permission to the replicated corporate directory and it uses the directory for authenticating end entities. Both the Certificate Manager and Registration Manager are configured for password and PIN-based enrollment with the PIN removal feature turned on. The master corporate directory is configured to update its replica (outside the firewall) every 10 minutes.

When a user enrolls for a certificate using the End Entity Services interface of the Registration Manager, it authenticates the user against the replica of the corporate directory. If the user presents a valid user ID, password, and PIN, the Registration Manager authenticates the user successfully and forwards the request to the Certificate Manager. As the Registration Manager is configured for PIN-based enrollment with PIN removal, it attempts to remove the PIN from the replicated directory, but it can't as it has no write permission to the replicated directory; the PIN is still around.

When the Certificate Manager processes the request forwarded by the Registration Manager, it calls the PinRemovalListener module, which in turn removes the PIN from the master corporate directory when the Certificate Manager issues the certificate. (The Certificate Manager sends the certificate to the Registration Manager, which in turn sends it to the user.)

Although the Certificate Manager has removed the PIN from the master directory, the replicated directory still has the PIN, because the update hasn't occurred. In the meantime, the user may enroll again successfully (from the Registration Manager) for another certificate and receive it from the Certificate Manager.

The Attribute Present Constraints policy enables you to prevent users from successfully enrolling for multiple certificates from the Registration Manager during the time interval between directory updates. If you configure the Certificate Manager to use this policy to check the master directory for PINs before issuing certificates, successive certificate requests would fail because the PIN has been removed from the master directory. This way, even if the Registration Manager authenticates successive requests, the Certificate Manager rejects them, thus ensuring that a user has only one certificate.

If you are not familiar with the Attribute Present Constraints policy, see section "AttributePresentConstraints Plug-in Module" in Chapter 3, "Constraints Policy Plug-in Modules" of CMS Plug-Ins Guide.

Note that unlike some of the other policy rules, Certificate Management System does not create an instance of the Attribute Present Constraints policy rule during installation. If you created this rule after installation, you can configure the server to use that rule. The instructions below explain how to create a new rule:

  1. Log in to the CMS window for the Certificate Manager (see Logging In to the CMS Window).

  2. Select the Configuration tab.

  3. In the navigation tree, select Certificate Manager, and then select Policies.

    The Policy Rules Management tab appears. It lists currently configured policy rules.

  4. Click Add.

    The Policy Plugin Implementation window appears.

  5. Select AttributePresentConstraints and click Next.

    The Policy Rule Editor window appears. It lists the configuration information required for this policy rule.

  6. Enter the appropriate information.

  7. Click OK to save your configuration.

    You are returned to the Policy Rules Management tab. If required, click the Reorder button and order the rules as appropriate. For details, see Step 5. Reorder Policy Rules.


Step 4: Add an Authentication Instance

Adding an authentication instance to the CMS configuration involves creating a new instance of an already registered plug-in module, assigning a unique name or ID to the instance, and entering appropriate values for the parameters that define the plug-in you want to create an instance of.

When naming an authentication instance (or rule), be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type My_Auth_Rule or MyAuthRule as the instance name, but not My Auth Rule.

Also note that when you add an authentication instance, the CMS configuration is updated with authentication-specific information only. The server does not associate the authentication instance you added with any of the end-user enrollment forms—that is, the end-user servlets that should use this authentication instance are not configured yet. You make this association by manually embedding the authentication instance name in the enrollment forms.

By default, the enrollment forms include authentication instance names listed in Table 15-1. Note that the authentication instances are not created by default; only the instance names are embedded in the forms for your convenience. If you create authentication instances with the default names, you can skip the step (Step A. Associate the Authentication Instance With the Enrollment Form) that explains how to update an enrollment form to associate it with the name of an authentication instance.


Table 15-1    Default authentication instance names embedded in end user enrollment forms  

Enrollment form (filename)

Authentication instance name

Certificate-based enrollment for dual certificates
(CertBasedDualEnroll.html)  

UserDirEnrollment  

Certificate-based enrollment for encryption certificates
(CertBasedEncryptionEnroll.html)  

UserDirEnrollment  

Certificate-based enrollment for single certificates
(CertBasedSingleEnroll.html)  

UserDirEnrollment  

Directory-based enrollment
(DirUserEnroll.html)  

UserDirEnrollment  

Directory- and PIN-based enrollment
(DirPinUserEnroll.html)  

PinDirEnrollment  

NIS server-based enrollment
(NISUserEnroll.html)  

NISAuth  

Portal enrollment
(PortalEnrollment.html)  

PortalEnrollment  

Figure 15-5 shows the default directory-based enrollment form configured to use an authentication instance named UserDirEnrollment.

Figure 15-5    Authentication information in the default directory-based enrollment form


For information on locating and customizing the default end-entity forms, see CMS Customization Guide.

To add an authentication instance to the CMS configuration:

  1. In the CMS window, select the Configuration tab.

  2. In the navigation tree, select Authentication.

    The right pane shows the Authentication Instance tab, which lists any currently configured authentication instances.

  3. Click Add.

    The Select Authentication Plugin Implementation window appears. It lists the currently registered authentication plug-in modules.

  4. Select a plug-in module.

    The following choices are the ones provided by default with Certificate Management System. If you have registered any custom authentication plug-in modules, they too will be available for selection.

    UidPwdDirAuth. Select this if you want to use the directory-based authentication module.

    UidPwdPinDirAuth. Select this if you want to use the directory- and PIN-based authentication module (with or without PIN removal). To configure Certificate Management System for PIN-based enrollment method, you must have completed Step 2. Set Up the Directory for PIN-Based Enrollment.

    NISAuth. Select this if you want to use the NIS server-based authentication module.

    SSOBasedAuthentication. Select this if you want to use the Single Sign-On authentication token that come with Directory Server Access Management Edition (DSAME) 6.0.

    PortalEnroll. Select this if you want to use the portal authentication module.

    For the purposes of this instruction, assume that you selected UidPwdPinDirAuth.

  5. Click Next.

    The Authentication Instance Editor window appears. The Authentication Instance ID field shows the default instance name embedded in the associated enrollment form (see Table 15-1). The Authentication Plugin ID field shows the module you've chosen. The remaining fields list the configuration information required for this authentication instance.

  6. If you don't want to use the default instance name, in the Authentication Instance ID field, type a unique name for this instance that will help you identify it.

    For the name, be sure to use an alphanumeric string with no spaces. If you chose to use a different name, be sure to edit the default name in the enrollment form in the next step, Step 5. Set Up the Enrollment Interface.

  7. Fill in values for the remaining parameters.

  8. Click OK.

    The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. Don't restart the server yet; you can do this after you've made all the required changes.


Step 5. Set Up the Enrollment Interface

This step explains how to customize the end-entity interface for the enrollment method you've chosen for your users.


Step A. Associate the Authentication Instance With the Enrollment Form

You can skip this step if, in the previous step, you chose the default instance name suggested in Table 15-1. Otherwise, you must edit the enrollment form to associate the instance you added because Certificate Management System relies on the authentication instance name embedded in the enrollment form to determine the authentication method.

For the new authentication instance to work with end-entity enrollment forms, you must update the appropriate forms, as follows:

  1. In the CMS host system, go to this directory: <server_root>/cert-<instance_id>/web/ee

  2. Locate the file that corresponds to the authentication module you chose in Step 4: Add an Authentication Instance; use Table 15-1 for guidance.

  3. Open the file in a text editor.

  4. Locate the attribute that associates the authentication instance with the enrollment form.

    In the default enrollment forms, locate this line:

    <INPUT TYPE="HIDDEN" NAME="authenticator" VALUE="myAuthMgr">

    In the custom enrollment form, be sure to include the following line, and replace myAuthMgr with the name of the authentication instance you added.

    <INPUT TYPE="HIDDEN" NAME="authenticator" VALUE="myAuthMgr">

  5. Check the value assigned to authenticator attribute (the VALUE= field). Make sure that it is same as the name or ID you assigned to the authentication instance you created in Step 5. If it is different, replace it with the name of the authentication instance. For example, if you used test_auth as the instance name, the edited line should look like this:

    <INPUT TYPE="HIDDEN" NAME="authenticator" VALUE="test_auth">

  6. Save your changes and close the file.


Step B. Customize the Form

You can make any other changes to meet your organization's requirements.


Step C. Hook Up the Certificate-Based Enrollment Form

This step is required only if you want to use any of the certificate-based enrollment forms.

As explained in the "Certificate-Based Enrollment" section in Chapter 1, "Authentication Plug-in Modules" of CMS Plug-Ins Guide, Certificate Management System provides three forms for certificate-based enrollment:

  • CertBasedDualEnroll.html

  • CertBasedEncryptionEnroll.html

  • CertBasedSingleEnroll.html

By default, the form named CertBasedDualEnroll.html is hooked up to the Enrollment tab of the end-entity interface. You can replace this form with either of the other two forms, CertBasedEncryptionEnroll.html and CertBasedSingleEnroll.html; you can do this by uncommenting the script relevant to either of the forms in the index file and by commenting out the script for CertBasedDualEnroll.html—thus, effectively unhook the old one and hook the new one.

To enable any of the certificate-based enrollment forms, follow these steps:

  1. In the CMS host system, go to this directory:

    <server_root>/cert-<instance_id>/web/ee

  2. Locate the index.html file.

  3. Open the file in a text editor.

  4. Follow instructions as appropriate:

    If you want to enable the CertBasedDualEnroll.html form, search for CertBasedDualEnroll. You should find a block of script like the following:

       count++;
       }
       if (http != 'true') {
          // this one is directory based, cert-based
       if ( isAuthMgrEnabled("UidPwdDirAuth") ) {
       item = 'certBasedDualEnroll';
       menuItems[count] = top.EnrollMenu[count] =
          new menuItem(item, 'CertBasedDualEnroll.html','Certificate');

    If you want to enable the CertBasedEncryptionEnroll.html form, search for CertBasedEncryption. You should find a block of script like the following:

       count++;
       }
       // item = 'certBasedEncEnroll';
       // menuItems[count] = top.EnrollMenu[count] =
       // new menuItem(item, CertBasedEncryptionEnroll.html',
       // 'Certificate');

    Uncomment the lines and then add lines for using the automated enrollment module you configured the server with. Your edited lines should look similar to this:

       count++;
       }
       if (http != 'true') {
          // this one is directory based cert-based
       if ( isAuthMgrEnabled("UidPwdDirAuth") ) {
          item = 'certBasedEncEnroll';
          menuItems[count] = top.EnrollMenu[count] =
           new menuItem(item, 'CertBasedEncryptionEnroll.html',
              'Certificate');

    If you want to enable the CertBasedSingleEnroll.html form, search for CertBasedSingle. You should find a block of script similar to this:

       count++;
       }
       // item = 'certBasedSingleEnroll';
       // menuItems[count] = top.EnrollMenu[count] =
       // new menuItem(item, 'CertBasedSingleEnroll.html',
       // 'Certificate');

    Uncomment the lines and then add lines for using the automated enrollment module you configured the server with. Your edited lines should look like these:

       count++;
       }
       if (http != 'true') {
          // this one is directory based cert-based
       if ( isAuthMgrEnabled("UidPwdDirAuth") ) {
          item = 'certBasedSingleEnroll';
          menuItems[count] = top.EnrollMenu[count] =
             new menuItem(item, 'CertBasedSingleEnroll.html',
              'Certificate');

  5. Make sure to comment out lines for any unused options.

  6. If you're using any of the default modules, except for the one provided for the directory-based enrollment (UidPwdDirAuth), edit the following line to replace UidPwdDirAuth with the name of the module you're using.

    if ( isAuthMgrEnabled("UidPwdDirAuth") ) {

  7. By default, a link named Certificate will be created under the Browser section. If you want to rename the link, replace Certificate in the following line with the new name:

    new menuItem(item, 'CertBasedDualEnroll.html', 'Certificate');

  8. Save your changes and close the file.


Step D. Remove Unwanted Enrollment Options

This step is optional.

By default, the Enrollment tab of the end-entity interface shows just one link, named Manual, under the Browser section. The Manual link opens a form that enables end users to request certificates manually. When you enable automated enrollment, that is, when you create an instance of any of the automated enrollment modules, a link for the corresponding form is automatically created under the Browser section. For example, if you create an instance of the directory-based authentication module, you will notice a new link named Directory under the Browser section.

If you don't want your end users to see the manual enrollment option, you can remove it from the Enrollment tab altogether. The steps below explain how to remove the Manual link from the Browser section of the Enrollment tab:

  1. In the CMS host system, go to this directory:

    <server_root>/cert-<instance_id>/web/ee

  2. Locate the index.html file.

  3. Open the file in a text editor.

  4. Locate the initEnrollMenu function (the function initEnrollMenu() line).

  5. Remove or comment out lines that correspond to the Manual enrollment form.

    count++;
    item = 'manuser';
    menuItems[count] = top.EnrollMenu[count] =
    new menuItem(item, 'ManUserEnroll.html', 'Manual');

  6. Save your changes and close the file.

  7. Open a browser window.

  8. Go to the end-entity interface and verify your changes.


Step 6. Enable End-Entity Interaction

You can configure end-entity interaction with a Certificate Manager or a Registration Manager, or with both. End entities cannot interact with a Data Recovery Manager directly; they must interact through a Certificate Manager or Registration Manager. By default, the Certificate Manager is configured for end-entity interaction; the Registration Manager is not configured for end-entity interaction.

Depending on the subsystem you're configuring, follow the instructions in Enabling End-Entity Interaction with a Certificate Manager or in Enabling End-Entity Interaction with a Registration Manager.


Enabling End-Entity Interaction with a Certificate Manager

To enable end-entity interaction with a Certificate Manager:

  1. In the CMS window, select the Configuration tab.

  2. In the navigation tree, select Certificate Manager.

    The General Setting tab appears.

  3. In the Web Access section, check the "Enable end-entity interaction" option if you want end entities to be able to interact with the selected Certificate Manager via the HTTPS port; leave it unchecked to disable end-entity interaction with the server.

    Note that if you disable end-entity interaction, the Network tab still shows the HTTPS port and allows you to configure it (see Configuring Port Numbers). However, you should know that the server ignores this port.

  4. In the Certificate Validity section, check the "Override validity nesting requirement" option, if you want the Certificate Manager to issue certificates with validity periods beyond that of its CA signing certificate; see CA Signing Key Pair and Certificate).

    If you leave the box unchecked and if the Certificate Manager (CA) finds a request with validity period extending beyond that of its CA signing certificate, it automatically truncates the validity period to end on the day the CA signing certificate expires. For example, if the CA signing certificate expires on June 10, 2004, any enrollment or renewal request with validity period beyond June 10, 2004 will have validity period truncated to end on June 10, 2004.

    Validity periods of certificates during enrollment is determined by the policy explained in ValidityConstraints plug-in module. Similarly, validity periods of certificates during renewal is determined by the policy explained in RenewalValidityConstraints plug-in module. Both the modules are explained in CMS Plug-Ins Guide.

  5. In the Certificate Serial Number section, specify the serial number range for certificates issued by this Certificate Manager. The server assigns the serial number you enter in the "Next serial number" to the next certificate it issues and the number you enter in the "Ending serial number" to the last certificate it issues.

    The serial number range enables you to deploy multiple CAs, balancing the number of certificates each CA issues. Note that the combination of an issuer name and a serial number uniquely identifies a certificate. To ensure that two distinct certificates issued by the same authority doesn't contain the same serial number, make sure the serial number range does not overlap among cloned CAs. (For information on cloning CAs, Cloning a Certificate Manager.)

    Also note that when a CA exhausts all its serial numbers, you can revive it by changing the values in the "Next serial number" and "Ending serial number" fields, followed by restarting the Certificate Manager.

  6. In the Default Signing Algorithm section, select the signing algorithm the Certificate Manager should use for signing certificates. The choices are "MD2 with RSA," "MD5 with RSA," and "SHA1 with RSA," if the CA's signing key type is RSA and "SHA1 with DSA," if the CA's signing key type is DSA.

    Note that the signing algorithm specified in the Certificate Manager's policy configuration overrides the algorithm you select here. For information on a Certificate Manager's policy configuration, see SigningAlgorithmConstraints policy plug-in module in CMS Plug-Ins Guide.

  7. To save your changes, click Save.

    The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.


Enabling End-Entity Interaction with a Registration Manager

To enable end-entity interaction with a Registration Manager:

  1. In the CMS window, select the Configuration tab.

  2. In the navigation tree, select Registration Manager.

    The General Setting tab appears.

  3. In the Web Access section, check the "Enable end-entity interaction" option if you want end entities to be able to interact with the selected Registration Manager via the HTTPS port; leave it unchecked to disable end-entity interaction with the server.

    Note that if you disable end-entity interaction, the Network tab still shows the HTTPS port and allows you to configure it (see Configuring Port Numbers). However, you should know that the server ignores this port.

  4. To save your changes, click Save.

    The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.


Step 7. Turn on Automated Notification

Both the Certificate Manager and the Registration Manager can send certificate-issuance notification to end users. For details on turning this feature on, see , Setting Up Automated Notifications.


Step 8. Test Your Authentication Setup

To test whether your end users can successfully enroll for a certificate using the authentication method you've set up:

  1. Open a web browser window.

  2. Go to the end-entity interface for the enrollment authority you configured.

    The default URL is as follows: https://<hostname>:<end_entity_HTTPS_port> or
    http://<hostname>:<end_entity_HTTP_port>

  3. In the Enrollment tab, open the enrollment form you customized.

  4. Fill in all the values and submit the request.

  5. The client prompts you to enter the password for your key database.

  6. When you enter the correct password, the client generates the key pair.

    Do not interrupt the key-generation process. Upon completion of the key generation, the request is submitted to the server for certificate issuance. The server subjects the request to the currently configured policy rules and issues the certificate only if the request passes all the policy rules.

    Upon receipt of a notification about the certificate issuance, install the certificate in your browser.

  7. Verify that the certificate is installed in the browser's certificate database; for example, in Communicator you can open the Security Info window and verify that the certificate is listed in there.

  8. If you've set up the directory- and PIN-based authentication with PIN removal, reenroll for another certificate using the same PIN. Your request should get rejected.

  9. If you've set up the portal enrollment, verify that an entry for the user is created in the directory. For example, you can point your browser to the portal directory and find out if an entry for the user for whom you requested the certificate exists.

    In the URL field, type
    ldap://<host_name>:<port>/<base_dn>??sub?(uid=<user_id>), substituting <host_name> with the fully qualified host name of the Directory Server, <port_number> with the port number at which the Directory Server is listening to authentication requests from the Certificate Manager <base_dn> with the DN to start searching for the user's entry, and <user_id> with the ID of the user for whom you requested the certificate.

    For example, if the directory host name is corpDirectory, port number is 389, base DN is O=siroe.com, and user's ID is jdoe, the URL would look like this:

    ldap://corpDirectory:389/O=siroe.com??sub?(uid=jdoe)

    In the resulting page, look for the user's credentials and verify that they match what you specified in the enrollment form. If you've configured Certificate Management System to publish certificates to the same directory (, Setting Up LDAP Publishing), you will be able to see the certificate-related information; it typically includes information such as the owner of the certificate, the CA that has issued the certificate, the serial number, the validity period, and the certificate fingerprint.


Step 9. Deliver PINs to End Users

This step is applicable for directory- and PIN-based authentication with or without PIN removal.

After you have confirmed that the PIN-based enrollment works (as it should), deliver the PINs to users so they can use them during enrollment. To protect the privacy of PINs, be sure to use a secure, out-of-band method for delivery. Here are a few suggested delivery methods:

  • Encrypted email (S/MIME)—if your company has S/MIME mail set up, you can deliver PINs to users by encrypted mail.

  • Mail—you can mail PINs to users, for example along with their pay stubs or slips.

  • Personal delivery—you can arrange a secure means of delivering the password to the user, or ask the user to collect it from you in person.



Managing Authentication Instances

This section explains how to use the CMS window to do the following:

For information on adding or changing authentication-specific information in the configuration file, see Changing the Configuration by Editing the Configuration File.


Deleting an Authentication Instance

You can delete an authentication instance that you no longer need from the CMS configuration. If you delete an authentication instance, end users will fail to enroll for certificates using the associated enrollment form. If you want the form to work with another authentication instance, you must make the appropriate changes to the form; see Step 5. Set Up the Enrollment Interface.

To delete an authentication instance from the CMS configuration:

  1. Log in to the CMS window (see Logging In to the CMS Window).

  2. Select the Configuration tab.

  3. In the navigation tree, click Authentication.

    The right pane shows the Authentication Instance tab, which lists currently configured authentication instances.

  4. In the Instance Name list, select the instance you want to delete and click Delete.

  5. When prompted, confirm the delete action.

    The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.


Modifying an Authentication Instance

You can modify an authentication instance by editing its configuration parameter values; you cannot edit the name of an instance. To change the name of an instance, you need to create a new instance exactly like the instance you want to rename, except with a new name, and delete the old instance. For details, see Step 4: Add an Authentication Instance.

When you modify an authentication instance, the CMS configuration is updated to include the modifications. Because you are not changing the name of the authentication instance, you do not have to make any changes to the end-user servlet configuration.

To modify an authentication instance in the CMS configuration:

  1. Log in to the CMS window (see Logging In to the CMS Window).

  2. Select the Configuration tab.

  3. In the navigation tree, click Authentication.

    The right pane shows the Authentication Instance tab, which lists configured authentication instances.

  4. In the Instance Name list, select the instance you want to modify and click Edit.

    The Configure Authentication Instance Parameters window appears, showing the current configuration of this instance.

    For the purposes of completing these instructions, assume you selected UserDirEnrollment.

  5. Make changes as appropriate. If you need description for any of the parameters, click the Help button or check the CMS Plug-Ins Guide.

  6. Click OK.

    The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.



Managing Authentication Plug-in Modules

This section explains how to use the CMS window to do the following:

For information on adding or changing authentication-specific information in the configuration file, see Changing the Configuration by Editing the Configuration File.


Registering an Authentication Module

You can register custom authentication plug-in modules from the CMS window. Registering a new authentication module involves specifying the name of the module and the full name of the Java class that implements the authentication interface. For example, you can add a Java class, named as follows, that implements an authentication module:

com.iplanet.certsrv.authentication.ssnAuth

Before registering an authentication module, be sure to put the Java class for the module in the classes directory. If you need help, check the tutorials installed in this directory: <server_root>/cms_sdk/cms_jdk/samples/authentication

To register an authentication module in the CMS authentication framework:

  1. Log in to the CMS window (see Logging In to the CMS Window).

  2. Select the Configuration tab.

  3. In the navigation tree, click Authentication, and in the right pane, click the Authentication Plugin Registration tab.

    The tab lists modules that are already registered.

  4. Click Register.

    The Register Authentication Plugin Implementation window appears.

  5. Specify which module you want to register:

    Plugin name. Type a name for the module.

    Class name. Type the full name of the class for this module—that is, the path to the implementing Java class. If this class is part of a package, be sure to include the package name. For example, if you are registering a class named NISAuth and if this class is in a package named com.mycompany, type com.mycompany.NISAuth.

  6. Click OK.

    The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.


Deleting an Authentication Module

You can delete an authentication plug-in module that you no longer need by using the CMS window. Before deleting a module, be sure to delete all the instances that are based on this module; see Deleting an Authentication Instance. You should also update the appropriate end-entity enrollment forms.

To delete an authentication module from the CMS authentication framework:

  1. Log in to the CMS window (see Logging In to the CMS Window).

  2. Select the Configuration tab.

  3. In the navigation tree, click Authentication, and in the right pane, click the Authentication Plugin Registration tab.

    The tab lists the currently registered modules.

  4. In the Plugin Name list, select the module you want to delete and click Delete.

  5. When prompted, confirm the delete action.

    The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.


Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated October 07, 2002