Basic certificate map mode
You can use the certificate map mode to map X.509 certificates into a basic user registry by PRINCIPAL_CN, CUSTOM, or NOT_SUPPORTED in Liberty.
Certificate map modes (certificateMapMode
)
You can choose among three certificate map modes. PRINCIPAL_CN is the default mode.
- PRINCIPAL_CN
- The PRINCIPAL_CN mapping mode requires that the Distinguished Name (DN) in
the certificate contain a common name (
cn
) Relative Distinguished Name (RDN). Thecn
RDN value must match the username
value as it is configured in thebasicRegistry
element of the server.xml file. See Configuring a basic user registry for Liberty. - CUSTOM
- To provide a custom certificate mapping implementation, you can use the
CUSTOM mode and supply an
X509CertificateMapper
implementation. - NOT_SUPPORTED
- The NOT_SUPPORTED mapping mode throws a
CertificateMapNotSupportedException
error if the registry receives an attempt to authenticate with a certificate. If the registry is not federated and is run stand-alone, the authentication attempt fails. When thefederatedRepositories-1.0
feature is used, theCertificateMapNotSupportedException
error is ignored if any other federated repositories can authenticate the certificate.
Certificate map mode configuration attributes
certificateMapperId
-
Specifies the identifier of the custom
com.ibm.websphere.security.X509CertificateMapper
implementation to use for the basic registry. UsecertificateMapperId
with the CUSTOM certificate map mode.TheX509CertificateMapper
implementation has the following requirements:- It must contain a constructor with no arguments.
- The
mapCertificate(X509Certificate[])
method must be thread-safe and must return a case-insensitive user name to check for in the basic registry.
Example of a custom X509CertificateMapper
implementation
The following example shows an X509CertificateMapper
implementation for a basic
registry.
public class CustomBasicMapper implements X509CertificateMapper {
@Override
public String mapCertificate(X509Certificate[] certificates)
throws CertificateMapNotSupportedException,
CertificateMapFailedException {
if (certificates == null || certificates.length == 0) {
throw new CertificateMapFailedException("No certificates found.");
}
LdapName dn;
try {
dn = new LdapName(certificates[0].getSubjectX500Principal().getName());
} catch (InvalidNameException e) {
throw new CertificateMapFailedException(
"The certificate subject X.500 principal is not in " +
"the form of a distinguished name.", e);
}
/*
* Return a user name from the value of the first RDN in the DN.
*/
List<Rdn> rdns = dn.getRdns();
return rdns.get(rdns.size() - 1).getValue();
}
}
You can make the X509CertificateMapper
implementation available to Liberty as an OSGi service in one of two ways,
with either a BELLs feature or a user feature.