Add Mapper Rule

Getting there

From the PKI Services Manager console Identity Mapper pane click Add.

NOTE:

As you configure a rule, the constructed rule is displayed at the bottom of the dialog box. For additional information about the rule syntax see PKI Services Manager Map File Reference.
After PKI Services Manager determines that a certificate meets the condition defined in a rule, rule processing stops.
If the map file contains rules of multiple types, PKI Services Manager first tests user-address rules, then user rules, then the "none" rules (which apply to any certificate). PKI Services Manager stops processing rules with the first successful test.

Select the type of certificate that is to be mapped

Specifies whether the rule applies to user or host authentication. Select "Any certificate" to have the rule apply to all authentications.

Apply this rule only to this server

This option is available when the rule type is set to "User Certificate". To apply a rule only to users authenticating to a specific server, enable this setting and then specify the server.

NOTE:When PKI Services Manager evaluates this rule, it uses the server name (not the DNS host name) of the server the user is connecting to. The server sends its name to PKI Services Manager when it requests validation of a user certificate, and PKI Services Manager uses that name when applying the rule. To determine the host name that is sent, you can enter the hostname command from a Windows DOS window or from a UNIX terminal session.

Specify one or more identities for the mapped certificate

Use the text box to specify which identities can authenticate with a valid certificate. Use spaces to separate multiple allowed identities. If an allowed name includes spaces, enclose it in quotes.

For example, to allow users named root, joe, and fred smith to authenticate with a valid certificate, enter:

root joe "fred smith"

Choose certificate identity to insert

Select an item from this drop-down list to construct the allowed identity set based on the contents of the certificate presented for authentication. In the resulting rule, the percent symbol (%) precedes and follows the item you select.

For example, if you are configuring host authentication, you can select "UPN Host" to allow authentication by the host specified in the Host portion of the UPN field. The allowed identity set shows as:

%UPN.Host%

You can combine text strings with extracted information. The following example adds a Windows domain name to an extracted user identity:

windomain\%UPN.User%

NOTE:You can precede a text string with an extracted identity, and/or add a text string after an extracted identity, but you cannot combine more than one extracted value to form a single identity.

Specify how the contents of the certificate affects authentication

Accept claimed identity	When this option is selected, no conditions are set on the identity being mapped. CAUTION:This option allows the listed identities to authenticate with any valid certificate and should therefore be used with caution.
Allow authentication if the following condition is met	When this option is selected, the set of allowed identities can authenticate only if the condition you configure is true. For details, see "Defining Conditions in a Rule" (below).

Defining Conditions in a Rule

A conditional expression takes the form:

Field Operation Argument

For Field, select one of the supported options from the first drop-down list.

For Operation, select one of the following from the second drop-down list:

Contains	Checks if the Field value is contained anywhere within the Argument.
Equals	Checks for absolute equality between the Field value and the Argument value. (This is the only option available if you select Certificate or Serial/Issuer from the first drop-down list.) For DNS, UPN and Email options, the comparison is case-insensitive.
External	Uses an external application to test the condition. Use the Argument box to point to the external application. Set the identity value to "First match," which is a placeholder for the value returned by the external application. PKI Services Manager sends the value of the field you specify in the first drop-down list to the external application. If the test within the external application is successful, it should exit with status 0; a non-zero return means an unsuccessful match. If you select "Certificate" in the first drop-down list, PKI Services Manager passes two arguments to your external application. The first contains the contents of the certificate in PEM format (text). The second argument contains the path to a temporary file that contains a copy of the certificate in DER format (binary). PKI Services Manager deletes the temporary DER formatted certificate when the external application exits.
Regular Expression	Applies the Argument as a regular expression to the Field. If the regular expression includes an exact match to the Field contents, the condition is true.

For Argument, enter text in the last text box. The required text depends on the Field item you have selected. For example, if you select Serial/Issuer, enter the certificate Serial number followed by the Issuer.