Certificate Mapping for X.509 Client Certificate 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  user in a user directory and then authenticate that user.
sm1252sp1
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 Single Sign-On
 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.
2
Configure a Certificate Mapping
To determine how to compare user certificate information with the information stored in the user directory, configure a certificate mapping.
Follow these steps:
  1. Click Infrastructure, Directory.
  2. Click Certificate Mappings.
  3. Click Create Certificate Mapping.
  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:
    • Comma (,)
    • Semicolons (;)
    • Quotes (")
    • Backslashes (\)
    • Plus character (+)
    • Greater than character (>)
    • Less than character (<)
    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.
    For information about reserved special characters for DNs, see RFC 2253.
  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 that is stored in the user record in the user directory. The Certificate Required in Directory option lets you require this verification.
    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 one of the following properties to locate the correct user entry:
    • A single attribute
    • A custom mapping expression
    • The entire Subject Name from the user certificate
  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.
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.
Follow these steps:
  1. Open the certificate mapping.
  2. Click Test in the Mapping section.
    The Certificate Map Test pane opens.
  3. Select a user directory connection from the Directory list.
    The Directory list includes all the existing directory connections of the type you selected when creating the certificate mapping.
    The contents of the Directory Information group box change depending 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 and the Lookup Start and Lookup End values used to locate a user DN within the LDAP directory.
    The Policy Server tests the certificate mapping and the Certificate Map Test group box provides the results.
  4. Click Close.
    The Certificate Map Test group box closes.
Custom Mapping Expressions
You can use custom mapping expressions for complex multiple attribute mapping. Custom mapping expressions allow you to specify multiple user attributes to extract from a user DN to establish a certificate mapping.
Custom mapping expressions are also useful when simulating certificate-based authentications through the Test Tool.
The syntax for a custom mapping expression is a parsing specification that is designed to enable full mapping flexibility. The syntax indicates which information to take from the certificate and where to apply it in the user directory. The basic syntax is as follows:
UserAttribute=%{CertificateAttribute}
To specify multiple name/value pairs, separate each pair with a comma (",") or plus sign ("+").
Examples
:
UserAttribute1=%{CertificateAttribute},UserAttribute2=%{CertificateAttribute}
UserAttribute1=%{CertificateAttribute}+UserAttribute2=%{CertificateAttribute}
Configure How Custom Mapping Expressions Are Processed to Create LDAP Search Query Strings 
By default, when a custom mapping expression is configured, the LDAP search query string is constructed as follows:
[
LDAP User DN Lookup Start string
][
Custom Mapping Expression
][
LDAP User DN Lookup End string
]
This format can result in invalid search query strings 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}))
You can configure the Policy Server to omit the User DN Lookup Start Strings that begin with "(" and End Strings that end with ")". To configure the Policy Server to omit such strings from the search query, enable the EnableCustomExprOnly registry key.
  • EnableCustomExprOnly 
    KeyType: DWORD
    Values: 0 (disabled) and 1 (enabled)
    Default: 0
To enable the
EnableCustomExprOnly
registry key on Windows
  1. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Netegrity\SiteMinder\CurrentVersion\PolicyServer, and open EnableCustomExprOnly.
  2. Edit the KeyType value to REG_DWORD.
  3. Edit the Values value to 1.
    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.
    EnableCustomExprOnly is enabled.
The resulting search query strings are now valid, 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 = (mail=%{E})
: Only User DN Lookup Start Strings that begin with "(" and End Strings that end with ")" are omitted when EnableCustomExprOnly is enabled. If the DN Lookup Start String does not begin with "(" or the End String does not end with ")", they are still included in the search query string. For example:
  • LDAP User DN Lookup Start = xxx
  • LDAP User DN Lookup End = yyy
  • Certificate Mapping Expression = (mail=%{E})
  • Resulting Search Query = xxx(mail=%{E})yyy
Configure Support for Logic Operators in LDAP Syntax Search Filters
To use LDAP syntax to create search filters that contain logic operators, 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
LegacyCertMapping 
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.
    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 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 certificate contains:
Subject DN: CN=John Smith + UID=jsmith [email protected], 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 previous example, the CN contained multiple attributes. The syntax indicated which components of the CN to take and apply to the CN of the UserDN by specifying “CN.CN or CN.UID.” This syntax indicates that the custom expression uses both the CN and UID parts of the CN.
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.
The user 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
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:
  • Undistinguished variable names (For example, DN) are resolved before being returned.
  • Distinguished variable names (for example, DN.UID) are resolved to the variable component before being returned.
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 attributes in the subjectDN of user certificates can be mapped to default or custom user-attributes, such as UID or CN in the user directory.
To map these attributes, add the following notation in the Mapping Expressions field in the Certificate Mapping pane:
  • CustomAttributeinLDAP1 = %{CertSerialNumber}
Custom Certificate Mapping for Multiple Attributes of the Same Type
Some certificates can have multiple attributes of the same type in their Subject DN.
CA Single Sign-On
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
For example, If the Subject DN of the certificate contains the following attributes, you can set up a custom certificate mapping to any of the sn attributes:
CN=user,ou=dev,sn=1234,sn=2345,sn=3456,o=company,c=us
So, 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 can be slightly different. For example, some users can have two account numbers, while others have a single number. In these cases, you can map to the second of the numbers when a second attribute exists. You can do so using the following notation:
%{attribute_name2/attribute_name}
In the previous example, 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 can be used if the SN does not exist, you can enter %{SN/CN}.