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_path: false sni: "demo-tomcat-server" mutual_auth: certificate_auth: certificate: - "@iag.pem" - "@iag.key" servers: - host: "demo-tomcat-server" port: 8443 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.demo:30443 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 replicas: 1 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-gateway:21.09.0 imagePullPolicy: IfNotPresent volumeMounts: - name: integration-config mountPath: /var/iag/config readinessProbe: exec: command: - /sbin/health_check.sh initialDelaySeconds: 5 periodSeconds: 10 livenessProbe: exec: command: - /sbin/health_check.sh initialDelaySeconds: 120 periodSeconds: 20 --- apiVersion: v1 kind: Service metadata: name: iag labels: app: iag spec: ports: - port: 8443 name: iag protocol: TCP nodePort: 30443 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 replicas: 1 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: - containerPort: 8443 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: - port: 8443 name: demo-tomcat-server nodePort: 31443 selector: app: tomcat-integration type: NodePort

Did this page help you?