IBM Websphere Liberty/OpenLiberty SSO Integration guide

This integration guide can be used to configure an IBM Websphere Liberty or OpenLiberty server to use SSO authentication provided by IBM on-premises or cloud based IAM solutions using a standards based identity token. This integration is capable of integrating with a number of traditional (LDAP/Active Directory) and distributed (Federation/Cloud Directory) identity sources; as well as enforcing customizable access control policies.

Identity is provided to a downstream Liberty server using the mpJwt Liberty feature. This feature is capable of using a JSON Web Token (JWT) supplied in the incoming request to:

• Establishing trust with the upstream authentication service.
• Extracting identity information from the incoming request.
  • Verify identity information cryptographically signed by the WebSEAL instance
  • Parse identity claims
• Building the Principal object available in the HttpServletRequest

A demonstration of this integration is available at IBM Security Integrations using the latest Websphere-Liberty and IBM Application Gateway containers. The deployment of this scenario is documented in the verify integration guide

Assumed knowledge

This integration guide requires a user to have a working knowledge of IBM Websphere Liberty configuration. Generally, a user should be familiar with the following technologies:

• Deploying applications on a liberty server
• Creating and modifying PCKS12 trust stores
• (Verify Access only) Configuring Verify Access reverse proxies and associated junctions
  • Create WebSEAL junction
  • Modify WebSEAL configuration file for junction specific stanza
  • Import X509 Certificate into the WebSEAL certificate database
• (Verify SaaS only) Creating and managing IBM Security Verify tenants
  • Create a new Application/API client
  • Create/Manage a Cloud Registry or Federated identity source

Prerequisites

To use this integration guide there are a number of prerequisites:

• A java application (ear/war)
  • Liberty specific application configuration is detailed here
• An identity source; this can be either be on premises (Verify Access) or cloud based (Verify SaaS)
• Public Key Infrastructure to sign and verify identity information
  • When testing certificates can be self-signed but should be managed in production environments

Supported products

This integration guide is intended for use with

• > IBM Websphere Liberty 7.0
  • > OpenLiberty 18.0.0.0
• > IBM Security Access Manager 10.0.0.0

Architecture overview

This guide details two integration pathways, one for on premises solutions and one for cloud based solutions. A demo integration using IBM Application Gateway and Websphere Liberty is documented here and illustrated in the above figure. Both architectures use a very similar deployment pattern where a reverse proxy identifies users before making a decision to permit access to web server resources. In a cloud based deployment the reverse proxy is IBM Application Gateway, and identity is verified by IBM Security Verify SaaS; for on premises deployments IBM Security Verify Access uses legacy Virtual Machine architecture to deploy WebSEAL with a LDAP based user registry or integrate with a Federated Identity Source.

The sequence diagram describes the browser interaction for a user attempting to access a protected resource. When a user makes a request to a protected resource, the reverse proxy intercepts the request and redirects the user to authenticate. For cloud based deployments this is demonstrated by using IBM Security Verify SaaS as an OIDC Identity Provider; for on premises deployments IBM Security Verify Access can authenticate against a local user registry (LDAP or Active Directory) or redirect to Federated Identity Partner. Once the user has authenticated they are returned to the reverse proxy where an identity token is propagated to the protected web application where is can be validated using Public Key Cryptography.

Liberty Server Configuration

The mpJwt feature can be configured to supply identity information via a signed (and/or encrypted) JWT. The junction server can also be configured to validate connections using SSL. The following sections detail the required Liberty configuration to: enable the mpJwt feature; configure a Java application to consume JWT identity information; and security harden the Liberty server being protected.

Available Configuration Properties

The mpJwt documentation lists the available configuration properties. At a minimum you will need to set the following options:\

• issuer: domain name of the reverse proxy supplying identity.
• audiences: domain name of the Liberty application server consuming identity.
• keyName: identifies the public key in the SSL keystore which is used to verify signature tokens.

SSL Configuration

Where possible it is recommended to secure communication to the upstream revere proxy using SSL communication. To enable client authentication in Liberty SSL configuration can be added to the server configuration by adding a SSL entry and referencing the id of the entry in the httpEndpoint->sslOptions configuration. The demo configuration uses the default SSL configuration id and does not need to be referenced in the httpEnpoint entry.

The OpenLiberty documentation describes additional SSL configuration and HTTP endpoint configuration configuration. This is used to validate connections to the Liberty server and protects against unauthorized access from within the protected network. To configure mutual verification between the reverse proxy being used and Liberty a X509 certificate which is part of the trust chain from the reverse proxy must be imported into the Liberty keystore. The following commands can be used to import an X509 certificate:

keytool -importcert \
     -file <certificate to trust> \
     -alias <alias for the certificate> \
     -keystore <name of the truststore> \
     -storepass <password for the truststore> \
     -storetype <type of the keystore>

This keystore is then added to the Liberty server. For this guide (and the demo server) the default keystore is used (located at ${server.output.dir}/resources/security/key.p12) which is referenced by the default id defaultKeyStore. If you are using a custom keystore then additional configuration of the HTTP endpoint SSL configuration may be required.

Example:

<keyStore id="defaultKeyStore"
          location="DemoKeyStoreFile.p12"
          type="PKCS12"
          password="demokeystore"
          pollingRate="5s"
          updateTrigger="polled"/>

<ssl id="defaultSSLConfig"
      keyStoreRef="defaultKeyStore"
      clientAuthentication="true"/>

Java application configuration

The demo application uses a web.xml file in the WEB-INF directory of a web application to define authentication constraints. The below code snippet shows this definition alongside the corresponding server configuration to map JWT groups to Java roles.

web.xml in the Java application bundle:

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.5">
  <display-name>DemoApplication</display-name>
    <distributable />

    <servlet-mapping>
        <servlet-name>whoami</servlet-name>
        <url-pattern>/whoami.jsp</url-pattern>
    </servlet-mapping>

    <security-constraint>
        <display-name>
        AnyAuthenticated</display-name>
        <web-resource-collection>
            <web-resource-name>
                AnyAuthenticatedResources
            </web-resource-name>
            <url-pattern>/whoami.jsp</url-pattern>
            <http-method>GET</http-method>
            <http-method>POST</http-method>
        </web-resource-collection>
        <auth-constraint>
            <role-name>secusers</role-name>
        </auth-constraint>
    </security-constraint>
</web-app>

corresponding server.xml application configuration:

    <application type="war"
                 name="DemoApplication"
                 id="DemoApplication"
                 location="${server.config.dir}/apps/DemoApplication.war">
        <application-bnd>
            <security-role name="secusers">
                <group name="secusers"
                       access-id="group:www.ibm.com/SecUsers"/>
            </security-role>
        </application-bnd>
    </application>

📘

Groups to roles mapping

Note that the group name should be prefixed with the iss claim from the JWT. This is how Liberty maps externally defined groups to "Security Realms"

Management application based configuration

The liberty feature adminCenter-1.0 can be enabled to allow the configuration of a Websphere Liberty server using an interactive app from a web browser.

File based configuration

To configure the server.xml of your liberty application directly open the server.xml file in a text editor
and add the following XML elements to your server definition:

• featureManager:
  The appSecurity feature must be enabled to activate the required subsystems to process the authentication filter (which invokes JWT authentication). The mpJwt feature is used to validate and parse the supplied JWT and generate a Principal which is available to subsequent servlets. Finally the ssl feature must also be activated to enable SSL communication.

Example:

<featureManager>
    <feature>appSecurity-3.0</feature>
    <feature>ssl-1.0</feature>
    <feature>mpJwt-1.2</feature>
</featureManager>

• authFilter:
  The authentication filter is used to identify the incoming requests which should be authenticated using the configured mpJwt element. The sample configuration is triggered for any request which contains the Authorization header, however this could be modified to target a specific webapp or request URL.

Example: requests which contain an authorization header.

<authFilter id="myAuthFilter">
    <requestHeader id="authRequest" matchType="equals" name="Authorization"/>
</authFilter>

Example: all requests to a server

<authFilter id="myAuthFilter">
    <requestUrl id="authRequest" matchType="contains" name="/"/>
</authFilter>

• mpJWT:
  To configure the mpJwt feature, set a unique name, identity attributes (these may be omitted if using liberty defaults), the public key alias and the authentication filter used to identify requests which should contain identity information supplied by IBM Security Verify or IBM Security Verify Access.

Example:

<mpJwt
    id="myMpJwt"
    userNameAttribute="sub"
    groupNameAttribute="groups"
    issuer="www.ibm.com"
    audiences="demo.integration.server"
    authFilterRef="myAuthFilter"
    keyName="isvajwt">
</mpJwt>

Verify Integration

The Verify Integration guide can be used to configure IAG to supply identity information to Liberty. This guide also documents a simple demo Java application showcasing the SSO capabilities offered by integrating Liberty with IBM Security Verify.

A demonstration integration using IBM Application Gateway and WebSphere Liberty is documented here with source files available at the IBM Security Integrations repository

Verify Access Integration

The Verify Access Integration guide can be used to configure Verify Access to supply identity information to Liberty. This guide also documents a simple demo Java application showcasing the SSO capabilities offered by integrating Liberty with IBM Security Verify Access

Troubleshooting

If you encounter issues or have a specific deployment requirement not covered by this guide you can create an issue at the ibm-security-integration GitHub. From here IBM developers and members of the community can contribute and collaborate to find a solution.