Package com.ibm.websphere.security

Interface X509CertificateMapper

public interface X509CertificateMapper
Interface for custom X.509 certificate mapping. Implementing classes are required to define a zero-argument constructor so that they can be instantiated during loading.

Support of this interface is currently limited to basic and LDAP registries.

To make a X509CertificateMapper implementation available to Liberty as an OSGi service there are two options.

  1. Basic Extensions using Liberty Libraries (BELL)

    2. The BELL 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/CustomLdapMapper.class
 -- com/acme/AnotherCustomCertificateMapper.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. It *must* also specify the ID for each instance by inserting a comment line prior to each implementing class that contains a key value pair where the key is 'x509.certificate.mapper.id' and the value is a unique ID that can be used to reference the instance from a user registry in the server.xml. 
     # x509.certificate.mapper.id=mapper1
 com.acme.CustomMapper

 # x509.certificate.mapper.id=mapper2
 com.acme.AnotherCustomMapper
    Once the JAR has been packaged, update the server.xml configuration to include the "bells-1.0" feature, the library that points to the JAR and the BELL configuration that points to the library. Finally, associate the user registry to a X509CertificateMapper implementation by changing the 'certificateMapMode' to 'CUSTOM' and setting the 'certificateMapperId' to the value of the 'x509.certificate.mapper.id' of the instance of the mapper to use.

    Below is an example of associating 'mapper1' to and LDAP registry using the BELL feature. 

     <server>
    <featureManager>
       <feature>ldapRegistry-3.0</feature>
       <feature>bells-1.0</feature>
    </featureManager>

    <!--
       Create a library for the JAR file that contains
       the CertificateMapper 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. -->
    <ldapRegistry ...
       certificateMapMode="CUSTOM"
       certificateMapperId="mapper1"
       ... />
 </server>

  2. Registering with a user feature

    3. If there is a pre-existing user feature or you prefer to create a user feature, you can create an new OSGi service in you user feature that implements the X509CertificateMapper. The service *must* define the property 'x509.certificate.mapper.id' with a unique ID that can be used to reference the instance from a user registry in the server.xml.

    When the user feature has been installed in Liberty, add the user feature to the feature list in the server.xml configuration file. Finally, associate the user registry to a X509CertificateMapper implementation by changing the 'certificateMapMode' to 'CUSTOM' and setting the 'certificateMapperId' to the value of the 'x509.certificate.mapper.id' of the instance of the mapper to use.

    Below is an example of associating 'mapper1' to an LDAP registry using a user feature. 

     <server>
    <featureManager>
       <feature>ldapRegistry-3.0</feature>
       <feature>user:myFeature-1.0</feature>
    </featureManager>

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

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    mapCertificate(X509Certificate[] certificates)
    Map the X.509 certificate.