5.5.2 Configuring Attribute Mappings

  1. Step 3 of the wizard or click Devices > Identity Servers > Edit > Local > Classes > [Name of X.509 class] > Properties > Attributes.

  2. Configure attribute mappings.

    Option

    Description

    Show certificate errors

    Select to displays an error page when a certificate error occurs. This option is not selected by default.

    Auto Provision X509

    Select to enables automatic provisioning of users for X.509 authentication.

    This option enhances the security of X.509 authentication when using a less secure way of authentication, such as username/password. Additional security measures include manual intervention to activate X.509 authentication by adding an additional attribute that is checked during authentication. For example, when a user authenticates with an X.509 certificate, Access Manager looks up for a matching SASallowableSubjectNames with the name of the user certificate. If no match is found and Auto Provision X509 is enabled, an error page is displayed that prompts the user to specify additional credentials such as a username/password or to start an optional Identity Manager workflow. If the authentication is successful, the user’s SASallowableSubjectNames attribute is filled with the name of the user certificate.

    When Auto Provision X509 is enabled and the attribute that is used for subject name mapping is changed from the default sasAllowableSubjectNames, ensure that the LDAP attribute that is used can store string values as long as the longest client certificate subject name. For example, if you use the LDAP attribute title (which has an upper bound of 64 characters), the Auto Provision X509 fails the provisioning part of the authentication if the client certificate subject name is longer than 64 characters. The authentication works if a valid name and password is given, but provisioning fails.

    Attributes

    Select attributes from Available attributes used for matching. If multiple attributes are specified, the evaluation of these attributes must resolve to only one user in the user store.

    Access Manager first does a DN lookup for subject name or directory name mapping. If this fails, the rest of the mappings are looked up in a single LDAP query.

    Available attributes

    The list of available X.509 attributes. To use an attribute, select it and move it to Attributes.

    • Directory name: Searches for the directory address in the client certificate and tries to match it to the DN of a user in the user store. If that fails, it searches the sasAllowableSubjectNames attribute of all users for a value that matches. The sasAllowableSubjectNames attribute must contain values that are comma-delimited, with a space after the comma. (For example, O=CURLY, OU=Organization CA or OU=Organization CA, O=CURLY.)

    • Email: Searches for the email attribute in the client certificate and tries to match it with a value in the LDAP mail attribute.

    • Serial number and issuer name: Lets you match a user’s certificate by using the serial number and issuer name. The issuer name and the serial number must be put into the same LDAP attribute of the user, and the name of this attribute must be listed in the Attribute Mappings section.

      When using a Case Ignore String attribute, both the issuer name and the serial number must be in the same attribute separated by a dollar sign ($) character. The issuer name must precede the $ character, with the serial number following the $ character. Do not use any spaces preceding or following the $ character. For example: O=CURLY, OU=Organization CA$21C0562C5C4

      The issuer name can be from root to leaf or from leaf to root. The issuer name must be comma-delimited with a space after the comma. (For example, O=CURLY, OU=Organization CA or OU=Organization CA, O=CURLY.)

      The serial number cannot begin with a zero (0) or with a hexadecimal notation (0x). If the serial number is 0x0BAC05, the value of the serial number in the attribute must be BAC05. The certificate number is displayed in Internet Explorer with a space after every fourth digit. However, you must enter the certificate number without using spaces.

      The LDAP attribute can be any Case Ignore List or Case Ignore String attribute of the user. If you are configuring your own attribute, ensure that the attribute is added to the Person class. When using a Case Ignore List attribute, both the issuer name and the serial number must be on the same list. The issuer name needs to be the first item on the list, with the serial number being the second and last item on the list.

    • Subject name: Searches for the Subject name of the client certificate and tries to match it to the DN of a user in the user store. If that fails, it searches the sasAllowableSubjectNames attribute of all users for a value that matches the Subject name of the client certificate. The sasAllowableSubjectNames attribute must contain values that are comma-delimited, with a space after the comma. (For example, O=CURLY, OU=Organization CA or OU=Organization CA, O=CURLY.)

    Attribute Mappings

    This option allows to specify how Identity Server maps the certificate to a user in the user store. Subject name is the default map.

    When an attribute is moved to Attributes, you can modify the mapping name here. The mapped name must match an attribute in your LDAP user store.

    You can also configure regular expression for attributes to use a partial value of the X.509 certificate attribute for searching users. See Regular Expression for Extracting the Partial String from DN.

  3. Click Finish.

  4. Create a method for this class.

    During step-up authentication with X509 method as primary method, if a user specifies a different username while authentication for secondary method, an error is displayed. While configuring a method, configure the following property to enable customizing this error message.

    Property: PRINCIPAL_MISMATCH_ERR

    Value: provide string to display on user principal mismatch

    If this property is not configured, the default intruder detection error is displayed to users.

    For instructions, see Section 5.1.3, Configuring Authentication Methods.

  5. Create a contract for the method:

    For instructions, see Section 5.1.4, Configuring Authentication Contracts.

    If you want the user’s credentials available for Identity Injection policies, add the password fetch method as a second method to the contract. For more information about this class and method, see Section 5.16.4, Password Retrieval.

  6. Update Identity Server.