Apache Tomcat SSO Integration guide

This integration guide can be used to configure a Apache Tomcat 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 Tomcat server using the JWT Valve available from the integration guide releases. This valve decodes and validates a supplied JSON Web Token (JWT) from 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
  • The valve is capable of setting the username and groups (roles) attributes.

A demonstration of this integration is available at IBM Security Integrations using the Apache Tomcat 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 Apache Tomcat configuration. Generally,
a user should be familiar with the following technologies:

• Deploying applications on a tomcat 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 web application bundle (ear/war)
  • Tomcat 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

• > Apache Tomcat 8.0
• > IBM Security Verify Access 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 container integration using IBM Application Gateway and Apache Tomcat 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.

Tomcat Server Configuration

A Tomcat application server is configured to use the supplied Valve which verifies a supplied JWT and creates a Principal object with the username and groups claims. The resulting identity can then be consumed by: either web.xml security-constraint configuration; or using JACC to make identity information available to java code.

Available configuration properties

The JWT Valve has a number of configuration options which must be defined in order to verify and parse the supplied JWT.

SSL Configuration

To set up mutual verification between the reverse proxy being used and Tomcat a X509 certificate which is part of the trust chain from the reverse proxy must be imported into the Tomcat keystore. The following commands can be used to import an X509 certificate into a JKS or PKCS12 keystore:

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>

In tomcat the SSL configuration for HTTP traffic is defined in the Connector element. This connector performs SNI on the supplied X509 certificate so the CN or appropriate extension must meet this check.

    <Connector port="8443" 
               maxThreads="150" 
               scheme="https" 
               secure="true" 
               protocol="org.apache.coyote.http11.Http11NioProtocol"
               SSLEnabled="true"
               defaultSSLHostConfigName="demo-tomcat-server"
               allowTrace="true">
        <SSLHostConfig protocols="all"
                       certificateVerification="required"
                       hostName="demo-tomcat-server"
                       truststoreFile="DemoKeystore.p12"
                       truststorePassword="demokeystore"
                       truststoreType="PKCS12">
        <Certificate type="RSA"
                     certificateKeystoreFile="DemoKeystore.p12"
                     certificateKeyAlias="1"
                     certificateKeystorePassword="demokeystore"
                     certificateKeystoreType="PKCS12"/>
        </SSLHostConfig>
    </Connector>

Java application configuration

The login-confg and security-congstraints elements can be added to the web.xml file of the WEB-INF directory of a Java web application deployment. This configuration is sufficient to enforce the use of the configured JWT Valve for the specified web resources.

This configuration file can also be used to enforce role based access policies (using group-to-role mapping) for web resources. In order to access the /secTestSSO.jsp resource the user must be a member of the "developer" group. The group name is prefixed with the "issuer" JWT attribute/claim to avoid collisions between identity sources with the same group names. Any required Java roles should be defined in this file.

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>secTestSSO</web-resource-name>
            <url-pattern>/secTestSSO.jsp</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>www.ibm.com/developer</role-name>
        </auth-constraint>
    </security-constraint>

    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>defaultRealm</realm-name>
    </login-config>

    <security-role>
        <role-name>www.ibm.com/developer</role-name>
    </security-role>

File based configuration

The provided server configuration stub demonstrates how the JwtValve can be enabled and configured for a Tomcat application server. The configuration of this component will rely on the PKI created in previous steps as well as the issuer/audience configuration set in the reverse proxy supplying the JWT (IAG or WebSEAL):

<?xml version="1.0" encoding="UTF-8"?>
<Server port="8005" shutdown="SHUTDOWN">
  <Service name="Catalina">
    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true">
        <Valve className="ibm.security.verify.sso.valve.JwtValve" 
            signKeyAlias="/c=au/st=qld/l=gold coast/o=ibm/cn=demo-iag-server"
            keyStorePath="DemoKeystore.p12"
            keyStorePassword="demokeystore"
            issuer="www.ibm.com"
            audience="demo.tomcat.server"/>
      </Host>
    </Engine>
  </Service>
</Server>

Verify Integration

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

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