Red Hat JBoss (& Wildfly) SSO Integration guide

This integration guide can be used to configure a JBoss or Wildfly application server to use SSO authentication provide by IBM Security Verify or IBM Security Verify Access. This integration uses the native JSON Web Token (JWT) identity realm which is part of the Elytron subsystem. This module is responsible for:

Establishing trust with the upstream authentication service.
Extracting identity information from the incoming request.
Building the Principal object available in the HttpServletRequest

Once configured, security policies can be applied by either by the application server using the legacy security constraint capability or by using the upstream IBM Application Gateway/WebSEAL instance to enforce customizable business logic such as multi-factor authentication or risk based authentication.

A demo integration using IBM Application Gateway and Wildfly containers is documented in the IBM Security Integrations repository.

Assumed knowledge

This guide assumes that you are familiar with:

Configuring JBoss server's via HTTP management interface, CLI or editing configuration file.
Creating and modifying PCKS12 trust stores
(Verify Access only) Configuring Verify Access reverse proxies and associated junctions
(Verify SaaS only) Creating and managing IBM Security Verify tenants

Prerequisites

Java application (ear/war)
An identity source; this can be either be on premises (Verify Access) or cloud base (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

> JBoss application server 7.1
- > Wildfly 20.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 JBoss Wildfly 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.

JBoss / Wildfly server configuration

The following sections will detail the required server and application configuration required to validate a JWT generated by an identity provider. The output of the server configuration is a new security realm which is capable of validating the JWT supplied by IBM Application Gateway or WebSEAL. Applications can use this new realm to provide authentication and authorization.

Available configuration parameters

The integration point for consuming JWTs have a number of configuration options. A complete list of available parameters can be found in the Elytron documentation

principal-claim: Claim which will be used to set the name of the Principal created
issuer: Domain which issued the JWT
audience: Domain which will be consuming the JWT
kid: Identifier to select the public key used to verify and/or decrypt the JWT
public-key: The public key (PEM format) material

Java application configuration

The WEB-INF/web.xml file of the Java application must contain the login-configuration element. This element must use the BEARER_TOKEN auth-method to invoke the JWT authentication mechanism. This file should also contain the names of any groups that are used by the java application (Java EE group-to-role mapping).

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         id="WebApp_ID"
         version="2.5">
    <display-name>IBMVerifyDemoApplication</display-name>
    <login-config>
        <auth-method>BEARER_TOKEN</auth-method>
        <realm-name>ibm-security-verify-realm</realm-name>
    </login-config>
    <security-role>
        <role-name>ExampleGroup</role-name>
    </security-role>
</web-app>

The WEB-INF/jboss-web.xml must also contain the security realm with the JWT token-realm configuration. If the token-realm is attached to the default http-authentication-factory then this file may be omitted.

Additionally, the WEB-INF/jboss-web.xml file contains the security domain configuration:

<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.3//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_3_0.dtd">
<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
    <security-domain>ibm-security-verify-realm</security-domain>
</jboss-web>

Elytron subsystem configuration

The Elytron subsystem must be configure to validate (and decrypt if required) JWT authentication tokens which conform to the authentication specification RFC 6750 implemented by JBoss/Wildfly. This can be done by either: using the Management Interface of a application server; or using the CLI tools provided by JBoss. Advanced users may also directly edit the XML configuration files as required.

GUI Configuration

Part 1:

Part 2:

CLI based configuration

The following jboss_cli.sh script can be used to configure the required JBoss subsystems to a XML configuration file (eg standalone.xml). The code block: creates a keystore which contains the JWT verification X509 certificate; adds a new security realm which parses the JWT generated by the identity provider; and connects the new realm to the undertow application responsible for accepting incoming HTTP connections. The results of these commands are detailed in subsequent sections.

To run this on your Application server the kid and public-key properties should be updated to match the respective key-label and public key properties used by either WebSEAL or IBM Application Gateway

batch
# Add a new token security realm to elytron for authentication using JWTs
/subsystem=elytron/token-realm=isva-jwt-realm:add(jwt={issuer=["www.ibm.com"],audience=["demo.integration.server"],key-map={"CN=iag.server"="-----BEGIN·PUBLIC·KEY-----&#xa;MIICIjA . . . CAwEAAQ==&#xa;---    --END·PUBLIC·KEY-----"}},principal-claim="sub")

# Add a new security domain, which uses the jwt security realm
/subsystem=elytron/security-domain=jwt-domain:add(realms=[{realm=isva-jwt-realm,role-decoder=groups-to-roles}],permission-mapper=default-permission-mapper,default-realm=isva-jwt-realm)

# Create http authentication factory that uses BEARER_TOKEN authentication
/subsystem=elytron/http-authentication-factory=jwt-http-authentication:add(security-domain=jwt-domain,http-server-mechanism-factory=global,mechanism-configurations=[{mechanism-name="BEARER_TOKEN",mechanism-realm-configurations=[{realm-name="isva-jwt-realm"}]}])

# Configure Undertow to use our http authentication factory for authentication
/subsystem=undertow/application-security-domain=ibm-security-verify-realm:add(http-authentication-factory=jwt-http-authentication)

run-batch

reload

File based configuration

The XML code block details the changes to the Elytron subsystem from running the above JBoss CLI commands. A new token-realm is added to the list of security realms. This realm contains the JWT claims configuration as well as the X509 certificate used to verify the token's signature. The full list of configuration parameters is available at the Wildfly documentation.

A http-authentication-factory element is also created and connected to the token-realm. This element also contains the security realm configuration which should be set in the WEB-INF/jboss-web.xml file of the Java web application. A new key-store is added to provide the required X509 certificate to verify the JWT. If a different keystore is used then the corresponding elements then the token-realm configuration must also be updated.

    <subsystem xmlns="urn:wildfly:elytron:14.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto">
        <security-domains>
            <security-domain name="jwt-domain" default-realm="isva-jwt-realm" permission-mapper="default-permission-mapper">
                <realm name="isva-jwt-realm" role-decoder="groups-to-roles"/>
            </security-domain>
        </security-domains>
        <security-realms>
            <token-realm name="isva-jwt-realm" principal-claim="sub">
                <jwt issuer="www.ibm.com" audience="jboss-jwt-audience">
                    <key kid="/C=AU/ST=QLD/L=Gold Coast/O=IBM/CN=iag.server"
                            public-key="-----BEGIN PUBLIC KEY-----&#xa;MIIC . . . AwEAAQ==&#xa;-----END PUBLIC KEY-----"/>
                </jwt>
            </token-realm>
        </security-realms>
        <http>
            <http-authentication-factory name="jwt-http-authentication" security-domain="jwt-domain" http-server-mechanism-factory="global">
                <mechanism-configuration>
                    <mechanism mechanism-name="BEARER_TOKEN">
                        <mechanism-realm realm-name="isva-jwt-realm"/>
                    </mechanism>
                </mechanism-configuration>
            </http-authentication-factory>
            <provider-http-server-mechanism-factory name="global"/>
        </http>
    </subsystem>
        <subsystem xmlns="urn:jboss:domain:undertow:12.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other" statistics-enabled="${wildfly.undertow.statistics-enabled:${wildfly.statistics-enabled:false}}">
            <application-security-domains>
                <application-security-domain name="ibm-security-verify-realm" http-authentication-factory="jwt-http-authentication"/>
            </application-security-domains>
        </subsystem>

Verify Integration

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

A demonstration integration using IBM Application Gateway and JBoss Wildfly 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 JBoss. This guide also documents a simple demo Java application showcasing the SSO capabilities offered by integrating JBoss 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.