HomeUse CasesConceptsConfig GuidesDeveloper GuidesAPI Reference
Content

IBM Security Verify Integration

Suggest Edits

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

Updated about 1 year ago