HomeUse CasesConceptsConfig GuidesDeveloper GuidesAPI Reference

IBM Security Verify Integration

Suggest Edits

IBM Security Verify SSO for Liberty 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 IAG identity source.
  • Configure an IAG resource server.
  • Set SSL configuration
    • SSL key/certificate for https traffic.
    • Mutual SSL for protected resource servers.
    • Strongly recommended for both Liberty and IAG web traffic.

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 Liberty 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 Liberty 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 identity headers (or JWT) and additional security configuration is also defined here for the downstream Liberty 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 Liberty 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 Liberty.

The configured issuer (iss), audience (aud) and subject (sub) for the JWT must match the configuration set in the Liberty server's XML configuration. The PKI used to sign (and encrypt) the generated JWT must also be imported into the keystore used by the Liberty server. Liberty only supports using the Authorization header to supply JWT's and should be of the for Authorization: Bearer <j.w.t>.

resource_servers:
  - path: "/libertysso"
    connection_type: ssl
    transparent_path: false
    sni: "demo.integration.server"
    mutual_auth:
      certificate_auth:
        certificate:
          - "@iag.pem"
          - "@iag.key"
    servers:
      - host: "liberty.integration.server"
        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

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 dependant on the junction name to the Liberty server. If a different junction name is used then the stanza key should be updated to jwt:/<junction name>.

    advanced:
      configuration:
        - stanza: "jwt:/libertysso"
          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:
            - "/libertysso/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 Liberty integration guide

Demo Liberty 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 setup to authenticate users with IBM Security Verify; and one Liberty container with a demo java 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

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 liberty
    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 Liberty 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 keystore (.p12 file) used by Liberty. 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 Liberty certificae/keys/pcsk12
openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:4096 -keyout liberty.key -out liberty.pem \
        -subj "/C=AU/ST=QLD/L=Gold Coast/O=IBM/CN=demo.liberty.server"
openssl pkcs12 -export -out liberty.p12 -inkey liberty.key -in liberty.pem -passout pass:demokeystore

# Import IAG X509 into the Liberty keystore
keytool -importcert -keystore liberty.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 Liberty 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 Liberty 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-liberty-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: "/libertysso"
        connection_type: ssl
        transparent_path: false
        sni: "demo.liberty.server"
        mutual_auth:
          certificate_auth:
            certificate:
              - "@iag.pem"
              - "@iag.key"
        servers:
          - host: "liberty-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
              - attr: groups
                name: groups
                type: string
    advanced:
      configuration:
        - stanza: "jwt:/libertysso"
          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://%%VERIFY_TENANT%%/oidc/endpoint/default/.well-known/openid-configuration
        redirect_uri_host: ibm.security.integration.demo:30443
        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-liberty-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 IBM Liberty server

The final step of this demo is to deploy the Liberty server which is the target of this integration. A simple Liberty container is provided as part of the demo resources. This container is already configured to use the mpJWT feature to supply identity information to Java application.

The demo application deployed to the Liberty container is configured to reflect the identity information supplied in the java Principal object. A PCKS12 keystore is also mounted to the Liberty default keystore file which ensures the SSL certificate provided by IBM Application Gateway can be validated by Liberty (mutual TLS).

apiVersion: v1
kind: ConfigMap
metadata:
  name: liberty-config
data:
  server.xml: |
    %%SERVER_XML%%
binaryData:
  DemoApplication.war: %%DEMO_APPLICATION%%
  DemoKeyStoreFile.p12: %%LIBERTY_KEYSTORE%%
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: liberty-integration
  labels:
    app: liberty-integration
spec:
  selector:
    matchLabels:
      app: liberty-integration
  replicas: 1
  template:
    metadata:
      labels:
        app: liberty-integration
    spec:
      volumes:
        - name: liberty-config
          configMap:
            name: server-xml
      containers:
        - name: liberty-integration
          image: websphere-liberty:latest
          args: ["/opt/ibm/wlp/bin/server", "run", "defaultServer"]
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 9443
          volumeMounts:
            - mountPath: /opt/ibm/wlp/output/defaultServer/resources/security/DemoKeyStoreFile.p12
              subPath: DemoKeyStoreFile.p12
              name: liberty-config
            - mountPath: /opt/ibm/wlp/usr/servers/defaultServer/dropins/DemoApplication.war
              subPath: DemoApplication.war
              name: liberty-config
            - mountPath: /opt/ibm/wlp/usr/servers/defaultServer/server.xml
              subPath: server.xml
              name: liberty-config
---
apiVersion: v1
kind: Service
metadata:
  name: liberty-integration
  labels:
    app: liberty-integration
spec:
  ports:
    - port: 9443
      name: liberty-integration
  selector:
    app: liberty-integration
  type: NodePort

Updated 8 months ago