pki_mapfile Map File Reference

Reflection PKI Services Manager mapping binds certificates to one or more allowed identities using mapping rules. Typically, allowed identities are users or hosts. For SSH connections, to authenticate a user correctly, you need to define a rule that links information in the validated certificate to an allowed user account. The mapper provides flexible options for mapping certificates to names. You can specify allowed names explicitly in your rules, or define rules that extract information, such as user or host name, from a certificate. By using these options, you can bind identities to certificates without having to create a separate rule for each certificate. Some PKI Services Manager client applications, including Reflection Security Gateway, use PKI Services Manager for certificate validation only, and do not require any identity mapping.

The default map filename and location is:

File Format

The map file consists of keyword settings and rules. Each rule is a single line and is independent of other rules. The format of a rule is:

{Allowed-Identity} [Conditional Expression]

After a certificate is determined to be valid, rules are processed in order (based on rule type then sequence). If the certificate meets the requirements defined in the conditional expression (or if the rule has no condition), the allowed identities specified in that rule are allowed to authenticate. No additional rules are applied after the first match.

Within the map file, you can use the RuleType keyword to apply different mapping criteria based on whether a user or host presents the certificate. Note: Rule type determines the order in which rules are processed. The order for processing user certificates is: user-address, user, none. The order for processing host certificates is: host, none. Within each rule type, rules are processed in order from top to bottom.

Allowed Identity Set

The allowed identity set is a required component of a rule. Allowed identities can be specified using a combination of constant values and values extracted from the certificate. The set of allowed identities can take multiple constant values, extracted values, or a combination of both. The identity mapping requirements for PKI Services Manager clients vary. For example: The Reflection for Secure IT server supports multiple formats for specifying domain user names in map rules. The Reflection for Secure IT User Manager requires that only one user be allowed for any valid certificate. For additional information refer to information about configuring validation using Reflection for Secure IT in your product documentation.

Using constant values to define allowed identities

Constant values are literal strings. Use white space to delimit separate values. (If an allowed name includes spaces, enclose it in quotes.) For example, the following rule uses literal strings to allow root, joe, and fred smith to authenticate with any valid certificate:

{ root joe "fred smith" }

Two asterisks used alone { ** } act as a wildcard for defining the allowed identity set. This option may be useful for testing, but should otherwise be used only with extreme caution. If you use this wildcard in a user rule, any user presenting a valid certificate is allowed to authenticate to any user account on the server. This creates a major security risk by allowing access to accounts with root, administrator, or power user privileges without requiring a password. If you use this wildcard in a host rule, any server with a valid certificate is accepted by the client. If you do choose to use the wildcard, consider limiting access using other options:

Using values extracted from the certificate

Use extracted values to construct the allowed identity set based on the contents of the certificate presented for authentication. Extracted values must be preceded and followed by "%". For example, to allow authentication by the host specified in the Host portion of the UPN field:

{ %UPN.Host% }

You can also combine literal strings with extracted identities. (You can prepend a literal string to an extracted identity, and/or append a literal string, but you cannot combine more than one extracted value to form a single identity.) The following example adds a Windows domain name to an extracted user identity:

{ windomain\%UPN.User% }

Note: If the extracted identity evaluates to an empty result, the entire concatenated string is deemed to be empty and is not included in the set of allowed identities. If the entire set of allowed identities is empty, the rule is deemed to have failed and processing continues to the next rule.

Supported certificate fields are:

Conditional Expression

When a conditional expression follows the {Allowed-Identity}, the allowed identities can authenticate only if the conditional expression is true. The use of a conditional expression is optional, but in most cases is recommended. If no conditional expression is included, the allowed identities can authenticate with any valid certificate.

After a certificate is determined to be valid, rules are processed in order (based on rule type then sequence). If the certificate meets the requirements defined in the conditional expression (or if the rule has no condition), the allowed identities specified in that rule are allowed to authenticate. No additional rules are applied after the first match.

The syntax for a conditional expression is:

Field Operation Argument

For Field, specify any of these supported certificate fields (described above): Subject, Subject.CN, Subject.Email, DNS, IPAddress, UPN, UPN.User, UPN.Host, Email, Email.Host, SerialAndIssuer, Cert, or subst.

For Argument, specify a string value.

For Operation, use one of the following:

Sample rules with conditional expressions:

{ %UPN.Email% } Subject.CN Equals acme.com

{ joep } Subject Contains "Joe Plumber"

Rule Type Stanzas

Rule types apply different mapping criteria based on whether the validated certificate is a user certificate or a host certificate. Use the RuleType keyword to create a new stanza for each supported type. A stanza ends at the next RuleType keyword or the end of the file. The format is:

RuleType type

Valid rule types are:

Keywords