Complete Contents
About This Guide
PART 1: Netscape Certificate Management System
Chapter 1: Introduction to Certificate Management System
Chapter 2: Administration Tasks and Tool
Chapter 3: Configuration
PART 2: Managing Certificate Management System
Chapter 4: Installing and Uninstalling Instances
Chapter 5: Starting and Stopping Instances
PART 3: System-Level Configuration
Chapter 6: Configuring Ports, Database, and SMTP Settings
Chapter 7: Managing Privileged Users and Groups
Chapter 8: Keys and Certificates
PART 4: Authentication
Chapter 9: Introduction to Authentication
Chapter 10: Using the PIN Generator Tool
Chapter 11: Configuring Authentication for End Entities
Chapter 12: Developing Authentication Plug-ins
PART 5: Job Scheduling and Notification
Chapter 13: Introduction to Job Scheduling and Notifications
Chapter 14: Configuring Jobs
PART 6: Policies
Chapter 15: Introduction to Policies
Chapter 16: Configuring Policies
PART 7: LDAP Publishing
Chapter 17: Introduction to LDAP Publishing
Chapter 18: Configuring Subsystems for LDAP Publishing
Chapter 19: Publishing CRLs
PART 8: Agent and End-Entity Interfaces
Chapter 20: Introduction to End-Entity and Agent Interfaces
Chapter 21: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 22: Introduction to Logs
Chapter 23: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 24: Issuing and Managing End-Entity Certificates
Chapter 25: Recovering Encrypted Data
PART 11: Appendixes
Appendix A: Distinguished Names
Appendix B: Backing Up and Restoring Data
Appendix C: Command-Line Utilities
Appendix D: Certificate Database Tool
Appendix E: Key Database Tool
Appendix F: Netscape Signing Tool
Appendix G: SSL Strength Tool
Appendix H: SSL Debugging Tool
Previous Next Contents Index Bookshelf


Chapter 12 Developing Authentication Plug-ins

The authentication subsystem evaluates and authenticates the identity of an end entity that is requesting service from Netscape Certificate Management System (CMS). By default, the authentication subsystem supports various authentication mechanisms; these are explained in "Introduction to Authentication".

If the authentication plug-in modules provided with Certificate Management System do not meet your requirements, you can write custom authentication plug-ins and plug them into the authentication framework of Certificate Management System.

 This chapter provides an overview of the authentication subsystem architecture, discusses the interfaces for writing custom authentication plug-ins (called authentication managers), and explains how to implement custom authentication.

 The chapter has the following sections:

 Note To customize authentication, you must be familiar with programming in Java and the Netscape Certificate Management System 4.x software development kit (SDK).


Authentication Subsystem Architecture
The authentication subsystem of Certificate Management System permits a flexible number of authentication managers for end-entity authentication. This architecture is illustrated in Figure 12.1. An authentication manager (authMgr) is a configured instance of an authentication plug-in implementation.

Figure 12.1 Authentication subsystem architecture

Table 12.1 describes the components shown in Figure 12.1.

Table 12.1 Description of components

Component
Description
End entity
Specifies end entities, such as users, servers, virtual private network (VPN) clients, or routers enrolling for a certificate through a web-based form.

End-entity gateway
Specifies the end-entity gateway provided by Certificate Management System.

Servlets
Specifies end-entity servlets. Each type of request from an end entity is handled by a different servlet; each servlet serves the correct HTML form or other information to the end entity, depending on the protocols supported by that entity.

Policies
Specifies currently configured policies for a Certificate Manager or Registration Manager (depending on which subsystem is processing end-entity requests).

Manual
Specifies manual authentication. If you do not configure Certificate Management System to use any of the authentication plug-in modules listed in the Authentication Registration Plugin tab, the server uses manual authentication for end-entity enrollment. This means that all end-entity enrollment requests are queued for agent approval.

End-entity authMgr
Specifies configured authentication managers (based on authentication plug-ins provided out of the box and custom, if any) for authenticating end entities.

How the Architecture Works

The setup shown in Figure 12.1 works in the following way:

  1. An end entity enrolls for a certificate through a web-based form that includes fields in which the end entity enters the required enrollment credentials or provides authentication parameter values. The form has been customized to use a specific authentication manager.
    2.

  2. On the CMS side, a servlet receives the following as input from the form the end entity used:

    3. The servlet then calls the appropriate authentication manager instance to authenticate the end entity.

  3. After the end entity is authenticated, policies are applied on the request by either a Certificate Manager or Registration Manager, depending on which subsystem is processing the request.
    4.

  4. Finally, a certificate is issued and returned to the end entity.

How Authentication Managers Are Used

To authenticate an end entity, an enrollment servlet calls the authentication manager authenticate (IAuthCredentials) method, passing it credentials received in the HTTP input (the HTML form). The authentication manager implementation specifies which HTTP input variables are required for authentication. For example, in the directory-based authentication manager the required credentials are UID and password. If authentication succeeds, an AuthToken is returned. Otherwise, an exception is thrown. IAuthCredentials and AuthToken contain lists of attribute and value pairs.

The AuthToken returned contains the fields and values listed in Table 12.2. The tokenCertSubject value must have the subject DN of the certificate set. Values for all other fields are optional.

Table 12.2 AuthToken fields and values

Field
Object type returned
tokenCertSubject

netscape.security.X509.X500Name
(a Java X509Name object)

tokenCertNotBefore

java.util.Date
(a Java Date object)

tokenCertNotAfter

java.util.Date
(a Java Date object)

tokenCertExts

netscape.security.X509.Certificate extensions
(a Java X509Extensions object)

For certificate enrollment the AuthToken must contain a field containing a certificate subject name for the authenticated user, for requests made through the KEYGEN tag. (Certificate Management System supports certificate requests in KEYGEN, PKCS #10, CRMF and CEP formats). The token field is AuthToken.TOKEN_CERT_SUBJECT. The value must be an instance of netscape.security.x509.X500Name. For other request formats that contain a subject name, a certificate subject name returned in the AuthToken will override the subject name in the request, for example in a PKCS #10 request.

 In addition, all AuthTokens contain the following:

 Optionally, the AuthToken can contain other attributes that customized policies can use in building the certificate.

 After authentication, the AuthToken and the attributes and values returned in the AuthToken are stored in the request. Credentials from the form are discarded. The request is then passed to policies and then to the Certificate Manager for issuance.
Customizing Authentication
Customizing authentication is a five-step process:

 Step 1. Decide on an Authentication Scheme

When you consider customizing authentication, the first thing to decide is the kind of authentication scheme that you want for your end entities when they enroll for a certificate. In planning the scheme, you must identify and decide on the end-entity attributes Certificate Management System should retrieve from an end-entity request and evaluate the values of. In other words, in this step you must fix the attributes for authentication.

For example, if you have a corporatewide user database, you may want the end entities to provide their user IDs and passwords for the directory as authentication credentials. In that case, you would make sure that the form the end entities use for certificate enrollment includes user ID and password fields. Then end entities will provide this information when they request a certificate from Certificate Management System. Alternatively, you may want to issue certificates to any individual who has a social security number or other kind of valid identification, such as a driver's license or bank account.

 Step 2. Write the Authentication Plug-in Module

Authentication managers are implemented as Java classes, which are then registered with Certificate Management System as plug-ins. After you decide on the attributes for authenticating end entities, you need to write an authentication plug-in (Java class) that uses those attributes. Keep in mind that the plug-in implementation must conform to the CMS interface, as explained in the section that follows.

Authentication Manager Plug-in API

To enable you to write custom authentication plug-ins, Certificate Management System provides an authentication manager plug-in API and related classes (Java Docs).

Your authentication manager plug-in must be a Java class that implements the following interface:

com.netscape.certsrv.authentication.IAuthManager

For the definition of IAuthManager, check the directory named SDK on the product CD. You can also download the CMS SDK from this site:

 http://home.netscape.com/eng/server/cms

 Compiling and Installing Authentication Manager Plug-ins

When you are compiling an authentication manager plug-in using javac, be sure to include CMS classes in the classpath. For example, if a CMS instance named testCA is installed in C:\netscape\server4 (default server root in Windows NT) or usr/netscape/server4 (default server root in Unix), use the following to compile the authentication manager plug-in implementation:

Windows NT > set CERT40DIR=C:\netscape\server4\bin\cert\jars
> javac -classpath \
C:\jdk1.1.6/lib/classes.zip;%CERT40DIR%/
ldapjdk.jar;%CERT40DIR%/certsrv.jar \
myAuthMgr.java
Unix $ set CERT40DIR=usr/netscape/server4/bin/cert/jars
$ javac -classpath \
/usr/jdk1.1.6/lib/classes.zip:$CERT40DIR/
ldapjdk.jar:$CERT40DIR/certsrv.jar \
myAuthMgr.java

After compiling an authentication manager plug-in, add it to the CMS authentication framework as explained in the section that follows.

Adding the Authentication Manager Class File to the CMS Authentication Framework

There are two ways in which you can add a custom authentication module class file to the CMS authentication framework. You can either put the class file in the server's default classpath or edit the server's start-cert script to include the path to your authentication plug-in module. The recommended method is that you add your class file to the server's default classpath.

The classes directories are located here:

 <server_root>/bin/cert/classes/... and

 <server_root>/cert-<instance_id>/classes/...

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.

Alternatively, for testing purposes, you can also edit the classpath in the
start-cert script to point to the custom class file.

Important Keep in mind that the changes you make to the start-cert script will take effect only when starting the server from the command line.

The default classpath in the start-cert script is as follows:

Windows NT C:\Netscape\Server4\cert- testCA\classes\;C:\Netscape\Server4\bin\cert\classes\;C:\Netsca pe\Server4\bin\cert\jars\jss.jar;C:\Netscape\Server4\bin\cert\j ars\certsrv.jar;C:\Netscape\Server4\java\ldapjdk.jar;C:\Netscap e\Server4\bin\base\jre\lib\rt.jar;C:\Netscape\Server4\bin\base\ jre\lib\i18n.jar;C:\Netscape\Server4\bin\cert\jars\jssjdk12.jar ;C:\Netscape\Server4\java\swingall.jar
Unix /usr/netscape/server4/cert-testCA/classes/:/usr/netscape/ server4/bin/cert/classes/:/usr/netscape/server4/bin/cert/jars/ jss.jar:/usr/netscape/server4/bin/cert/jars/certsrv.jar:/usr/ netscape/server4/java/ldapjdk.jar:/usr/netscape/server4/bin/ base/jre/lib/rt.jar:/usr/netscape/server4/bin/base/jre/lib/ i18n.jar:/usr/netscape/server4/bin/cert/jars/jssjdk12.jar

To add a classpath to the start-cert script in Unix:

    1. Go the command-line window.
      2.

    2. Go to the CMS-instance directory. For example, /usr/netscape/server4/cert-testCA

    3. Enter the following line at the prompt:

      4. cat start-cert

      You should see something similar to this:

      #!/bin/sh

      /usr/netscape/server4/bin/cert/admin/bin/start -i testCA -r /usr/netscape/server4 -e -classpath

      /usr/netscape/server4/bin/cert/classes:/usr/netscape/
      server4/bin/cert/jars/jss.jar:/usr/netscape/server4/bin/
      cert/jars/certsrv.jar:usr/netscape/server4/java/
      ldapjdk.jar:/usr/netscape/server4/bin/base/jre/lib/
      rt.jar:/usr/netscape/server4/bin/base/jre/lib/i18n.jar:/

      usr/netscape/server4/bin/cert/jars/jssjdk12.jar

    4. Add your class's directory path to the start-cert script. Be sure to add the directory path to the beginning as shown in the example.

      5. #!/bin/sh

      /usr/netscape/server4/bin/cert/admin/bin/start -i testCA -r /usr/netscape/server4 -e -classpath

      <your_class's_directory_path>:/usr/netscape/server4/cert-
      testCA/classes/      :/usr/netscape/server4/bin/cert/classes/:/
      usr/netscape/server4/bin/cert/jars/jss.jar:/usr/netscape/
      server4/bin/cert/jars/certsrv.jar:/usr/netscape/server4/
      java/ldapjdk.jar:/usr/netscape/server4/bin/base/jre/lib/
      rt.jar:/usr/netscape/server4/bin/base/jre/lib/i18n.jar:/
      usr/netscape/server4/bin/cert/jars/jssjdk12.jar

      For example, if your class file is in a directory /u/jdoe/myAuthMgrs, here's how the start-cert script would look:

      #!/bin/sh

      /usr/netscape/server4/bin/cert/admin/bin/start -i testCA -r /usr/netscape/server4 -e -classpath

      /u/jdoe/myAuthMgrs:/usr/netscape/server4/cert-testCA/
      classes:/usr/netscape/server4/bin/cert/classes/:/usr/
      netscape/server4/bin/cert/jars/jss.jar:/usr/netscape/
      server4/bin/cert/jars/certsrv.jar:/usr/netscape/server4/
      java/ldapjdk.jar:/usr/netscape/server4/bin/base/jre/lib/
      rt.jar:/usr/netscape/server4/bin/base/jre/lib/i18n.jar:/
      usr/netscape/server4/bin/cert/jars/jssjdk12.jar

To add a classpath to the start-cert.bat script in Windows NT:
    1. Go the command-line window.
      2.

    2. Go to the CMS instance directory. For example, C:\netscape\server4\cert-testCA

    3. Enter the following line at the prompt:

      4. type start-cert.bat

      You should see something similar to this:

      net start cert-testCA /cC:\Netscape\Server4\cert-
      testCA\classes\;C:\Netscape\Server4\bin\cert\classes\;C:\
      Netscape\Server4\bin\cert\jars\jss.jar;C:\Netscape\Server
      4\bin\cert\jars\certsrv.jar;C:\Netscape\Server4\java\ldap
      jdk.jar;C:\Netscape\Server4\bin\base\jre\lib\rt.jar;C:\Ne
      tscape\Server4\bin\base\jre\lib\i18n.jar;C:\Netscape\Serv
      er4\bin\cert\jars\jssjdk12.jar;C:\Netscape\Server4\java\
      swingall.jar

    4. Add your class's directory path to the start-cert command. Be sure to add the directory path to the beginning as shown in the example.

      5. net start cert-testCA /c<your_class's_directory_path>C:\Netscape\Server4\cert-
      testCA\classes\;C:\Netscape\Server4\bin\cert\classes\;C:\
      Netscape\Server4\bin\cert\jars\jss.jar;C:\Netscape\Server 4\bin\cert\jars\certsrv.jar;C:\Netscape\Server4\java\ldap
      jdk.jar;C:\Netscape\Server4\bin\base\jre\lib\rt.jar;C:\Ne
      tscape\Server4\bin\base\jre\lib\i18n.jar;C:\Netscape\Serv
      er4\bin\cert\jars\jssjdk12.jar;C:\Netscape\Server4\java\
      swingall.jar

      For example, if your class file is in a directory C:\jdoe\myAuthMgrs\... here's how the start-cert.bat script would look:

      net start cert-testCA /cC:\jdoe\myAuthMgrs\;C:\Netscape\Server4\cert-
      testCA\classes\;C:\Netscape\Server4\bin\cert\classes\;C:\
      Netscape\Server4\bin\cert\jars\jss.jar;C:\Netscape\Server
      4\bin\cert\jars\certsrv.jar;C:\Netscape\Server4\java\ldap
      jdk.jar;C:\Netscape\Server4\bin\base\jre\lib\rt.jar;C:\Ne
      tscape\Server4\bin\base\jre\lib\i18n.jar;C:\Netscape\Serv
      er4\bin\cert\jars\jssjdk12.jar;C:\Netscape\Server4\java\s
      wingall.jar

Authentication Manager Examples

To aid you in writing custom authentication managers, Certificate Management System provides sample authentication plug-ins. You can find them in this directory:

<server_root>/bin/cert/samples/authentication/...

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

You can also download the samples from this site:

 http://home.netscape.com/eng/server/cms

 The samples directory includes an authentication manager that checks the user's user ID and password in a directory configured for authenticating users.

 Step 3. Register the Authentication Manager Plug-in Module

You can register custom authentication manager plug-in modules by using the CMS window. Before registering a custom plug-in, be sure to put the Java class for the plug-in in the classes directory. For instructions, see "Registering an Authentication Plug-in Module".

Step 4. Create an Instance of the Authentication Plug-in Module

After you have registered the custom authentication plug-in module, you must configure an instance of it. For instructions, see "Adding an Authentication Instance".

Step 5. Customize the End-Entity Enrollment Forms

After you have created the authentication manager instance, you must customize the appropriate HTML form for end-entity enrollment. Make the following changes:

The most convenient way to do this is by editing the forms provided out of the box for end entities. For example, you can add new fields to the directory-based authentication form provided for end-entity enrollment. You can also use custom enrollment forms, but if you do so, be sure to include the following HTML element in your end-entity enrollment form:

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

where myAuthMgr is the name of the authentication instance you want to use with the enrollment form.

Figure 12.2 shows a directory-based authentication form customized to use a social security number (SSN) for authentication in addition to user ID and password for the authentication directory. Note the text field named SSN.

Figure 12.2 End-entity enrollment form for SSN and directory-based authentication

 

© Copyright 1999 Netscape Communications Corp., a subsidiary of America Online, Inc. All rights reserved.