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). The cn RDN value must match the user name value as it is configured in the basicRegistry 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 the federatedRepositories-1.0 feature is used, the CertificateMapNotSupportedException 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. Use certificateMapperId with the CUSTOM certificate map mode.

The X509CertificateMapper 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.

  • Basic Extensions using Liberty Libraries (BELLs) feature

    The BELLs feature uses the Java ServiceLoader facility to load an OSGi service from a library. Your JAR file must contain both the X509CertificateMapper implementation class and the provider-configuration file. The following list shows the files that might go into a JAR file:

    myLibrary.jar
+ com/acme/CustomBasicMapper.class
+ com/acme/AnotherCustomMapper.class
+ META-INF/services/com.ibm.websphere.security.X509CertificateMapper

    The provider-configuration file lists all the X509CertificateMapper implementations to be provided as an OSGi service. For example, for myLibrary.jar, the META-INF/services/com.ibm.websphere.security.X509CertificateMapper provider-configuration file has a list of services, with each service on its own line. Each service must be preceded by a comment line that contains a key-value pair that specifies a value for the x509.certificate.mapper.id property. The value of this property will be referenced from the basicRegistry configuration element in the server.xml file.

    # x509.certificate.mapper.id=customBasicMapper 
com.acme.CustomBasicMapper 
# x509.certificate.mapper.id=anotherCustomMapper 
com.acme.AnotherCustomMapper

    To bind the X509CertificateMapper to the basic registry, your server.xml configuration must load the services that are specified in the JAR file and configure the basic registry to point to the wanted X509CertificateMapper service.

    <server>
   <featureManager>
      <feature>appSecurity-2.0</feature>
      <feature>bells-1.0</feature>
   </featureManager>

   <!-- 
      Create a library for the JAR file that contains 
      the X509CertificateMapper implementation. 
   -->
   <library id="mylibrary">
      <file name="${shared.resource.dir}/libs/MyLibrary.jar">
   </library>

   <!-- Load the library in a BELL. -->
   <bell libraryRef="mylibrary" />

   <!-- Configure the registry with the custom X509CertificateMapper. -->
   <basicRegistry ... 
      certificateMapMode="CUSTOM"
      certificateMapperId="customBasicMapper" 
      ... >
   </basicRegistry>
</server>
  • User feature

    If you already have a user feature or plan on creating a user feature, you alternatively can put the X509CertificateMapper implementation in the user feature bundle.

    Configure the X509CertificateMapper implementation as a Service Component and define the x509.certificate.mapper.id property to have a unique ID. The value of this property will be referenced from the basicRegistry configuration element in the server.xml file. See information about developing a Liberty feature.

    To bind the X509CertificateMapper to the basic registry, your server.xml configuration must configure the basic registry to point to the wanted X509CertificateMapper service.

    <server>
   <featureManager>
      <feature>appSecurity-2.0</feature>
      <feature>usr:myFeature-1.0</feature>
   </featureManager>

   <!-- Configure the registry with the custom X509CertificateMapper. -->
   <basicRegistry ...
      certificateMapMode="CUSTOM"
      certificateMapperId="customBasicMapper"
      ... >
   </basicRegistry>
</server>