About cookies on this site Our websites require some cookies to function properly (required). In addition, other cookies may be used with your consent to analyze site usage, improve the user experience and for advertising. For more information, please review your options. By visiting our website, you agree to our processing of information as described in IBM’sprivacy statement. To provide a smooth navigation, your cookie preferences will be shared across the IBM web domains listed here.
IBM Security Verify Integration
IBM Security Verify SSO for Tomcat using IBM Application Gateway
IBM Security Verify can be used to provide a cloud based identity to IBM Application Gateway (IAG) using the OIDC standard. IAG is a lightweight reverse proxy which provides authentication and authorization to web application servers. IAG can also be used to enforce additional path based authentication policies (such as 2FA) where required.
Assumed knowledge
This guide assumes that you are familiar with IBM Security Verify applications and managing a cloud based user registry. Users should also be familiar with IBM Application Gateway configuration. Specifically you should be able to:
- Create a new IBM Security Verify application from the IAG template.
- Configure an identity source.
- Configure a resource server.
- Set SSL configuration
- SSL key/certificate for https traffic.
- Mutual SSL for protected resource servers.
Users should also be familiar with IBM Application Gateway (IAG) configuration. Specifically you should be able to configure an identity source and a resource server. You must also provided the required PKI to support SSL connections between IAG and the junctioned server.
Prerequisites
To use this this guide you should have:
- A Tomcat server configured for SSO authentication (this guide)
- A IBM Security Verify subscription or valid trial account
Configure IBM Security Verify
The verify scenario guide can be used to configure an IBM Security Verify tenant to provide SSO capabilities to IBM Application Gateway. An IAG application should be created or updated to support the new IAG instance. This will likely involve modifying the redirect_uri
entries to include the DNS/hostname that the IAG instance is protecting.
The user registry should also be configured now (if not already done). IBM Security Verify supports cloud directory users as well as federated identity sources.
Deploying IBM Application Gateway
To configure IAG to pass-through identity information from IBM Security Verify to Tomcat the resource_servers
and identity
configuration keys are used. The required configuration for each key is detailed below.
Resource servers
The resource server key is used to configure downstream applications which will be protected by IAG. At a minimum a junction path (prefixed with a /
) and a resource server must be defined. The JWT identity header and additional token configuration is also defined here for the downstream Tomcat server.
The target integration server can be identified by a DNS name or IP address, for Kubernetes environments this should be the service created for the target Tomcat deployment. The X509 certificate (or a signer certificate) configured for mutual authentication (eg: iag.pem
) must be a trusted certificate in the keystore used by Tomcat.
The configured issuer (iss
), audience (aud
) and subject (sub
) for the JWT must match the configuration set in the Tomcat server's XML configuration. The PKI used to sign (and encrypt) the generated JWT must also be imported into the keystore used by the Tomcat server. Tomcat only supports using the Authorization header to supply JWT's and should be of the form Authorization: Bearer <j.w.t>
.
resource_servers
path"/tomcatsso"
connection_type ssl
transparent_pathfalse
sni"demo-tomcat-server"
mutual_auth
certificate_auth
certificate
"@iag.pem"
"@iag.key"
servers
host"demo-tomcat-server"
port8443
ssl
certificate
"@integration.target.pem"
identity_headers
jwt
hdr_name"Authorization"
certificate
"@iag.pem"
"@iag.key"
claims
text"www.ibm.com"
name iss
type string
attr AZN_CRED_PRINCIPAL_NAME
name sub
type string
text"demo.tomcat.server"
name aud
type string
attr groups
name groups
type string
Identity
The identity key can be used to configure IAG as an OIDC RP. You can use the IBM Security Verify application created here to supply identity information to IAG. The provided example also makes use of special data types that IAG exposes to obfuscate sensitive information that may be required to define your deployment. In this case the client id and secret for the IBM Security Verify application is stored in a Kubernetes secret instead of a config map or set in the deployment yaml.
The oidc
definition also maps the preferred_username
attribute instead of the sub
attribute returned in the claims from Verify. This is done to return a human recognisable attribute as the Principal name available to the downstream application.
identity
oidc
client_id secret ibm-verify-oidc-integration/client_id
client_secret secret ibm-verify-oidc-integration/client_secret
discovery_endpoint https //your.tenant.ibmcloudsecurity.com/oidc/endpoint/default/.well-known/openid-configuration
redirect_uri_host ibm.security.integration.demo30443
mapped_identity"{preferred_username}"
ssl
certificate
"@verify_tenant_ca.pem"
response_type code
response_mode query
Advanced configuration:
IAG requires some additional advanced configuration parameters in order to supply a JWT in the correct format. The header format needs to be modified to include the static string Bearer
. The name of the stanza for this property is dependent on the junction name to the Tomcat server. If a different junction name is used then the stanza key should be updated to jwt:/<junction name>
.
advanced
configuration
stanza"jwt:/tomcatsso"
entry"hdr-format"
operation set
value"Bearer %TOKEN%"
Second Factor Authentication (2FA) with IBM Security Verify
A number of additional authentication policies can be applied to protected resources to enforce additional authentication requirements when accessing protected resources. The IAG policies configuration key allows administrators to specify path which will be protected as well as the logic for permitting or denying access. The IBM Security Verify access policies docs detail the list of defined authentication policies which can be applied.
The following code stub demonstrates how a singe page can be protected with "2FA always" policy, which will always prompt the user to complete a 2FA challenge before permitting access.
policies:
authorization:
- name: "enforce_2fa"
paths:
- "/tomcatsso/DemoApplication/secTestStepUp.jsp"
rule: 'acr != "urn:ibm:security:policy:id:17"'
action: "obligate"
obligation:
oidc:
acr_values: "urn:ibm:security:policy:id:17"
Return to Tomcat integration guide
Demo Tomcat Application server: "hello world" integration example
This guide can be used to deploy a simple demonstration of the identity capabilities available from IBM Security Verify and IBM Application Gateway (IAG). This demo provides configuration for two containers: One IAG container set-up to authenticate users with IBM Security Verify; and one Tomcat container with a demo java JSP web application.
This demo is deployed on Kubernetes but could be modified for OpenShift or another container orchestration platform. All of the configuration files plus additional scripts to assist with deployment of this demo can be found at IBM Security Integrations. An archive of the demo web application is available on the releases page.
Assumed knowledge
To successfully deploy this demonstration there is some assumed knowledge. A user should be familiar with:
- Deploying containers, configuration maps and secrets to Kubernetes.
- Creating and managing IBM Security Verify tenants.
Prerequisites
To deploy this demo a user should first:
- Retrieve the integration artifacts required from the tomcat directory of the security Integrations repo.
- Configure your environment to connect to the Kubernetes (or equivalent) cluster being used to host this demo.
- You will need an API client for an IAG verify application; PKI to secure connection to both the application server and IBM Security Verify; and an application (eg the demo application) to deploy.
Configuring IBM Security Verify
Identity for this demo is provided by IBM Security Verify. A guide for configuring IBM Security Verify as an OP for IAG is available in the IAG Readme
Create/Request PKI
Asymmetric keys are required for SSL connections and to sign/verify JWT's. The following openssl commands can be used to generate RSA keys and self-signed X509 certificates for Tomcat and IBM Application Gateway. The X509 Certificate/Public Key used by IBM Application Gateway for connections to junctioned servers should also be imported to the PKCS12 keystore (.p12
file) used by Tomcat. For production environments the PKI used should be signed by a suitable certificate authority.
# Create IAG certificates/keys
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:4096 -keyout iag.key -out iag.pem \
-subj "/C=AU/ST=QLD/L=Gold Coast/O=IBM/CN=demo.iag.server"
# Create Tomcat certificae/keys/pcsk12
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:4096 -keyout tomcat.key -out tomcat.pem \
-subj "/C=AU/ST=QLD/L=Gold Coast/O=IBM/CN=demo.tomcat.server"
openssl pkcs12 -export -out tomcat.p12 -inkey tomcat.key -in tomcat.pem -passout pass:demokeystore
# Import IAG X509 into the Tomcat keystore
keytool -importcert -keystore tomcat.p12 -file iag.pem -alias isvajwt -storepass demokeystore -noprompt
Deploying IBM Application Gateway
Once the IBM Security Verify application has been created and PKI generated the Application can be deployed to your container orchestration platform (OpenShift/Kubernetes). There are two containers required for this demonstration: the IAG container which is configured as an OIDC RP for the previously configured IBM Security Verify OP; and the Tomcat application server which is the target of the integration. The IAG deployment requires three Kubernetes Objects: A secret map for sensitive data; a config map with the IAG configuration; and a deployment which defines the IAG containers to be deployed. The following sections detail how these objects are created.
IAG Secrets map
Kubernetes secrets are used to obfuscate sensitive data such as the client id and secret of the IBM Security Verify Application. Additional non-sensitive information such as the config.yaml
file and any X509 Certificates / Keys should be added using Config Maps.
apiVersion v1
kind Secret
metadata
name ibm-verify-oidc-integration
type Opaque
data
client_id"change this"
client_secret"change this"
IAG Config Map
The core of an IAG deployment is the yaml configuration file which defines protected resources and access policies. The following example sets a junction to a Tomcat application server as well as defining the JWT supplied to the server. IBM Security Verify identity configuration s also defined in this file. If a configuration option is not able to be set with the documented configuration options, the advanced/configuration
entry can be used to define reverse proxy daemon configuration entries.
apiVersion v1
kind ConfigMap
metadata
name ibm-verify-tomcat-integration-config
data
iag.pem
%%IAG_CERTIFICATE%%
iag.key
%%IAG_KEY%%
integration.target.pem
%%INTEGRATION_SERVER_CERTIFICATE%%
verify_tenant_ca.pem
%%VERIFY_TENANT_CERT%%
config.yaml
version: 21.09
server:
ssl:
front_end:
certificate:
- "@iag.pem"
- "@iag.key"
resource_servers:
- path: "/tomcatsso"
connection_type: ssl
transparent_path: false
sni: "demo.integration.server"
mutual_auth:
certificate_auth:
certificate:
- "@iag.pem"
- "@iag.key"
servers:
- host: "tomcat-integration"
port: 9443
ssl:
certificate:
- "@integration.target.pem"
identity_headers:
jwt:
hdr_name: "Authorization"
certificate:
- "@iag.pem"
- "@iag.key"
claims:
- text: "www.ibm.com"
name: iss
type: string
- attr: AZN_CRED_PRINCIPAL_NAME
name: sub
type: string
- text: "demo.websphere.server"
name: aud
type: string
advanced:
configuration:
- stanza: "jwt:/tomcatsso"
entry: "hdr-format"
operation: set
value: "Bearer %TOKEN%"
identity:
oidc:
client_id: secret:ibm-verify-oidc-integration/client_id
client_secret: secret:ibm-verify-oidc-integration/client_secret
discovery_endpoint: https://your.ibmcloudsecurity.com/oidc/endpoint/default/.well-known/openid-configuration
redirect_uri_host: ibm.security.integration.demo:30443
#mapped_identity: "{sub}"
ssl:
certificate:
- "@verify_tenant_ca.pem"
response_type: code
response_mode: query
IBM Application Gateway deployment
Next we need to define the IBM Application Gateway container and connect it to the Kubernetes service layer so it is reachable from network addresses outside to the Kubernetes cluster. The container version used should match the version set in the ConfigMap config.yaml
. Container health checks are also defined to enable Kubernetes to respond if the IBM Application gateway container stops responding.
apiVersion apps/v1
kind Deployment
metadata
name iag
labels
app iag
spec
selector
matchLabels
app iag
replicas1
template
metadata
labels
app iag
spec
#serviceAccountName: ibm-application-gateway
imagePullSecrets
name iag-login
volumes
name integration-config
configMap
name ibm-verify-tomcat-integration-config
containers
name iag
image ibmcom/ibm-application-gateway21.09.0
imagePullPolicy IfNotPresent
volumeMounts
name integration-config
mountPath /var/iag/config
readinessProbe
exec
command
/sbin/health_check.sh
initialDelaySeconds5
periodSeconds10
livenessProbe
exec
command
/sbin/health_check.sh
initialDelaySeconds120
periodSeconds20
---
apiVersion v1
kind Service
metadata
name iag
labels
app iag
spec
ports
port8443
name iag
protocol TCP
nodePort30443
selector
app iag
type NodePort
Deploying the demo Apache Tomcat server
The final step of this demo is to deploy the Tomcat server which is the target of this integration. A simple Tomcat container is provided as part of the demo resources. This container is already configured to use the JWT Valve to supply identity information to Java application.
The demo application deployed to the Tomcat container is configured to reflect the identity information supplied in the java Principal object. A PCKS12 keystore is also mounted to the Tomcat default keystore file which ensures the SSL certificate provided by IBM Application Gateway can be validated by Tomcat (mutual TLS).
apiVersion v1
kind ConfigMap
metadata
name tomcat-config
binaryData
DemoApplication.war %%DEMO_APPLICATION%%
jose4j.jar %%JOSE4J_JAR%%
slf4j-api.jar %%SLF4J_JAR%%
jakrta_servlet_api.jar %%JAKARTA_SERLVET_API_JAR%%
jakrta_jacc.jar %%JAKARTA_JACC_JAR%%
ibm_security_jwt_valve.jar %%IBM_SECURITY_JWT_VALVE_JAR%%
DemoKeystore.p12 %%DEMO_KEYSTORE%%
data
server.xml
%%SERVER_XML%%
logging.properties
%%LOGGING_PROPERTIES%%
---
apiVersion apps/v1
kind Deployment
metadata
name tomcat-integration
labels
app tomcat-integration
spec
selector
matchLabels
app tomcat-integration
replicas1
template
metadata
labels
app tomcat-integration
spec
volumes
name tomcat-config
configMap
name tomcat-config
name tomcat-lib
emptyDir
containers
name tomcat-integration
image tomcat latest
args"catalina.sh" "run"
imagePullPolicy IfNotPresent
ports
containerPort8443
env
name JAVA_OPTS
value"-Djavax.net.debug=ssl:handshake"
volumeMounts
mountPath /usr/local/tomcat/webapps/DemoApplication.war
subPath DemoApplication.war
name tomcat-config
mountPath /usr/local/tomcat/conf/server.xml
subPath server.xml
name tomcat-config
mountPath /usr/local/tomcat/conf/logging.properties
subPath logging.properties
name tomcat-config
mountPath /usr/local/tomcat/DemoKeystore.p12
subPath DemoKeystore.p12
name tomcat-config
mountPath /usr/local/tomcat/lib
name tomcat-lib
initContainers
name permissions-fix
image tomcat latest
command"bash" "-c" "cp /temp/*.jar /tomcat_lib/; cp /usr/local/tomcat/lib/*.jar /tomcat_lib/; ls -lah /tomcat_lib"
volumeMounts
mountPath /temp
name tomcat-config
mountPath /tomcat_lib
name tomcat-lib
---
apiVersion v1
kind Service
metadata
name demo-tomcat-server
labels
app tomcat-integration
spec
ports
port8443
name demo-tomcat-server
nodePort31443
selector
app tomcat-integration
type NodePort
Updated over 1 year ago
Did this page help you?