Configuring X509 Certificate Authentication

Use the following information and procedures to configure X509 Certificate Authentication for Identity Manager.

Configuration Prerequisites

To support X509 certificate-based authentication in Identity Manager, ensure that two-way (client and server) SSL authentication is configured properly. From the client perspective, this means that an X509-compliant user certificate should have been imported into the browser (or be available through a smart card reader), and that the trusted certificate used to sign the user certificate should be imported into the Web application server’s keystore of trusted certificates.

Also, the client certificate used must be enabled for client authentication.

To Verify that the Client Certificate’s Client Authentication Option is Selected

1. Using Internet Explorer, select Tools, and then select Internet Options.

2. Select the Content tab.

3. In the Certificates area, click Certificates.

4. Select the client certificate, and then click Advanced.

5. In the Certificate Purposes area, verify that the Client Authentication option is selected.

Configuring X509 Certificate Authentication in Identity Manager

To Configure X509 Certificate Authentication

1. Log in to the Administrator Interface as Configurator (or with equivalent permissions).

2. Select Configure, and then select Login to display the Login page.

3. Click Manage Login Module Groups to displays the Login Module Groups page.

4. Select a login module group from the list.

5. Select Identity Manager X509 Certificate Login Module from the Assign Login Module list. Identity Manager displays the Modify Login Module page.

6. Set the login success requirement.

   The following values are acceptable:

   • Required. The login module is required to succeed. Irrespective of whether it succeeds or fails, authentication proceeds to the next login module in the list. If it is the only login module, the administrator is successfully logged in.

   • Requisite. The login module is required to succeed. If it succeeds, authentication proceeds to the next login module in the list. If it fails, authentication does not proceed.

   • Sufficient. The login module is not required to succeed. If it does succeed, authentication does not proceed to the next login module, and the administrator is successfully logged in. If it fails, authentication continues to the next login module in the list.

   • Optional. The login module is not required to succeed. Irrespective of whether it succeeds or fails, authentication continues to the next login module in the list.

7. Select a login correlation rule. This could be a built-in rule or a custom correlation rule. (See the following section for information about creating custom correlation rules.)

8. Click Save to return to the Modify Login Module Group page.

9. Optionally, reorder the login modules (if more than one login module is assigned to the login module group, and then click Save.

10. Assign the login module group to a login application if it is not yet assigned. From the Login Module Groups page, click Return to Login Applications, and then select a login application. After assigning a login module group to the application, click Save.

    ---

    Note –

    If the allowLoginWithNoPreexistingUser option is set to a value of true in the waveset.properties file, then when configuring the Identity Manager X509 Certificate Login Module, you are prompted to select a New User Name Rule. This rule is used to determine how to name new users created when one is not found by the associated Login Correlation Rule. The New User Name Rule has the same available input arguments as the Login Correlation Rule. It returns a single string, which is the user name used to create the new Identity Manager user account. A sample new user name rule is included in idm/sample/rules, named NewUserNameRules.xml.

    ---

Creating and Importing a Login Correlation Rule

A Login Correlation Rule is used by the Identity Manager X509 Certificate Login Module to determine how to map the certificate data to the appropriate Identity Manager user. Identity Manager includes a built-in correlation rule, named Correlate via X509 Certificate subjectDN.

You can also add your own correlation rules. Refer to LoginCorrelationRules.xml, which is located in the idm/sample/rules directory, as an example.

Each correlation rule must follow these guidelines:

• Its authType attribute must be set to LoginCorrelationRule

• It is expected to return an instance of a list of AttributeConditions to be used by the login module to find the associated Identity Manager user. For example, the login correlation rule might return an AttributeCondition that searches for the associated Identity Manager user by email address.

Arguments passed to login correlation rules are:

• Standard X509 certificate fields (such as subjectDN, issuerDN, and valid dates)

• Critical and noncritical extension properties

The naming convention for certificate arguments passed to the login correlation rule is

cert.field name.subfield name

Example argument names that are available to the rule include:

• cert.subjectDN

• cert.issuerDN

• cert.notValidAfter

• cert.notValidBefore

• cert.serialNumber

The login correlation rule, using the passed-in arguments, returns a list of one or more AttributeConditions. These are used by the Identity Manager X509 Certificate Login Module to find the associated Identity Manager user.

A sample login correlation rule is included in idm/sample/rules, named LoginCorrelationRules.xml.

After creating a custom correlation rule, you must import it into Identity Manager. From the Administrator Interface, select Configure, and then select Import Exchange File to use the file import facility.

Testing the SSL Connection

To test the SSL connection, go to the configured application interface’s URL using SSL (for example, https://idm007:7002/idm/user/login.jsp). You are notified that you are entering a secure site, and then prompted to specify which personal certificate to send to the Web server.

Diagnosing Problems

Report any problems authenticating using X509 certificates as error messages on the login form.

For more complete diagnostics, enable trace on the Identity Manager server for these classes and levels:

• com.waveset.session.SessionFactory 1

• com.waveset.security.authn.WSX509CertLoginModule 1

• com.waveset.security.authn.LoginModule 1

If the client certificate attribute is named something other than javaxservlet.request.X509Certificate in the HTTP request, then you will receive a message that this attribute cannot be found in the HTTP request.

To Correct a Client Certificate Attribute Name in an HTTP Request

1. Enable trace for SessionFactory to see the complete list of HTTP attributes and determine the name of the X509 Certificate.

2. Use the Identity Manager debug facility (The Identity Manager Debug Page) to edit the LoginConfig object.

3. Change the name of the <AuthnProperty> in the <LoginConfigEntry> for the Identity Manager X509 Certificate Login Module to the correct name.

4. Save, and then retry.

   You may also need to remove, and then re-add the Identity Manager X509 Certificate Login Module in the login application.