Chapter 11 Configuring Authentication for End Entities

Netscape Certificate Management System (CMS) provides a customizable authentication subsystem that supports various mechanisms for authenticating end entities. This chapter explains how to configure Certificate Management System to use specific authentication plug-in modules for authenticating end entities during certificate enrollment. The chapter also shows how end-entity authentication plug-in implementations and configured instances appear in the configuration file.

• Authentication Management
• Managing Authentication Instances
• Managing Authentication Plug-in Modules

• By making changes to the authentication-specific parameters from the CMS window, explained in "Authentication Management from the CMS Window"
• By editing the parameters in the configuration file, explained in "Authentication Parameters in the Configuration File"

Figure 11.1 shows the CMS window, which provides the required user interface to support authentication management for end entities.

• Configuration of currently registered authentication plug-in modules
• Registration of new (custom) authentication plug-in modules

The Authentication Instance tab lists the currently configured authentication instances, so that you can manage them at a single place. From this tab you can perform the following operations:

Delete. The delete operation allows you to remove unwanted authentication instances from the CMS configuration. For instructions on deleting authentication instances, see "Deleting an Authentication Instance".

Edit/View. The edit operation allows you to view and modify the configuration parameter values of currently configured authentication instances. You modify the parameter values with the help of the authentication instance editor (see "Authentication Instance Editor"). For instructions on modifying authentication instances, see "Modifying an Authentication Instance".

Authentication Instance Editor

The authentication instance editor is designed to be generic. Its simple graphical interface enables you to create new instances and modify the configuration of an individual authentication instance. When you are adding a new instance, the editor shows the configuration parameters pertaining to the plug-in module you selected. When you are modifying an instance, the editor shows the configuration parameters pertaining to the instance you selected.

The Authentication Plugin Registration tab lists the currently registered authentication plug-in implementations for the selected CMS instance and gives you access to the window from which you can register new authentication plug-in modules. On this tab you will find the names of registered plug-in modules listed on the left and the path to the Java class that implements the plug-in module listed on the right.

When you save the changes, Certificate Management System loads the authentication plug-in implementation and displays it in the list of registered plug-ins. For instructions on registering new authentication plug- in modules, see "Registering an Authentication Plug-in Module".

Authentication Plug-in Registration Editor

The authentication plug-in registration editor allows you to register new authentication plug-in modules in the CMS authentication framework. Registering a new authentication plug-in module involves specifying the name of the plug-in module and the full name of the Java class that implements the authentication interface (implementation must be on the class path).

The sample shown in Figure 11.2 illustrates how authentication-specific information appears in the configuration file. Keep the following points in mind:

• All authentication-specific information, such as registered authentication implementations and configured instances, appears in the Authentication section of the configuration file. See the example shown in Figure 11.2 below.
• Each registered authentication plug-in module is identified by its implementation name.
• Each configured instance of an authentication implementation is identified by the name you specified when creating it.
• You can create multiple instances out of an implementation; each instance must have a unique name. For details, see "Authentication Plug-in Implementation and Instance".
• The name of the authentication instance must be used in enrollment forms to identify the authentication manager. For details, see "Adding an Authentication Instance".

Figure 11.2 End-entity authentication-specific information in the CMS configuration file

Authentication managers are implemented as Java classes, which are then registered with Certificate Management System as plug-ins. You can use a given implementation of an end-entity authentication plug-in module and configure multiple instances of it. Each instance must have a unique name (an alphanumeric string with no spaces) and can contain different input parameter values to apply to different end-entity enrollment requests. In other words, a given end-entity authentication implementation can be shared by multiple configurations. You can also distinguish the applicability of configured instances by including appropriate instance names.

• Adding an Authentication Instance
• Deleting an Authentication Instance
• Modifying 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 (an alphanumeric string with no spaces) to the instance, and entering appropriate values for the parameters that define the plug-in implementation you want to create an instance of.

• If you are using custom forms for end-entity enrollment, be sure to include the following line in the forms, and replace myAuthMgr with the name of the authentication instance you added.

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

For example, if your authentication instance is named testAuth, the line would look like this:

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

• If your end-entity forms are based on the HTML forms that come with Certificate Management System, locate the above-mentioned line; it is already embedded in the forms. Then replace myAuthMgr with the name of the authentication instance you added.

By default, the enrollment forms include the authentication instance names listed in Table 11.1. Note that the authentication instances are not created by default; only the instance names are embedded in the forms. If you create authentication instances with these names, you don't have to update the enrollment forms to replace myAuthMgr with the name of the authentication instance.

Figure 11.5 shows the default directory-based enrollment form configured to use an authentication instance identified as UserDirEnrollment.

For information on locating and customizing the default end-entity forms, see "Summary of End-Entity Forms and Templates".

To add an authentication instance to the CMS configuration:

1. Access the CMS window (see "Accessing the CMS Window").
2. Click the Configuration tab.
3. In the navigation tree, click Authentication.

The right pane shows the Authentication Instance tab, which lists any currently configured authentication instances. For information about this tab, see "Authentication Instance Tab".



4. Click Add.

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



5. Select a plug-in module.

The following choices are the ones provided out of the box with Certificate Management System (they are described in "End-Entity Authentication During Certificate Enrollment"). If you have registered any custom authentication plug-in modules, they too will be available for selection.

• UidPwdDirAuth

This entry represents the user ID- and password-based authentication module explained in "Directory-Based Authentication".

• UidPwdPinDirAuth

This entry represents the user ID-, password-, and PIN-based authentication module (with or without PIN removal) explained in "Directory-Based Authentication with PINs".

To configure Certificate Management System for PIN-based authentication, you must have an LDAP-compliant directory deployed (with end-entity entries in it) and a unique PIN for each end entity.

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

6. Click Next.

The Configure Authentication Instance Parameters window appears. It lists the configuration information required for this authentication instance. For more information on how this window functions, see "Authentication Instance Editor".



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

8. In the configuration area, specify the required information by filling in parameter values in the corresponding text fields (the right column).

If you do not want to set any restrictions on a particular parameter, leave its value field blank.

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

You can delete any unwanted authentication instances from the CMS configuration. If you delete an authentication instance, the associated end-entity enrollment forms, if used, fail to authenticate end entities. If you want these forms to work with other authentication instances, make the appropriate changes to the forms; see "Step 5. Customize the End-Entity Enrollment Forms".

1. Access the CMS window (see "Accessing the CMS Window").
2. Click the Configuration tab.
3. In the navigation tree, click Authentication.

The right pane shows the Authentication Instance tab, which lists currently configured authentication instances. For information about this tab, see "Authentication Instance Tab".

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 involves changing its configuration parameter values; you cannot change the name of an instance. To change the name of an instance, create a new instance using the same authentication plug-in module that you used to create the instance you want to rename, with the same parameter values, and delete the old one.

1. Access the CMS window (see "Accessing the CMS Window").
2. Click 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 modify and click Edit.

The Configure Authentication Instance Parameters window appears, showing the current configuration of this instance. For more information on how this window functions, see "Authentication Instance Editor".



5. Make the necessary changes by filling in parameter values in the corresponding text fields (the right column).

If you do not want to set any restrictions on a particular parameter, leave its value field blank.

• For a description of configuration parameters pertaining to the instances created using the UidPwdDirAuth plug-in module, see Table 9.1.
• For a description of configuration parameters pertaining to the instances created using the UidPwdPinDirAuth plug-in module, see Table 9.2.

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.

• Registering an Authentication Plug-in Module
• Deleting an Authentication Plug-in Module

You can register custom authentication plug-in modules from the CMS window. Before registering an authentication plug-in, be sure to put the Java class for the plug-in module in the classes directory; see "Compiling and Installing Authentication Manager Plug-ins".

1. Access the CMS window (see "Accessing the CMS Window").
2. Click the Configuration tab.
3. In the navigation tree, click Authentication, and in the right pane, click the Authentication Plugin Registration tab.

The Authentication Plugin Registration tab lists currently registered plug-in modules. For information about this tab, see "Authentication Plugin Registration Tab".



4. Click Register.

The Register Authentication Plugin Implementation window appears. For information on how this window works, see "Authentication Plug-in Registration Editor".



5. Specify the appropriate information:

Plugin name. Type the name of the plug-in module.

Class name. Type the full name of the class for this plug-in 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.

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

1. Access the CMS window (see "Accessing the CMS Window").
2. Click the Configuration tab.
3. In the navigation tree, click Authentication, and in the right pane, click the Authentication Plugin Registration tab.

The Authentication Plugin Registration tab lists currently registered plug-in modules. For information about this tab, see "Authentication Plugin Registration Tab".

4. In the Plugin Name list, select the plug-in 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.