|
|
| (39 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | = Authentication Plug-in Tutorial =
| + | This page has been moved to https://github.com/dogtagpki/pki/wiki/Creating-Authentication-Plugin. |
| − | | |
| − | == 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.
| |
| − | | |
| − | == 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_Install_Guide|PKI Installation Instructions]] - instructions for installing a CA,
| |
| − | * [http://pki-svn.fedora.redhat.com/pki/javadocs/pki-common-8.0.0/index.html?com/netscape/cms/authentication/package-summary.html com.netscape.cms.authentication] - out-of-the-box authentication plug-in samples, and
| |
| − | * [[PKI_Authentication_Plug-in_Anatomy|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 [http://pki-svn.fedora.redhat.com/pki/tutorials/pki_authentication.tar.gz pki_authentication.tar.gz].
| |
| − | * Type '''''gtar -zxvf pki_authentication.tar.gz''''' to unpackage '''pki_authentication.tar.gz'''.
| |
| − | * A directory called '''authentication''' will be created containing the following files:
| |
| − | ** [[PKI_Authentication_SSNAuth.java|SSNAuth.java]] - the source code for this authentication plug-in,
| |
| − | ** [[PKI_Authentication_SSNEnroll.cfg|SSNEnroll.cfg]] - the configuration file for this authentication plug-in, and
| |
| − | ** [[PKI_Authentication_build.sh|build.sh]] - the build script used to create this authentication plug-in.
| |
| − | * Type '''''cd authentication'''''.
| |
| − | * To simply build this authentication plug-in in the current directory, execute '''''./build.sh'''''.
| |
| − | * 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.
| |
| − | * 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.
| |
| − | | |
| − | == 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:
| |
| − | | |
| − | <ul>
| |
| − | [[Image:PKI_console_begin_register_authentication_plugin.gif]]
| |
| − | </ul>
| |
| − | | |
| − | * 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).
| |
| − | | |
| − | <ul>
| |
| − | <ul>
| |
| − | [[Image:PKI_console_register_authentication_plugin.gif]]
| |
| − | </ul>
| |
| − | </ul>
| |
| − | | |
| − | <ul>
| |
| − | <table>
| |
| − | <tr>
| |
| − | <td valign="top">
| |
| − | '''NOTE''':
| |
| − | </td>
| |
| − | <td>
| |
| − | 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.
| |
| − | </td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | </ul>
| |
| − | | |
| − | * Press the <B>OK</B> 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:
| |
| − | | |
| − | <ul>
| |
| − | [[Image:PKI_console_end_register_authentication_plugin.gif]]
| |
| − | </ul>
| |
| − | | |
| − | === Create an Instance of the Authentication Plug-in ===
| |
| − | | |
| − | * Select the <B>Authentication Instance</B> tab:
| |
| − | | |
| − | <ul>
| |
| − | [[Image:PKI_console_begin_authentication_plugin_instance.gif]]
| |
| − | </ul>
| |
| − | | |
| − | * Press the '''Add''' button, and a dialog box entitled '''Select Authentication Plug-in Implementation''' appears:
| |
| − | | |
| − | <ul>
| |
| − | [[Image:PKI_console_select_authentication_plugin_instance.gif]]
| |
| − | </ul>
| |
| − | | |
| − | * 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.
| |
| − | | |
| − | <ul>
| |
| − | <ul>
| |
| − | <table border=1>
| |
| − | <caption>'''Example Values'''</caption>
| |
| − | <tr bgcolor="#000000">
| |
| − | <th><font color="#ffffff">Field</font></th>
| |
| − | <th><font color="#ffffff">Value</font></th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''Authentication Instance ID:'''</td>
| |
| − | <td><center>SSNEnroll</center></td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''Authentication Plug-in ID:'''</td>
| |
| − | <td><center>'''SSNAuth'''</center></td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''* baseSubjectDN:'''</td>
| |
| − | <td><center>o=<Organization>, c=US</center></td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''* ssnfile:'''</td>
| |
| − | <td><center><pki-instance>/conf/SSNEnroll.cfg</center></td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | | |
| − | [[Image:PKI_console_edit_authentication_plugin_instance.gif]]
| |
| − | </ul>
| |
| − | </ul>
| |
| − | | |
| − | * 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:
| |
| − | | |
| − | <ul>
| |
| − | [[Image:PKI_console_end_authentication_plugin_instance.gif]]
| |
| − | </ul>
| |
| − | | |
| − | * 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/rc.d/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:
| |
| − | | |
| − | <b>
| |
| − | desc=This certificate profile is for enrolling user certificates with SSN authentication.</b>
| |
| − | visible=true
| |
| − | enable=true
| |
| − | enableBy=admin<b>
| |
| − | name=SSN User Dual-Use Certificate Enrollment
| |
| − | auth.instance_id=SSNEnroll</b>
| |
| − | .
| |
| − | .
| |
| − | .
| |
| − | | |
| − | * 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<b>,caSSNUserCert</b>
| |
| − | .
| |
| − | .
| |
| − | .
| |
| − | profile.caRouterCert.class_id=caEnrollImpl
| |
| − | profile.caRouterCert.config=<pki-instance>/profiles/<pki-subsystem>/caRouterCert.cfg<b>
| |
| − | profile.caSSNUserCert.class_id=caEnrollImpl
| |
| − | profile.caSSNUserCert.config=<pki-instance>/profiles/<pki-subsystem>/caSSNUserCert.cfg</b>
| |
| − | 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 (preferably Mozilla Firefox 2.0 or later).
| |
| − | * Type the URL '''https://<PKI hostname>:<PKI secure EE port>/<pki-subsystem>/''', where '''<pki-subsystem>''' is always '''ca''' for authentication plug-ins, into the browser to list the CA Certificate Profiles:
| |
| − | | |
| − | <ul>
| |
| − | <IMG SRC="browser_profiles.gif">
| |
| − | </ul>
| |
| − | | |
| − | * 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:
| |
| − | | |
| − | <ul>
| |
| − | <IMG SRC="browser_SSN_profile.gif">
| |
| − | </ul>
| |
| − | | |
| − | == Test Cases for this Authentication Plug-in ==
| |
| − | | |
| − | 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.
| |
| − | | |
| − | <ul>
| |
| − | <table border=1>
| |
| − | <tr bgcolor="#000000">
| |
| − | <th><font color="#ffffff">Field</font></th>
| |
| − | <th><font color="#ffffff">Value</font></th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''User ID:'''</td>
| |
| − | <td>hmiller</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''SSN:'''</td>
| |
| − | <td>000112222</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | </ul>
| |
| − | | |
| − | * 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:
| |
| − | | |
| − | <ul>
| |
| − | <ul>
| |
| − | Congratulations, your request has been processed successfully
| |
| − | </ul>
| |
| − | </ul>
| |
| − | | |
| − | 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.
| |
| − | | |
| − | <ul>
| |
| − | <table border=1>
| |
| − | <tr bgcolor="#000000">
| |
| − | <th><font color="#ffffff">Field</font></th>
| |
| − | <th><font color="#ffffff">Value</font></th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''User ID:'''</td>
| |
| − | <td>scarter</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''SSN:'''</td>
| |
| − | <td>000112222</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | </ul>
| |
| − | | |
| − | * 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:
| |
| − | | |
| − | <ul>
| |
| − | <ul>
| |
| − | Sorry, your request is not submitted. The reason is "Authentication Error".
| |
| − | </ul>
| |
| − | </ul>
| |
| − | | |
| − | === ''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.
| |
| − | | |
| − | <ul>
| |
| − | <table border=1>
| |
| − | <tr bgcolor="#000000">
| |
| − | <th><font color="#ffffff">Field</font></th>
| |
| − | <th><font color="#ffffff">Value</font></th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''User ID:'''</td>
| |
| − | <td>scarter</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''SSN:'''</td>
| |
| − | <td>999887777</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | </ul>
| |
| − | | |
| − | * 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:
| |
| − | | |
| − | <ul>
| |
| − | <ul>
| |
| − | Congratulations, your request has been processed successfully
| |
| − | </ul>
| |
| − | </ul>
| |
| − | | |
| − | 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.
| |
| − | | |
| − | <ul>
| |
| − | <table border=1>
| |
| − | <tr bgcolor="#000000">
| |
| − | <th><font color="#ffffff">Field</font></th>
| |
| − | <th><font color="#ffffff">Value</font></th>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''User ID:'''</td>
| |
| − | <td>smiller</td>
| |
| − | </tr>
| |
| − | <tr>
| |
| − | <td>'''SSN:'''</td>
| |
| − | <td>000112222</td>
| |
| − | </tr>
| |
| − | </table>
| |
| − | </ul>
| |
| − | | |
| − | * Press the <B>Submit</B> 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:
| |
| − | | |
| − | <ul>
| |
| − | <ul>
| |
| − | Sorry, your request is not submitted. The reason is "Authentication Error".
| |
| − | </ul>
| |
| − | </ul>
| |
