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 CMS Instances
Chapter 5: Starting and Stopping CMS 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: Authentication Modules for End-Entity Enrollment
Chapter 11: Using the PIN Generator Tool
Chapter 12: Configuring Authentication for End Users
Chapter 13: Developing Custom Authentication Modules
PART 5: Job Scheduling and Notification
Chapter 14: Introduction to Job Scheduling and Notifications
Chapter 15: Configuring Schedulable Jobs
PART 6: Policies
Chapter 16: Introduction to Policy
Chapter 17: Constraints-Specific Policy Modules
Chapter 18: Extension-Specific Policy Modules
Chapter 19: Configuring a Subsystem's Policies
PART 7: Publishing
Chapter 20: Introduction to Publishing Certificates and CRLs
Chapter 21: Modules for Publishing Certificates and CRLs
Chapter 22: Configuring a Certificate Manager for Publishing
PART 8: Agent and End-Entity Interfaces
Chapter 23: Introduction to End-Entity and Agent Interfaces
Chapter 24: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 25: Introduction to Logs
Chapter 26: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 27: Issuing and Managing End-Entity Certificates
Chapter 28: 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
Netscape Certificate Management System Administrator's Guide: Authentication Modules for End-
Previous Next Contents Index Bookshelf


Chapter 10 Authentication Modules for End- Entity Enrollment

Certificate Management System provides a set of authentication modules that enable you to configure the server to authenticate end entities, based on specified criteria, when they enroll for a certificate. This chapter explains the authentication modules that are installed with the server--it lists and briefly describes the modules and then explains each one in detail. Before reading this chapter, you should have read the chapter "Introduction to Authentication".

The chapter has the following sections:
Overview of Authentication Modules
Certificate Management System supports both manual and automated certificate issuance.

 In the manual method of certificate issuance, end entities supply most of the information required by the server to formulate certificate requests and issue certificates. Manual issuance is also dependent on human agents; it requires that all end-entity certificate requests be approved by agents before the server can process the requests. To understand the role of an agent in your PKI, see "Agents".

For details on the manual method of certificate issuance, see "Manual Authentication". For the automated method of certificate issuance, Certificate Management System provides a set of plug-in modules. Plug-in modules are implemented as Java classes and are registered in the CMS authentication framework. The Authentication Plugin Registration tab of the CMS window (see Figure 10.1) lists all the modules and the corresponding classes that are currently registered with a CMS instance.

Figure 10.1 Default authentication modules for end-user enrollment

Table 10.1 lists the authentication modules provided for the Certificate Manager and Registration Manager; no authentication modules are provided for the Data Recovery Manager as it does not function as an enrollment authority in a PKI. You can use these modules to configure a Certificate Manager and Registration Manager to employ a specific authentication method during certificate enrollments.

Table 10.1 Authentication plug-in modules for end user certificate enrollments

Plug-in module name
Function
NISAuth
Authenticates end users based on their user IDs and passwords stored in a NIS server. Optionally, uses an LDAP directory for formulating certificate subject names. For details, see "NIS Server-Based Authentication".
PortalEnroll
Authenticates online service users based on their user IDs and passwords stored in an LDAP directory. Also registers new users for the online service. For details, see "Portal Enrollment".
UidPwdDirAuth
Authenticates end users based on their user IDs and passwords stored in an LDAP directory. For details, see "Manual Authentication".
UidPwdPinDirAuth
Authenticates end users based on their user IDs, passwords, and PINs stored in an LDAP directory. For details, see "Directory-Based Authentication".

Because large corporations typically store corporatewide user, group, and network-resource data in LDAP-compliant directories, the default authentication modules provided for automated certificate enrollment use an LDAP directory for authenticating users or for formulating certificate subject names, or for both. If you already have an LDAP-compliant directory, such as Netscape Directory Server, with end-user data, you can use that directory for any of the purposes mentioned above. For example, if you have an NIS server and LDAP directory installations, you can use the NIS server for authenticating end users and the directory for formulating certificate subject names; end users will be required to provide only their NIS user IDs and passwords during enrollment.

 If you don't have a directory deployed, you may use the Netscape Directory Server instance created at the time of CMS installation; in the documentation, this instance is identified as the Configuration Directory. For a demonstration on how to use this directory for issuing certificates to end users, see Chapter 2: "Default Demo Installation" of the Netscape Certificate Management System Installation and Deployment Guide.

 If you determine that the default authentication modules do not meet your requirements, you can develop a custom authentication module using the CMS SDK, which is available in the form of Java Docs at this location:

 <server_root>/cms_sdk/sdkdocs

 For general guidelines on developing custom authentication modules and adding them to the CMS authentication framework, see "Developing Custom Authentication Modules". Be sure to take a look at the authentication-specific samples available at this location:

<server_root>/cms_sdk/samples/authentication

 For instructions on how to configure a Certificate Manager and a Registration Manager to use one or more of the authentication methods, see "Setting Up Authentication for End-User Enrollment".

Keep in mind that in an automated certificate management setup, the Certificate Manager and Registration Manager use the configured authentication methods only during certificate enrollment. During certificate renewal, the servers rely on end users SSL client certificate for automated renewal. For automated revocation, the users can use their SSL-client certificate or a challenge password. For more information, see sections "Authentication of End Users During Certificate Renewal" and "Authentication of End Users During Certificate Revocation".)

Certificate Management System also provides HTML forms-based interfaces for all the authentication methods it supports. Your end entities can use these forms for certificate enrollment. Explanation of each enrollment form, along with the corresponding authentication module, is covered in "Enrollment Forms". Certificate renewal and revocation forms are covered as a part of those processes. For details on individual form elements in the enrollment, renewal, and revocation forms, see the online help available by clicking the Help buttons on the HTML forms. You can also customize these forms to suit to your organization's requirements. For customization information, see "Agent and End-Entity Interfaces".


Manual Authentication
Manual authentication refers to operations which must be approved by a CMS agent, where no automated operation is possible. That is, a real person must log in to approve or reject request. By default, Certificate Management System provides manual-enrollment forms that enable you to request many types of certificates from the server. For details, see "Enrollment Forms".

Note that the manual authentication method is hardcoded; you cannot configure it in any other way. This ensures that when the server receives requests that lack authentication credentials, it sends those requests to the request queue for agent approval. It also means that if you don't configure a Certificate Manager or Registration Manager for any other authentication method, the server automatically sends all certificate-related requests to a queue where they await agent approval.

 Figure 10.2 illustrates how the manual authentication method works during certificate enrollment.

Figure 10.2 Manual authentication of end entities during certificate enrollment

These are the steps shown in Figure 10.2:

  1. In the manual enrollment form, the end entity enters the information needed to request a certificate and submits the request to the server.
    2.

  2. When the server receives the request, it automatically lists the request in a certificate request queue for an agent to process.

  3. An agent verifies the authenticity of the request.

  4. When the server receives the agent-approved request, it subjects it to policy processing; for details, see "Policies".

    5. The certificate is delivered to the email address specified in the certificate request.


Directory-Based Authentication
The UidPwdDirAuth plug-in module implements the directory-based authentication method. You can use this module for authenticating end users during certificate enrollment. You can use this module for authenticating unprivileged users in the global LDAP domain.

 As part of configuring a Certificate Manager and a Registration Manager, or both, for authentication, you specify an LDAP directory that the server must use to authenticate end users. End users enroll for a certificate by entering their user IDs and passwords for this authentication directory in an HTML form that is served by a Certificate Manager or Registration Manager (see "Enrollment Forms". Once the server successfully authenticates an end user, it retrieves the rest of the information required to formulate the certificate from the directory.

Figure 10.3 illustrates how authentication based on a user ID and password works during certificate enrollment.

Figure 10.3 User ID- and password-based authentication of an end user

These are the steps shown in Figure 10.3:

  1. In the directory-based certificate enrollment form, the end user enters a user ID and password for the directory and submits the request to a Certificate Manager or Registration Manager.
    2.

  2. When the server receives the request, it looks up the directory that is configured for authenticating end users. The server verifies the authenticity of the user by checking the directory entries.

    3. If, for some reason, the directory to which the server binds for authenticating the user ID and password is unavailable, the server returns an LDAP error code and writes it to the log. When troubleshooting any authentication failures, if you see a log entry with an LDAP error code, look up the corresponding error code at this URL:
    http://help.netscape.com/kb/server/970303-9.html

    A sample log entry with an LDAP error code is shown below:

28/Jun/1999:18:40:25 -0700] conn=0 op=7 RESULT err=32 tag=101 nentries=0 etime=0]
  1. Next, the server subjects the certificate request to policy processing; for details, see "Policies".

UidPwdDirAuth Module

The Java class that implements the directory-based authentication method is identified as follows:

com.netscape.certsrv.authentication.UidPwdDirAuthentication

 Figure 10.4 shows how configurable parameters of the UidPwdDirAuth module are displayed in the CMS window.

Figure 10.4 Parameters defined in the UidPwdDirAuth module

Table 10.2 gives details about each of these parameters and their values.

Table 10.2 Description of parameters defined in the UidPwdDirAuth module

Parameter
Description
dnpattern
Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:
E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates, S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).

ldapStringAttributes
Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token--that is, values retrieved from this parameter can be used by policy modules to formulate subject names for certificates or to make other policy decisions. For details, see "Subject Alternative Name Extension Policy".

Entering values for this parameter is optional.

Permissible values: Any valid LDAP string attributes, separated by commas.

Example: mail

(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)

ldapByteAttributes
Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules--that is, values retrieved from this parameter can be used by policy modules to make certain policy decisions or to add additional information to users' certificates.

For example, assume you have defined an LDAP binary attribute for storing users' pictures or fingerprints in your directory. You could develop a policy plug-in that adds users' pictures to their certificates as extensions.

Entering values for this parameter is optional.

Permissible values: Any valid LDAP byte attributes, separated by commas.

Example: jpegPhoto

This sample configuration specifies that the value of the LDAP attribute named jpegPhoto (which is included in the standard inetOrgPerson object class) should be stored in the authentication token and be used to put the user's picture in his or her certificate.

ldap.ldapconn.host
Specifies the host name of the authentication directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: corpDirectory.siroe.com

ldap.ldapconn.port
Specifies the TCP/IP port at which the authentication directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389

ldap.ldapconn.
secureConn
Specifies the type--SSL or non-SSL--of the port at which the authentication directory listens to requests from Certificate Management System.

ldap.ldapconn.
version
Specifies the LDAP protocol version.

Permissible values: 2 or 3.

Example: 3

ldap.basedn
Specifies the base DN for searching the authentication directory--the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters.

Example: O=siroe.com

ldap.minConns
Specifies the minimum number of connections permitted to the authentication directory.

Permissible values: 1 to 3.

Example: 2

ldap.maxConns
Specifies the maximum number of connections permitted to the authentication directory.

Permissible values: 3 to 10.

Example: 8


Directory- and PIN-Based Authentication
The UidPwdPinDirAuth plug-in module implements the directory- and PIN-based authentication method. You can use this module for authenticating users in the global LDAP domain during certificate enrollment. This authentication method is functionally very similar to the directory-based authentication explained in "Directory-Based Authentication", except that for stronger authentication you combine a PIN or one-time password with the end users' user IDs and passwords.

As a part of setting up a Certificate Manager or a Registration Manager, or both for end-user authentication, you specify the LDAP directory that the server must use to authenticate end users. End users enroll for a certificate by entering their user IDs, passwords, and PINs in an HTML form that is served by the Certificate Manager or Registration Manager (see "Enrollment Forms". Once the server successfully authenticates an end user, it retrieves the rest of the information required to formulate the certificate from the directory. You can also configure the server to either retain or remove the PIN from the directory following successful authentication.

Normally, user entries in directories do not contain PINs. In order to use the UidPwdPinDirAuth module, you must first populate the directory that you intend to use for authentication with unique PINs for users; each user to whom you intend to issue a certificate must know his or her PIN at the time of certificate enrollment, as he or she will be required to enter it in the enrollment form. To aid you in the process of generating unique PINs for users and adding them to the directory, Certificate Management System provides a command-line tool called the PIN Generator. The section "Using the PIN Generator Tool" explains how to use this tool in detail.

UidPwdPinDirAuth Module

The Java class that implements the directory- and PIN-based authentication method is identified as follows:

com.netscape.certsrv.authentication.UidPwdPinDirAuthentication

 Figure 10.5 shows how configurable parameters of the UidPwdPinDirAuth module are displayed in the CMS window.

Figure 10.5 Parameters defined in the UidPwdPinDirAuth module

Table 10.3 gives details about each of these parameters.

Table 10.3 Description of parameters defined in the UidPwdPinDirAuth module

Parameter
Description
removePin
Specifies whether to remove PINs from the authentication directory (after end users successfully authenticate). Removing PINs from the directory restricts users from enrolling more than once, and thus prevents them from getting more than one certificate.
pinAttr
Specifies the authentication directory attribute for PINs. If you used the PIN Generator utility (provided with Certificate Management System), the attribute is specified by the value of the objectclass parameter; the default value for this parameter is pin. For details, see "Arguments".

Permissible values: Any valid attribute name.

Example: pin

dnpattern
Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:
E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates,
S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).

ldapStringAttributes
Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token--that is, values retrieved from this parameter can be used by policy modules to formulate subject names for certificates or to make other policy decisions. For details, see "Subject Alternative Name Extension Policy".

Entering values for this parameter is optional.

Permissible values: Any valid LDAP string attributes, separated by commas.

Example: mail

(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)

ldapByteAttributes
Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules--that is, values retrieved from this parameter can be used by policy modules to make certain policy decisions or to add additional information to users' certificates.

For example, assume you have defined an LDAP binary attribute for storing users' pictures or fingerprints in your directory. You could develop a policy plug-in that adds users' pictures to their certificates as extensions.

Entering values for this parameter is optional.

Permissible values: Any valid LDAP byte attributes, separated by commas.

Example: jpegPhoto

This sample configuration specifies that the value of the LDAP attribute named jpegPhoto (which is included in the standard inetOrgPerson object class) should be stored in the authentication token and be used to put the user's picture in his or her certificate.

ldap.ldapconn.host
Specifies the host name of the authentication directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: corpDirectory.siroe.com

ldap.ldapconn.port
Specifies the TCP/IP port at which the authentication directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389

ldap.ldapconn.
secureConn
Specifies the type--SSL or non-SSL--of the port at which the authentication directory listens to requests from Certificate Management System.

ldap.ldapconn.
version
Specifies the LDAP protocol version.

Permissible values: 2 or 3.

Example: 3

ldap.ldapauth.bindDN
Specifies the user entry to bind as when removing PINs from the authentication directory. You need to specify this parameter only if you've selected removePin. It is recommended that you create and use a separate user entry that has permission to modify only the PIN attribute in the directory. For example, don't use the directory manager's entry as it has privileges to modify the entire directory content.

Permissible values: A valid bind DN.

Example: CN=pinmanager

password

Specifies the password associated with the DN specified by the ldap.ldapauthbindDN parameter. when you save your changes, the server stores the password in the single sign-on password cache and uses it for subsequent start ups (see "Required Start-up Information").

You need to specify this parameter only if you've selected removePin.

ldap.ldapauth.
clientCertNickname
Specifies the nickname or the friendly name of the certificate to be used for SSL client authentication to the authentication directory in order to remove PINs. Make sure that the certificate is valid and has been signed by a CA that is trusted in the authentication directory's certificate database, and that the authentication directory's certmap.conf file has been configured to correctly map the certificate to a DN in the directory. (This is needed for PIN removal only.)

Permissible values: Enter the name of a currently valid CMS certificate, for example, its SSL server certificate.

Example: Server-Cert

ldap.ldapauth.
authtype
Specifies the authentication type--basic authentication or SSL client authentication--required in order to remove PINs from the authentication directory.

Permissible values: BasicAuth or SslClientAuth.

Example: BasicAuth

ldap.basedn
Specifies the base DN for searching the authentication directory--the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment from) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters.

Example: O=siroe.com

ldap.minConns
Specifies the minimum number of connections permitted to the authentication directory.

Permissible values: 1 to 3.

Example: 3

ldap.maxConns
Specifies the maximum number of connections permitted to the authentication directory.

Permissible values: 3 to 10.

Example: 9


NIS Server-Based Authentication
The NISAuth module implements the NIS server-based authentication. You can use the module for authenticating unprivileged users in the NIS domain during certificate enrollment. The module enables you to deploy Public Key Infrastructure (PKI) leveraging an existing NIS server installation--it enables you to configure a Certificate Manager or Registration Manager to authenticate end users, based on their user IDs and passwords stored in an existing NIS server, and to issue certificates.

 Optionally, you can configure the authentication module to do an LDAP correlation--that is, use the NIS directory to authenticate users based on the user ID and password they enter in the enrollment form, but compose certificate subject names from an LDAP-compliant directory, such as Netscape Directory Server. When using an LDAP directory to compose subject names, you can configure the module to search for and retrieve specific LDAP attribute values from the directory. The ability of the module to use an LDAP directory to form certificate subject names is useful in cases where the NIS server only stores user IDs and passwords and you don't want to formulate subject names using just common names and user IDs.

 In the absence of an LDAP directory, subject names of all certificates issued by the server will be of the form CN=<FirstName LastName>,UID=<UserID>, where First Name and Last Name is a user's first and last names as specified in the NIS directory, and UserID is the user's NIS ID. To accommodate scenarios where the default subject-name form isn't adequate, the module supports a parameter named extendedDN. This parameter enables you to specify a suffix that the server should use for extending the default subject DN pattern.

 Figure 10.6 illustrates how the NIS authentication module works during certificate enrollment.

Figure 10.6 NIS server-based authentication of an end user

These are the steps shown in Figure 10.6:

  1. In the NIS server-based certificate enrollment form, the end user enters his or her user ID and password for the NIS server and submits the request to a Certificate Manager or Registration Manager.
    2.

  2. When the server receives the request, it looks up the NIS server that is configured for authenticating end users. The server verifies the authenticity of the end user by checking the entries.

    3. If, for some reason, the directory to which the server binds for retrieving user attributes is unavailable, the server writes the appropriate LDAP error code to the log. When checking the log for troubleshooting any authentication failures, if you see a log entry with an LDAP error code, look up the corresponding error code at this URL:

    http://help.netscape.com/kb/server/970303-9.html

    A sample log entry with an LDAP error code is shown below:

30/Dec/1999:18:40:25 -0700] conn=0 op=7 RESULT err=32 tag=101 nentries=0 etime=0]
  1. Next, the server subjects the certificate request to policy processing; for details, see "Policies".

NISAuth Module

The Java class that implements the NIS server-based authentication module is identified as follows:

com.netscape.certsrv.authentication.NISAuth

 Figure 10.7 shows how configurable parameters of the NISAuth module are displayed in the CMS window.

Figure 10.7 Parameters defined in the NISAuth module

Table 10.4 gives details about each of these parameters and their values.

Table 10.4 Description of parameters defined in the NISAuth module

Parameter
Description
nisserver
Specifies the NIS server name. (In Unix, use the ypwhich command to find the NIS server name.)

Permissible values: A valid server name.

Example: myServer

nisdomain
Specifies the NIS domain name. (In Unix, use the domainname command to find the domain name.)

Permissible values: A valid domain name.

Example: siroe.com

dnpattern
Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:
E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates,
S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).
extendedDN
Specifies the suffix that the server should use for extending the default subject DN when an LDAP directory for retrieving such information is not specified. The value you specify in this field is used by the sever to suffix the default subject name in certificates, which is in the form CN=<FirstName LastName>,UID=<UserID>.

Example: If you assign OU=People,O=siroe.org,C=US as the extended DN, subject names in certificates would be of this form:
CN=<FirstName LastName>,UID=<UserID>,OU=People, O=siroe.org,C=US

ldapStringAttributes
Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token--that is, values retrieved from this parameter can be used by policy modules to formulate subject names for certificates or to make other policy decisions. For details, see "Subject Alternative Name Extension Policy".

Entering values for this parameter is optional.

Permissible values: Any valid LDAP string attributes, separated by commas.

Example: mail

(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)

ldapByteAttributes
Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end user. If specified, the values corresponding to these attributes will be copied from the LDAP directory into the authentication token for use by other modules--that is, values retrieved from this parameter can be used by policy modules to make certain policy decisions or to add additional information to users' certificates.

For example, assume you have defined an LDAP binary attribute for storing users' pictures or fingerprints in your directory. You could develop a policy plug-in that adds users' pictures to their certificates as extensions.

Entering values for this parameter is optional.

Permissible values: Any valid LDAP byte attributes, separated by commas.

Example: jpegPhoto

This sample configuration specifies that the value of the LDAP attribute named jpegPhoto (which is included in the standard inetOrgPerson object class) should be stored in the authentication token and be used to put the user's picture in his or her certificate.

ldap.ldapconn.host
Specifies the host name of the LDAP directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: corpDirectory.siroe.com

ldap.ldapconn.port
Specifies the TCP/IP port at which the LDAP directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389

ldap.ldapconn.
secureConn
Specifies the type--SSL or non-SSL--of the port at which the LDAP directory listens to requests from Certificate Management System.

Permissible values: true or false.

Example: false

ldap.ldapconn.
version
Specifies the LDAP protocol version of the LDAP directory.

Permissible values: true or false.

Example: 3

ldap.basedn
Specifies the base DN for searching the LDAP directory--the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters.

Example: O=siroe.com

ldap.minConns
Specifies the minimum number of connections permitted to the LDAP directory.

Permissible values: 1 to 3

Example: 2

ldap.maxConns
Specifies the maximum number of connections permitted to the LDAP directory.

Permissible values: 3 to 10

Example: 10


Portal Enrollment
The PortalEnroll module implements portal enrollment. This module enables you to issue certificates and create directory entries for users who do not yet have an entry in the directory. For example, if your company runs a portal service, such as Netscape NetcenterTM, you can use the PortalEnroll module to issue certificates to new users when they register for the online service. You can also use the module to authenticate and issue certificates to your extranet users. For example, if you have deployed extranets for partners and vendors, you can use the module to authenticate and issue certificates to these users when they register for the service.

 The PortalEnroll module does following:

 There are many advantages in issuing certificates to your user community:

 Functionally, the portal authentication module is very similar to the directory-based authentication module (see "Directory-Based Authentication") except that instead of binding to the directory as the enrolling user, Certificate Management System binds as some directory account with permission to create and update user entries. The server then queries the directory for the user name specified by the user and if it doesn't find a match, it adds the entry with all the standard LDAP field names that match the directory attributes.

For example, if the HTTP form input contains data such as surname, common name, and phone number, the corresponding LDAP attributes would be set in the directory; for details, see "Enrollment Forms". The server also uses a combination of these attributes (which you can specify using the dnpattern parameter defined in the module) to construct subject names for certificates.

Note that the portal authentication module by default uses the standard LDAP object class named inetOrgPerson to create and update user entries. The input fields defined in the default portal enrollment form correspond to the attributes defined in this object class as defined in Netscape Directory Server 4.x. The module is capable of reading and writing these attributes only. However, you can customize the module to accommodate all the fields supported by popular portals by extending the directory schema to include a new object class; you'll also be required to update the enrollment form to include attributes corresponding to the new object class. For guidelines on how to customize the module, check the sample located here:

 <server_root>/cms_sdk/samples/authentication

 Figure 10.8 illustrates how the portal authentication module works during certificate enrollment.

Figure 10.8 Portal authentication of an end user

These are the steps shown in Figure 10.8:

  1. In the portal enrollment form, the end user enters registration information, such as a user name or ID, password, first name, last name, and mailing address, and submits the request to the server.
    2.

  2. When the server receives the request, it verifies that the required fields contain appropriate information, for example, the values entered in the Password and Confirm Password fields match. Next, the server looks up the directory that is configured for authenticating portal service users for a matching user name.

    3. If, for some reason, the directory to which the server binds for authenticating the user ID and password is unavailable, the server returns an LDAP error code and writes it to the log. When troubleshooting any authentication failures, if you see a log entry with an LDAP error code, look up the corresponding error code at this URL:

    http://help.netscape.com/kb/server/970303-9.html

    A sample log entry with an LDAP error code is shown below:

28/Jun/1999:18:40:25 -0700] conn=0 op=7 RESULT err=32 tag=101 nentries=0 etime=0]
  1. Next, the server subjects the certificate request to policy processing; for details, see "Policies".

PortalEnroll Module

The Java class that implements the portal authentication plug-in module is identified as follows:

com.netscape.certsrv.authentication.PortalEnroll

 Figure 10.9 shows how configurable parameters for the PortalEnroll module are displayed in the CMS window.

Figure 10.9 Parameters defined in the PortalEnroll module

Table 10.5 gives details about each of these parameters and their values.

Table 10.5 Description of parameters defined in the PortalEnroll module

Parameter
Description
dnpattern
Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:
E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates,
S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).

ldap.ldapconn.host
Specifies the host name of the portal directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: portalDirectory.siroe.com

ldap.ldapconn.port
Specifies the TCP/IP port at which the portal directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389

ldap.ldapconn.
secureConn
Specifies the type--SSL or non-SSL--of the port at which the portal directory listens to requests from Certificate Management System.

ldap.ldapconn.
version
Specifies the LDAP protocol version.

Permissible values: 2 or 3.

Example: 3

ldap.ldapauth.
bindDN
Specifies the user account to bind as in order to create and update user entries in the portal directory. It is recommended that you create and use a separate user account that has permission to create user entries and modify user attributes in the directory. For example, don't use the directory manager's entry as it has privileges to modify the entire directory content.

Permissible values: A valid bind DN.

Example: CN=Portal Registration Manager

password
Specifies the password associated with the DN specified by the ldap.ldapauthbindDN parameter.

Permissible values: As applicable.

ldap.ldapauth.
clientCertNickname
Specifies the nickname or the friendly name of the certificate to be used for SSL client authentication to the portal directory. Make sure that the certificate is valid and has been signed by a CA that is trusted in the portal directory's certificate database, and that the portal directory's certmap.conf file has been configured to correctly map the certificate to a DN in the directory.

Permissible values: Enter the name of a currently valid CMS certificate, for example, its SSL server certificate.

Example: Server-Cert

ldap.ldapauth.
authtype
Specifies the authentication type--basic authentication or SSL client authentication--required to communicate with the portal directory.

Permissible values: BasicAuth or SslClientAuth.

Example: BasicAuth

ldap.basedn
Specifies the base DN for searching the portal directory--the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters.