Authentication Plug-in Tutorial

Overview

The administrator of a Public Key Infrastructure (PKI) Certificate System (CS) server would like users to obtain their certificates by merely entering their user id (UID) and their Social Security Number (SSN). This tutorial describes step-by-step how an administrator can build, install, and run an authentication plug-in so that users may authenticate themselves to the Certificate Authority (CA) by merely entering their UID and SSN.

This plug-in is for demonstration purposes only and it is only compatible with DCS 1.0.0 or later.

Prerequisites for this Authentication Plug-in

For the illustrative purposes of this tutorial, it will be necessary for the user to setup a basic test CA which can be thrown away at the completion of this tutorial.

This tutorial assumes that the user is at least somewhat familiar with the administrative and operational tasks required to run a basic CA within a PKI CS. The user should know what an "instance" is, and should be able to install and configure a CA, and obtain an administration certificate for at least one instance of this CA. Additionally, the user should be familiar with basic command line tools for copying, editing, and removing files and how they work on their chosen operating system.

Before continuing with this document, the reader is advised to read the following information:

PKI Installation Instructions - instructions for installing a CA,
com.netscape.cms.authentication - out-of-the-box authentication plug-in samples, and
Authentication Plug-in Anatomy - a complete generic description of the composition of an authentication plug-in.

Creating this Authentication Plug-in

Building this Authentication Plug-in

Invoke a command line window on the Linux host.
Download pki_authentication.tar.gz.
Unpackage pki_authentication.tar.gz:

gtar -zxvf pki_authentication.tar.gz

A directory called authentication will be created containing the following files:
- SSNAuth.java - the source code for this authentication plug-in,
- SSNEnroll.cfg - the configuration file for this authentication plug-in, and
- build.sh - the build script used to create this authentication plug-in.
Go to the authentication subdirectory:

cd authentication

It may be necessary to edit the "build.sh" as the original jar names may have changed:

 CLASSPATH=${PKIHOME}/pki-cmsutil.jar:${PKIHOME}/pki-cms.jar:${CLASSPATH}
 CLASSPATH=${PKIHOME}/pki-nsutil.jar:${PKIHOME}/pki-certsrv.jar:${CLASSPATH}

To build this authentication plug-in in the current directory, execute this command:

./build.sh

NOTE: If version 1.5.x or later of javac is used, the user may see something similar to the following warning:

Note: SSNAuth.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

This warning may be safely ignored, as it refers to features specific to Java SDK 1.5.x or later.

A file called SSNAuth.class should be created in this authentication directory.

Installing this Authentication Plug-in

PKI authentication plug-ins are only relevant to CA subsystems.

To install this authentication plug-in to be unique to a particular CA instance, perform the following commands for each desired CA subsystem:

Assume the role of the root user.
Type cp SSNAuth.class <pki-instance>/webapps/<pki-subsystem>/WEB-INF/classes, where <pki-instance> is the complete path to the desired CA instance, and <pki-subsystem> is always ca for all authentication plug-ins. (For example, the default instance directory for the first instance is /var/lib/pki-ca)
Type chown <pki-instance-owner>:<pki-instance-group> <pki-instance>/webapps/<pki-subsystem>/WEB-INF/classes/SSNAuth.class, where <pki-instance-owner> is the user id of the owner of the specified instance, <pki-instance-group> is the group id of the owner of the specified instance, <pki-instance> is the complete path to the specified CA instance, and <pki-subsystem> is always ca for all authentication plug-ins.
Type cp SSNEnroll.cfg <pki-instance>/conf, where <pki-instance> is the complete path to the desired CA instance.
Type chown <pki-instance-owner>:<pki-instance-group> <pki-instance>/conf/SSNEnroll.cfg, where <pki-instance-owner> is the user id of the owner of the specified instance, <pki-instance-group> is the group id of the owner of the specified instance, and <pki-instance> is the complete path to the specified CA instance.
Dismiss the command line window on the Linux host.

NOTE: It was recently reported that these <pki-instance> specific paths no longer work in newer versions of Dogtag; try using cp SSNAuth.class /usr/share/pki/ca/webapps/ca/WEB-INF/classes/SSNAuth.class instead.

Customizing this Authentication Plug-in

Launch the PKI Console

Invoke a command line window on the Linux host.
Invoke the PKI console and login.
Login to a PKI instance, providing the requested Username and Password.
A new screen entitled Certificate System should appear with two tabs labeled Configuration, and Status.
Select the Configuration tab.
Click on the Authentication option presented in the menu on the left-side of this panel.
Two tabs should appear on the right-side labeled Authentication Instance and Authentication Plug-in Registration.

Register the Authentication Plug-in

Select the Authentication Plug-in Registration tab:

Press the Register button, and a dialog box entitled Register Authentication Plug-in Implementation appears:
- For the "Plug-in name:" field, type in SSNAuth.
- For the "Class name:" field, type in the path to the SSNAuth.class class finishing with the name SSNAuth (do NOT type in the .class extension).

NOTE:

For the purposes of this tutorial, it is ONLY necessary to type in a Class Name of SSNAuth. This is due to the fact that the default search path order for plug-ins ALWAYS searches for plug-ins in the following order:

the <pki-instance>/webapps/<pki-subsystem>/WEB-INF/classes/ directory (and all subdirectories under this directory for this specific instance)
a combination of default PKI jar files and default PKI jre jar files

For example, if the SSNAuth.class had been placed in a directory called <pki-instance>/webapps/<pki-subsystem>/WEB-INF/classes/mydir/mysubdir/, the java source code would need to contain a package mydir.mysubdir; statement, be rebuilt, and the subsequent SSNAuth.class binary would then need to be placed into this directory. Finally, the user would need to type mydir.mysubdir.SSNAuth within this dialog box to register their plug-in.

Press the OK button to dismiss the dialog box, and this plug-in should now appear in alphabetical order on the list of authentication plug-ins displayed on this panel. If it does not, try pressing the Refresh button until it does:

Create an Instance of the Authentication Plug-in

Select the Authentication Instance tab:

Press the Add button, and a dialog box entitled Select Authentication Plug-in Implementation appears:

Highlight "SSNAuth", and press the Next button. A dialog entitled Authentication Instance Editor appears:
- For the "Authentication Instance ID:" field, type in "SSNEnroll".
- For the "Authentication Plugin ID:" field, the string "SSNAuth" should already be present (and non-editable).
- For the required "* baseSubjectDN:" field, type in the desired base subject DN to be appended to the UID on each certificate.
- For the required "* ssnfile:" field, type in the fully qualified path to the "SSNEnroll.cfg" file.

**Example Values**
Field	Value
Authentication Instance ID:	SSNEnroll
Authentication Plug-in ID:	SSNAuth
* baseSubjectDN:	o=<Organization>, c=US
* ssnfile:	<pki-instance>/conf/SSNEnroll.cfg

Press the OK button to dismiss the dialog box, and this plug-in should now appear on the list of authentication plug-in instances displayed on this panel. If it does not, try pressing the Refresh button until it does:

Close the console.
Dismiss the command line window on the Linux host.

Stop Each Selected PKI Instance

Stop each selected PKI instance by performing the following shutdown sequence:

Invoke a command line window on the Linux host.
Assume the role of the root user.
Type cd /etc/init.d.
For each selected PKI instance, execute ./<pki-instance> stop, where <pki-instance> is the name of the selected PKI instance, to shutdown this instance of the PKI server.
Optional Verification: At this time, to verify that the SSNEnroll authentication plug-in was actually installed, the user may verify that the <pki-instance>/conf/CS.cfg file, where <pki-instance> is the complete path to the specified CA instance, contains the following values:

       .
       .
       .
   auths.impl.SSNAuth.class=SSNAuth
       .
       .
       .
   auths.instance.SSNEnroll.baseSubjectDN=o=<Organization>,c=US
   auths.instance.SSNEnroll.pluginName=SSNAuth
   auths.instance.SSNEnroll.ssnfile=<pki-instance>/conf/SSNEnroll.cfg
       .
       .
       .

Dismiss the command line window on the Linux host.

Customize the End-Entity Enrollment Page with a new Profile

Perform the following customization to automatically create a profile for this authentication plug-in which will be directly available from the end-entity (EE) port (default EE port number is 9443). Perform the following tasks for each selected instance of the PKI server:

Invoke a command line window on the Linux host.
Assume the role of the root user.
Type cd <pki-instance>/profiles/<pki-subsystem>/, where <pki-instance> is the complete path to the desired CA instance, and <pki-subsystem> is always ca for all authentication plug-ins.
Type cp -p caDirUserCert.cfg caSSNUserCert.cfg to create a new customized enrollment page, and preserve the permissions of the owner of this CA instance.
Edit the <pki-instance>/profiles/<pki-subsystem>/caSSNUserCert.cfg file to make the following highlighted changes:

   
   desc=This certificate profile is for enrolling user certificates with SSN authentication.
   visible=true
   enable=true
   enableBy=admin
   name=SSN User Dual-Use Certificate Enrollment
   auth.instance_id=SSNEnroll
       .
       .
       .

Type cd <pki-instance>/conf/, where <pki-instance> is the complete path to the same CA instance.
Edit the <pki-instance>/conf/CS.cfg file to make the following highlighted changes:

       .
       .
       .
   profile.list=caUserCert,caDualCert,caSignedLogCert,caTPSCert,caRARouterCert,caRo
   uterCert,caServerCert,caOtherCert,caCACert,caInstallCACert,caRACert,caOCSPCert,c
   aTransportCert,caDirUserCert,caAgentServerCert,caAgentFileSigning,caCMCUserCert,
   caFullCMCUserCert,caSimpleCMCUserCert,caTokenDeviceKeyEnrollment,caTokenUserEncr
   yptionKeyEnrollment,caTokenUserSigningKeyEnrollment,caTempTokenDeviceKeyEnrollme
   nt,caTempTokenUserEncryptionKeyEnrollment,caTempTokenUserSigningKeyEnrollment,ca
   AdminCert,caInternalAuthServerCert,caInternalAuthTransportCert,caInternalAuthDRM
   storageCert,caInternalAuthSubsystemCert,caInternalAuthOCSPCert,DomainController,
   caDualRAuserCert,caRAagentCert,caRAserverCert,caSSNUserCert
       .
       .
       .
   profile.caRouterCert.class_id=caEnrollImpl
   profile.caRouterCert.config=<pki-instance>/profiles/<pki-subsystem>/caRouterCert.cfg
   profile.caSSNUserCert.class_id=caEnrollImpl
   profile.caSSNUserCert.config=<pki-instance>/profiles/<pki-subsystem>/caSSNUserCert.cfg
   profile.caServerCert.class_id=caEnrollImpl
   profile.caServerCert.config=<pki-instance>/profiles/<pki-subsystem>/caServerCert.cfg 
       .
       .
       .

Dismiss the command line window on the Linux host.

Start Each Selected PKI Instance

Refresh each selected PKI instance by performing the following startup sequence:

Invoke a command line window on the Linux host.
Assume the role of the root user.
Type cd /etc/rc.d/init.d.
For each selected PKI instance, execute ./<pki-instance> start, where <pki-instance> is the name of the selected PKI instance, to startup this instance of the PKI server.
Dismiss the command line window on the Linux host.

Running this Authentication Plug-in

Launch a Browser to Test this Authentication Plug-in

Launch a browser (preferably Mozilla Firefox 2.0 or later).
Type the URL https://<PKI hostname>:<PKI secure EE port>/<pki-subsystem>/ee/<pki-subsystem>, where <pki-subsystem> is always ca for authentication plug-ins, into the browser to list the CA Certificate Profiles:

Select the SSN User Dual-Use Certificate Enrollment profile presented in the menu on the right-side of the Enrollment panel to display the following SSN User enrollment profile:

Perform the following Test Cases for this Authentication Plug-in:

Test Case I: Successful Certificate Issuance for "hmiller" -- expected SUCCESS

Type in "hmiller" for User ID.
Type in "000112222" (which will be displayed as "*********") for SSN.

Field	Value
User ID:	hmiller
SSN:	000112222

Press the Submit button, and the browser should notify the user that it needs to begin generating a key (the user may need to press the OK button). The browser should then start generating the key before it returns a screen stating the following:

   Congratulations, your request has been processed successfully

The remainder of the screen should reference the request ID, and contain the requested certificate for the user "hmiller".

Test Case II: Incorrect SSN entered for "scarter" -- expected FAILURE

Type in "scarter" for User ID.
Type in "000112222" (which will be displayed as "*********") for SSN.

Field	Value
User ID:	scarter
SSN:	000112222

Press the Submit button, and the browser should notify the user that it needs to begin generating a key (the user may need to press the OK button). The browser should then start generating the key before it returns a screen stating the following:

   Sorry, your request is not submitted. The reason is "Authentication Error".

Test Case III: Successful Certificate Issuance for "scarter" -- expected SUCCESS

Type in "scarter" for User ID.
Type in "999887777" (which will be displayed as "*********") for SSN.

Field	Value
User ID:	scarter
SSN:	999887777

Press the Submit button, and the browser should notify the user that it needs to begin generating a key (the user may need to press the OK button). The browser should then start generating the key before it returns a screen stating the following:

   Congratulations, your request has been processed successfully

The remainder of the screen should reference the request ID, and contain the requested certificate for the user "scarter".

Test Case IV: Unknown user entered for "smiller" -- expected FAILURE

Type in "smiller" for User ID.
Type in "000112222" (which will be displayed as "*********") for SSN.

Field	Value
User ID:	smiller
SSN:	000112222

Press the Submit button, and the browser should notify the user that it needs to begin generating a key (the user may need to press the OK button). The browser should then start generating the key before it returns a screen stating the following:

   Sorry, your request is not submitted. The reason is "Authentication Error".

PKI Authentication Plug-ins

Contents