Previous Topic: Certificate Mapping and Validity Checking for X.509 CertificatesNext Topic: Certificate Validity Checking (optional)


Certificate Mapping for X.509 Client Authentication Schemes

For the Policy Server to use a certificate to identify a user, it compares the certificate information to a user record in the user directory. A certificate mapping defines how the Policy Server uses the Subject Name from the user certificate to locate a CA SiteMinder® user in a user directory and then authenticate that user.

You can configure certificate mapping for users whose authentication information is stored in a Microsoft SQL Server, Oracle, or LDAP user directory.

More information:

User Directories

Configure a Certificate Mapping

Configure a certificate mapping that lets CA SiteMinder® determine how to compare user certificate information with the information stored in the user directory.

To configure a certificate mapping

  1. Click Infrastructure, Directory.
  2. Click Certificate Mappings.

    The Certificate Mappings page appears.

  3. Click Create Certificate Mapping.

    The Create Certificate Mapping page appears.

    Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

  4. Type the Issuer DN exactly as it appears in the certificate. Do not add any additional spaces or characters.

    When entering the DN, escape reserved special characters with a backslash (\). Special characters include:

    More information about reserved special characters for DNs exists at http://www.faqs.org/rfcs/rfc2253.html.

    Note: If you use a relational database as a policy store, Issuer DNs cannot exceed 255 characters. If you use an LDAP directory as a policy store, verify the character limit for your specific directory.

  5. Select the directory type against which the certificate is mapped.

    For LDAP directories only, you can configure the Policy Server to verify that the certificate the user presents matches the certificate stored in the user record in the user directory. The Certificate Required in Directory option lets you require this verification.

    Note: The attribute in the user record where the certificate is stored is named usercertificate.

  6. Specify how to map X.509 user certificate information to a user entry in the user directory. The Policy Server can apply a mapping using a single attribute, a custom mapping expression, or the entire Subject Name from the user certificate to locate the correct user entry.
  7. Select an attribute name from the list.
  8. Click Test to test the certificate mapping.
  9. (Optional) Select Perform CRL Checks and specify the CRL settings.

    If you do not select CRLs, you can use OCSP.

  10. Click Submit.

    The certificate is mapped with the selected user directory.

More information:

Certificate Validity Checking (optional)

Test a Certificate Mapping

Testing a certificate mapping displays the search string the Policy Server is to use to map client certificates to user directory attributes.

To test a certificate mapping

  1. Open the certificate mapping.
  2. Click Test in Mapping group box.

    The Certificate Map Test group box opens.

  3. Select a user directory connection from the Directory list.

    Note: The Directory list includes all of the existing directory connections of the type you selected when creating the certificate mapping.

    The contents of the Directory Information group box change based on the type of user directory connection. For WinNT, ODBC and OCI user directory connections, the group box displays the Directory Type you are testing. For LDAP directory connections, the group box displays the Directory Type, as well as the Lookup Start and Lookup End values used to locate a user’s DN within the LDAP directory.

    The Policy Server tests the certificate mapping and the Certificate Map Test group box provides the results.

    Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

  4. Click Close.

    The Certificate Map Test group box closes.

Custom Mapping Expressions

You can use custom mapping expressions for complex multiple attribute mapping. This allows you to specify multiple user attributes that should be extracted from a user DN to establish a certificate mapping.

Note: Custom mapping expressions are also useful when simulating certificate-based authentications through the CA SiteMinder® Test Tool.

The syntax for a custom mapping expression is a parsing specification designed to enable full mapping flexibility. It indicates which information to take from the certificate and where it should be applied to in the user directory. The basic syntax is as follows:

UserAttribute=%{CertificateAttribute},
UserAttribute2=%{CertificateAttribute}

More information:

Certificate-based Authentication Tests

EnableCustomExprOnly Registry Key

When you create a custom certificate mapping for an LDAP user directory, the resulting search query string includes the LDAP User DN Lookup Start and End strings in addition to the Mapping Expression that you specify on the Create Certificate Mapping pane. The resulting query is invalid, as seen in the following example:

LDAP User DN Lookup Start

(samAccountName=

LDAP User DN Lookup End

)

Certificate Mapping Expression

(mail=%{E})

Resulting Search Query

(samAccountName=(mail=%{E}))

To omit the User DN Lookup Start and End strings from the search query, navigate to \Netegrity\SiteMinder\CurrentVersion\PolicyServer\ and set the EnableCustomExprOnly registry key to 1. The resulting search query string is valid, as seen in this example:

Certificate Mapping Expression

mail=%{E}

Resulting Search Query

mail=%{E}

Note: If the EnableCustomExprOnly registry key is 0 (the default) or the key does not exist, the User DN Lookup Start and End strings are included in the resulting search query.

Enable LegacyCertMapping Registry Key

Using LDAP syntax to create search filters that contain logic operators requires you to enable the LegacyCertMapping registry key. Enabling the registry key allows legacy behavior in certificate mapping, which ensures that users are authenticated using the specified LDAP search criteria.

LegacyCertMapping

KeyType: DWORD

Values: 0 (disabled) and 1 (enabled)

Default: 0

To enable the registry key on Windows

  1. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Netegrity\SiteMinder\CurrentVersion\
    PolicyServer, and open LegacyCertMapping.
  2. Edit the KeyType value to REG_DWORD.
  3. Edit the Values value to 1.

    Note: If a value other than 0x1 is set, or the registry value does not exist, the registry key is disabled.

  4. Save the registry key.

    LegacyCertMapping is enabled, and LDAP search filter syntax can be used with custom mapping.

To enable the registry key on UNIX

  1. Open the sm.registry file.
  2. Add the following lines to the file:
    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Netegrity\SiteMinder\CurrentVersion\
    PolicyServer=XXXXX
    LegacyCertMapping=0X1 REG_DWORD
    
  3. Save the file.

    LegacyCertMapping is enabled, and LDAP search filter syntax can be used with custom mapping.

Custom Mapping: Example 1

If a user’s certificate contains:

SubjectDN: CN=John Smith, UID=JSMITH, OU=development, O=CompanyA

You can specify the following custom mapping:

CN=%{UID}, OU=%{OU}, O=%{O}

The resulting UserDN is:

CN=JSMITH, OU=development, O=CompanyA

Custom Mapping: Example 2

The custom mapping syntax also handles more complex mappings, as illustrated in the example:

If the user’s certificate contains:

Subject DN: CN=John Smith + UID=jsmith +EMAIL=jsmith@companyA.com, ou=development, o=companyA

You can specify the following custom mapping:

CN=%{CN.CN}+UID=%{CN.UID}, OU=%{O}

The resulting UserDN is:

CN=John Smith+UID=JSMITH, OU=companyA

In the above example, the CN contained multiple attributes. The syntax indicated which components of the CN to take and apply to the UserDN’s CN. This was done by specifying “CN.CN or CN.UID” This syntax indicates that the custom expression uses both the CN and UID parts of the CN.

Note: You cannot use the “+” operator to disambiguate multiple attributes in a user directory. The “+” operator is used like any other character in the user DN for a user that is present in the user directory.

Custom Mapping: Example 3

Static text can be represented in a custom expression by leaving it outside of the bracket notation as shown below.

The user’s certificate contains:

Subject DN: CN=John Smith, UID=JSMITH, OU-development

You can specify the following mapping:

CN=%{UID}, OU=%{OU}, O=companyA

The resulting UserDN is:

CN=JSMITH, OU=development, O=CompanyA

For more information, see the next section.

Template String Usage

The template string is composed of text and hash-bracketed expressions %{…}. All text outside the brackets is returned unchanged. The hash-bracketed expressions are evaluated based on the following rules:

Map to the Certificate Serial Number or IssuerDN

Certificate Mapping supports mapping of the CertSerialNumber and IssuerDN attributes, which are not part of the subjectDN. These attribute(s) in the subjectDN of user certificates can be mapped to default or custom user-attribute(s), such as UID or CN in the user directory.

To map these attributes, add the following in the Mapping Expressions field in the Certificate Mapping pane:

Custom Certificate Mapping for Multiple Attributes of the Same Type

Some certificates may have multiple attributes of the same type in their Subject DN. CA SiteMinder® supports a simple method for using a custom certificate mapping to see attributes other than the first attribute of a particular type. The syntax is as follows:

%{attribute_name} for the first occurrence of attribute_name

%{attribute_nameN} for the Nth occurrence of attribute_name

If the Subject DN of the certificate contained CN=user,ou=dev,sn=1234,sn=2345,sn=3456,o=company,c=us, you could set up a custom certificate mapping to any of the sn attributes. For example, to map to the first sn, enter %{sn} as the custom mapping. To map to the second sn, you could enter %{sn2} as the custom mapping.

Map to Non-Required Attributes

Sometimes certificates for individuals may be slightly different. For example, some users may have two account numbers, while others have a single number. In these cases, you may want to map to the second of the numbers when a second attribute exists. You can do so using the following notation:

%{attribute_name2/attribute_name}

Using the example from above, you could enter %{SN2/SN} as a custom mapping to indicate that the second number in the Subject DN should be used if it exists, otherwise, the first occurrence of the account number attribute should be used.

This notation can also be used to specify two different attributes that are acceptable for a certificate mapping. For example, to indicate that the SN should be used, but a CN may be used if the SN does not exist, you could enter %{SN/CN}.