Verify Access SSO for Apache Tomcat

IBM Security Verify Access can be used to integrate on-premises user registries (eg. LDAP, Active Directory) with applications running on Apache Tomcat. The web reverse proxy component is used to provide and enforce access to downstream servers junctioned by WebSEAL. Identity information provided by Verify Access is then consumed by the JWT Valve which passes on the identity to java web applications. Customised or complex access policies can be implemented using the Advanced Access Control component of Verify Access.

Assumed knowledge

This integration guide assumes you are familiar with a number IBM Security Verify Access configuration options. At a minimum you should be able to:

• Create WebSEAL instances and junctions
• Modify the WebSEAL configuration file
• Manage the runtime server's SSL database

Prerequisites

This guide assumes that you have Verify Access (hardware, virtual machine or containers) deployed and the runtime server and user registry configured. Some additional configuration may be required if a Federated user registry (eg. Active Directory) or a Federated Identity (eg. OIDC or SAML) are used.

You should also have a Tomcat server deployed and configured to use a JWT Valve. Instructions for configuring Tomcat are detailed in this guide. Identity is supplied via a JSON Web Token (JWT) constructed from the available user attributes. This guide assumes you are familiar with the associated PKI needed to verify and (if required) decrypt JWTs.

Configure SSL verification

Where possible it is recommended to secure the WebSEAL junction the downstream Tomcat server using SSL. By default WebSEAL instances use the pdsrv SSL certificate database. To enable SSL communication a certificate which is part of the X509 trust chain from the tomcat SSL handshake must be imported into the SSL certificate database used by your WebSEAL instance.

To enable mutual verification a certificate which is part of the X509 trust chain from the WebSEAL handshake must be imported into the Tomcat SSL keystore

WebSEAL Reverse Proxy Configuration

A WebSEAL instance is used to supply and enforce authentication requirements. At a minimum you will need to create/modify a WebSEAL instance with a junction to the target tomcat server and add the JWT configuration stanza configured to match the claims configured for the JWT Valve.

Create the WebSEAL junction to Tomcat

Create a mutual junction to the Tomcat server. This guide uses a standard junction, however a transparent junction can be used if the downstream server must be able to redirect using relative paths. The junction should be configured to use SSL connections with no other additional configuration is required.

This can also be done using the pdadmin CLI tool:

[user@workstation ~]$ ssh [email protected]
Warning: Permanently added '192.168.42.101' (ED25519) to the list of known hosts.
([email protected]) Password:
Welcome to the IBM Security Verify Access appliance
Enter "help" for a list of available commands

my.isva.appliance> isam admin

pdadmin> server task <instance_name>-webseald-<host_name_or_address> create –t mutual -h target.integration.server -p 9080 -P 9443 /tomcat-sso-demo

Created junction at /tomcat-sso-demo

Configure WebSEAL to supply a JWT

To configure WebSEAL to supply a JWT, a[jwt:<junction name>] stanza is added to the WebSEAL configuration file. This stanza contains the attribute mapping to be used as well as any cryptographic configuration required. The demo integration uses the self signed certificate created in the pdsrv keystore (WebSEAL default keystore) to sign JWTs. In a production environment this should be replaced with appropriate PKI. The HTTP header used must be of the form Authorization: Bearer %TOKEN% as the tomcat feature does not allow for this to be changed.

A sample WebSEAL configuration file stub is provided which demonstrates the configuration required:

[jwt:/tomcatsso]
key-label = WebSEAL-Test-Only
claim = attr::AZN_CRED_PRINCIPAL_NAME::sub
claim = text::webseal.ibm.com::iss
claim = text::demo.integration.server::aud
claim = attr::AZN_*
hdr-name = Authorization
hdr-format = Bearer %TOKEN%
lifetime = 0
renewal-window = 15

Optional: Configure additional access control of web resources

Any additional Access Control Lists (ACLs) and Protected Object Policies (POPs) required for the junctioned resource should also be created here. ACLs and POPs are used to define additional business logic required to enforce additional security requirements to access web resources. Out of the box step-up authentication, provided by the Advanced Access Control module is a simple to use example of the additional authentication which can be implemented using IBM Security Verify Access.

Return to Tomcat integration guide