WAS v8.5 > Secure applications > Authenticate users > Select a registry or repository > Manage the realm in a federated repository configurationEnable 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.
- In the dmgr console, click Security > Global security.
- 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.
- Under Related items, click Manage repositories and then click the InternalFileRepository link.
- 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 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 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.
- If you set the value of the certificateMapMode property to filterDescriptorMode, then 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 you set the value of the certificateMapMode property to notSupported or exactDNMode.
- Under Custom properties, click New.
- 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 your client certificate. It must begin with a dollar sign ($) and open bracket ({) and end with a close bracket (}).
- You must 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}'.
We can 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, you 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, you 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.
Description of differences between certificate filter syntax for LDAP and file repositories.
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}))
- Save the configuration changes and restart WAS 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.
Procedure
- Enter the following command to start wsadmin.
wsadmin –conntype none
- 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}”}
- Save the configuration changes.
$AdminConfig save
- Restart WAS 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.
Certificate login results in a federated repositories configuration that includes only a file repository.
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 that are displayed in various configuration scenarios.
Certificate login results in a federated repositories configuration that includes a file and an LDAP repository.
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
Certificate login results in a federated repositories configuration that includes a file and local operating system repository.
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
IdMgrRepositoryConfig command group for AdminTask
Use a single built-in, file-based repository in a new configuration under Federated repositories