Document the RESTful APIs in your Java apps with OpenAPI 3.1 in the April 2018 beta of WebSphere Liberty. Also try out single sign-on with JWT and custom X.509 certificate mapping to users.

Thanks to your support for our regular beta programme, we are able to release new Liberty features every few months. Check out the release of WebSphere Liberty which is built on the release of Open Liberty. Look out for more betas over the coming months. If you just can’t wait, take a look at the daily builds of Open Liberty.

Follow Open Liberty happenings on @OpenLibertyIO.

What’s new in this beta?

Get it now! Ask a question about the beta

Document the RESTful APIs in your Java apps with OpenAPI 3.1

The openapi-3.1 feature is an extension of the MicroProfile OpenAPI (mpOpenAPI-1.0) feature. In addition to providing support for the MicroProfile OpenAPI 1.0 specification, the Open API 3.1 feature provides an aggregated view of APIs from multiple applications deployed in the server.

Simply add the openapi-3.1 feature to your server.xml and use one of the documentation methods listed in the specification for each of your applications:


You can view the generated aggregated OpenAPI document in the endpoint /api/docs, or view the rendered user interface at the endpoint /api/explorer.

Single sign-on (SSO) with JSON web tokens (JWT)

The new JWT SSO feature uses the industry standard JWT as a single sign-on tracking cookie. This is an alternative to the IBM proprietary LTPA cookie with several advantages:

  • The JWT cookie can carry enough information that the overhead of contacting a back-end registry (LDAP) for authentication can be avoided.
  • Other components, such as reverse proxies and app servers, can produce and consume these cookies which simplifies inter-operation and avoids the need to create custom authentication mechanisms.

To enable the JWT SSO feature, add the feature to the server.xml:


For more info, see the WebSphere Liberty Knowledge Center docs.

Custom X.509 certificate mapping to users

Liberty’s LDAP and basic user registries now support custom X.509 certificate mapping. This allows complete control over how certificates are mapped to users in the user registry.

The out-of-the-box X.509 certificate mappers for the LDAP user registry did not handle custom Universal Object Identifiers (OIDs) or parsing of certificate fields, and they included custom filtering of only a subset of the certificate’s fields. For example, there was no support for subject alternative name (SAN). The out-of-the-box X.509 certificate mapper for the basic user registry only supported using the subject’s cn relative distinguished name (RDN) for the user name.

The CertificateMapper API now enables mapping an X.509 certificate to a user in the user registry in any way that is required.

To use the CertificateMapper API, implement the interface and include it in a JAR. Also include in the JAR a Java ServiceLoader provider-configuration file (META-INF/ that contains the fully-qualified class names of any CertificateMapper implementations that you want to use in the Liberty server.

These implementations can then be loaded into Liberty’s classpath using the bells-1.0 feature with a shared library. Basic and LDAP user registries can then reference your implementation. Here is an example server.xml configuration for configuring two separate CertificateMapper implementations to a basic and LDAP user registry:


                    The library contains any CertificateMapper implementations.
            <library id="mylibrary">
                <file name="${shared.resource.dir}/libs/myLibrary.jar" />

                    Bundle the library using the BELLS feature.
            <bell libraryRef="mylibrary" />

                    Reference the CertificateMapper(s) from the user registries by configuring the
                    certificateMapMode attribute to "CUSTOM" and referencing the ID returned from
                    the CertificateMapper implementation's getId() method in the certificateMapperId
            <basicRegistry ... certificateMapMode="CUSTOM" certificateMapperId="basicMapper" />
            <ldapRegistry ... certificateMapMode="CUSTOM" certificateMapperId="ldapMapper" />

For more info, see the WebSphere Liberty Knowledge Center docs on Basic registry mapping and LDAP registry mapping.

What’s already in there?

The March Liberty beta included single logout function with single sign-on, and HTTP sesssion persistence backed by JCache.

MicroProfile 1.3 is now fully-supported in WebSphere Liberty

Looking for the latest?

If you’re visiting this post from the future and you’re looking for the latest releases of Liberty, here are the links you’re looking for:

Latest beta release
Latest stable release

Get it now! Ask a question on Stack Overflow

Join The Discussion

Your email address will not be published. Required fields are marked *