+

Search Tips   |   Advanced Search

Enable client certificate login support for a file-based repository in federated repositories

We can enable support for client certificate login in a realm configured with a single built-in file-based repository or a multiple repository configuration that includes the file-based repository and other repositories.

The federated repositories configuration must include a file-based repository. See the topic, Use a single built-in, file-based repository in a new configuration under Federated repositories.

The default configuration of the built-in file-based repository ignores a certificate login request, returns an empty search result, and does not display any error.

To enable client certificate login for the built-in file-based repository, complete the following steps to set custom properties.


Tasks

  1. In the administrative console, click Security > Global security.

  2. Under User account repository, select Federated repositories from the Available realm definitions field and click Configure.

    To configure for a specific domain in a multiple security domain environment, click Security domains > domain_name. Under Security Attributes, expand User Realm, and click Customize for this domain. Select the Realm type as Federated repositories and then click Configure.

  3. Under Related items, click Manage repositories and then click the InternalFileRepository link.

  4. To enable certificate login for the file-based repository, under Custom properties, enter the property name as certificateMapMode. Specify one of the following values for this property according to your requirement:

    Property names are case-sensitive, while property values are not case-sensitive.

    notSupported

    An error is displayed informing the user that the file-based repository does not support certificate login.

    exactDNMode

    Login is attempted by mapping the PrincipalName value in the X.509 certificate to the exact distinguished name (DN) in the repository. If a matching entity is found, login is successful. If a matching entity is not found, an error stating that the entity is not found is displayed.

    filterDescriptorMode

    Login is attempted using the certificate filter for the mapping. If a single matching entity is found, the login is successful. If more than one matching entity is found, the authentication fails because the result is an ambiguous match and an error is displayed.

    If we do not specify a valid value, an error is logged during initialization of the file adapter and an empty search result is returned.

  5. If we set the value of the certificateMapMode property to filterDescriptorMode, then we must add another custom property, certificateFilter. The certificateFilter custom property specifies the filter that maps attributes in the client certificate to entries in the repository.

    This step is not required if we set the value of the certificateMapMode property to notSupported or exactDNMode.

    1. Under Custom properties, click New.

    2. In the new row, enter the property name as certificateFilter. Specify the filter expression as the value for this property.

    The syntax or structure of this filter is Repository attribute=${Client certificate attribute}, for example, uid='${SubjectCN}'.

    The following conditions apply to the syntax of the certificate filter for file repositories:

    • The part of the filter specification that precedes the equals sign (=) must be a valid property for PersonAccount in the file-based repository.

    • The part of the filter specification that follows the equals sign (=) is one of the public attributes in the client certificate. It must begin with a dollar sign ($) and open bracket ({) and end with a close bracket (}).

    • Enclose data for all federated repository string properties within single quotation marks ('). For example, the federated repository property cn is a string; so a certificate filter that uses this property is specified as cn='${IssuerCN}'.

    Use the following certificate attribute values on the part of the filter specification that comes after the equals sign (=). The case of the strings is important.

    • ${UniqueKey}
    • {PublicKey}
    • {PublicKey}
    • {Issuer<xx>} where <xx> is replaced by the characters that represent any valid component of the Issuer Distinguished Name. For example, we might use ${IssuerCN} for the Issuer Common Name.
    • ${NotAfter}
    • ${NotBefore}
    • ${SerialNumber}
    • ${SigAlgName}
    • ${SigAlgOID}
    • ${SigAlgParams}
    • ${Subject<xx>} where <xx> is replaced by the characters that represent any valid component of the Subject Distinguished Name. For example, we might use ${SubjectCN} for the Subject Common Name.
    • ${Version}

    The following examples are complex certificate filters for the file repository:

    • ((cn='${IssuerCN}') and (mobile=${SerialNumber}) and (seeAlso='${SubjectDN}'))
    • ((employeeNumber=${SerialNumber}) or (seeAlso='${SubjectDN}')

    There are several differences between the syntax used to specify certificate filters for LDAP repository and file repository, as shown in the following table.

    File repository certificate filters LDAP repository certificate filters
    Use infix notations. Use prefix notations.
    Use the logical operators and and or. Use the logical operators ampersand (&) and vertical bar (|)
    Data for all federated repository string properties must be enclosed within single quotation marks ('), Data for federated repository string properties does not have to be enclosed within single quotation marks ('),
    Example: 
    cn='${Issuer	CN}' and mobile=${SerialNumber})
    		Example: 
    (& (cn=${IssuerCN}) (mobile=${SerialNumber}))

  6. Save the configuration changes and restart WebSphere Application Server for the changes to take effect.


Add custom properties using wsadmin commands

Alternately, we can also use wsadmin commands to add the custom properties as shown in the following steps.


Tasks

  1. Start wsadmin. 
    wsadmin -conntype none

  2. Use the setIdMgrCustomProperty command to add custom properties. 
    $AdminTask setIdMgrCustomProperty { -id InternalFileRepository -name certificateMapMode -value mode}
$AdminTask setIdMgrCustomProperty { -id InternalFileRepository -name certificateFilter -value filter_expression}

    For example, the following command searches for a user whose CN has the value specified by the IssureCN property of the certificate:

    $AdminTask setIdMgrCustomProperty { -id InternalFileRepository -name certificateFilter -value "cn='${IssuerCN}'"}

    The following command searches for a user whose CN has the value specified by the IssuerCN property of the certificate and whose mobile matches the SerialNumber property of the certificate.

    $AdminTask setIdMgrCustomProperty { -id InternalFileRepository -name certificateFilter -value "cn='${IssuerCN}' and mobile=${SerialNumber}"}

  3. Save the configuration changes. 
    $AdminConfig save

  4. Restart WebSphere Application Server for the changes to take effect.


Results

After completing these steps, support for certificate login for file-based repository is enabled in the federated repositories as shown in the following entries of the file adapter configuration: 

<config:CustomProperties name="certificateMapMode" value="mode"/>
<config:CustomProperties name="certificateFilter" value="filter_expression"/>

If the certificate login request is honored, login is successful. If the certificate login request is rejected, an error is displayed.

If only file repository is configured under federated repositories, the results of the certificate login request are as described in the following table.

File repository Expected results
Default behavior (certificateMapMode custom property is not added) Certificate login request is ignored, an empty result is returned, and no error is displayed
Certificate login is not supported (value of certificateMapMode custom property is notSupported) CertificateMapNotSupportedException occurs
Certificate login is supported (value of certificateMapMode custom property is exactDNMode or filterDescriptorMode) and user is not found EntityNotFoundException occurs
Certificate login is supported (value of certificateMapMode custom property is exactDNMode) and an entity with DN that matches the PrincipalName in the certificate is found Certificate login is successful
Certificate login is supported (value of certificateMapMode custom property is filterDescriptorMode) and a single matching entity is found Certificate login is successful
Certificate login is supported (value of certificateMapMode custom property is filterDescriptorMode) and more than one matching entities are found CertificateMapFailedException occurs and "Multiple principals found" error message is displayed

If multiple repositories are configured under federated repositories, the final login result depends on the behavior and results returned from the other repositories. The following tables contain examples of errors displayed in various configuration scenarios.

File repository LDAP repository Expected results
Default behavior Certificate login is supported and user is found Certificate login is successful
Default behavior Certificate login is supported and user is not found PasswordCheckFailedException occurs
Certificate login is not supported Certificate login is supported and user is found CertificateMapFailedException occurs
Certificate login is supported and user is found Certificate login is supported and user is found DuplicateLogonIdException occurs
Certificate login is supported and user is found Certificate login is supported and user is not found Certificate login is successful
Certificate login is supported and user is not found Certificate login is supported and user is found Certificate login is successful
Certificate login is supported and user is not found Certificate login is supported and user is not found PasswordCheckFailedException occurs

File repository Local operating system repository Expected results
Default behavior Certificate login is not supported CertificateMapFailedException occurs
Certificate login is not supported Certificate login is not supported CertificateMapNotSupportedException occurs
Certificate login is supported and user is found Certificate login is not supported CertificateMapFailedException occurs
Certificate login is supported and user is not found Certificate login is not supported CertificateMapFailedException occurs
Default behavior Certificate login is supported and user is found Certificate login is successful
Default behavior Certificate login is supported and user is not found PasswordCheckFailedException occurs
Certificate login is not supported Certificate login is supported and user is found CertificateMapFailedException occurs
Certificate login is supported and user is found Certificate login is supported and user is found DuplicateLogonIdException occurs
Certificate login is supported and user is found Certificate login is supported and user is not found Certificate login is successful
Certificate login is supported and user is not found Certificate login is supported and user is found Certificate login is successful
Certificate login is supported and user is not found Certificate login is supported and user is not found PasswordCheckFailedException occurs

Related tasks:

  • IdMgrRepositoryConfig
  • Use a single built-in, file-based repository in a new configuration under Federated repositories