Integrating the IBM License Service Reporter with IBM Security Verify Access
This article will document the steps required to configure Verify Access as an OIDC Identity Provider for IBM License Service Reporter Operator. This integration allows administrators to use their existing Verify Access deployment to provide identity and authentication to IBM's license reporting tool. The WebSEAL user registry is used to provide user and groups. If your deployment uses a different source for users, then some of the configuration steps may change.
The critical points of this integration are to ensure that both the email and groups claims are included in the generated JWT. There are a number of ways that this can be done. The article will demonstrate how attributes can be down-streamed from WebSEAL's iv-creds; however these attributes could also be read from LDAP, or added to the generated token via custom JavaScript in the pre-token Mapping Rule.
Before you begin:
Before you attempt this integration, you should ensure your OpenShift cluster has the required Operators installed from the RedHat Community Marketplace or IBM provided catalog sources. The required operators are:
Deploying IBM Security Verify Access:
The first thing this article will cover is the required configuration for Verify Access, including the steps required to configure WebSEAL's user registry to provide the required claims to the Federation runtime service. If you are using an existing deployment with a different identity source, you can skip ahead to the OIDC Identity Provider configuration, just make sure you have a way to provide the groups and email claims in the generated identity token.
OpenShift deployment:
This article will use Verify Access deployed to OpenShift. I will not cover the steps required to do the initial container configuration. If you are unsure how to perform this initial configuration, my colleague Shane Weeden has a very good article on deploying Verify Access to IBM Cloud which should help you get started.
One additional step that is required is to create an OpenShift route for the WebSEAL Reverse Proxy. This will provide the container with a DNS name which can be resolved by both service running within OpenShift and clients connecting to exposed endpoint.
cat<<EOF | oc create -f -
apiVersion: route.openshift.io/v1
kind: Route
metadata:
labels:
type: ""
name: isamwebseal
namespace: default
spec:
subdomain: isamwebseal
tls:
termination: passthrough
to:
kind: Service
name: isamwebseal
EOF
You may need to update the configuration for the OpenShift route to the WebSEAL Reverse Proxy container. The value for spec.to.name will depend on the Service you have created for the WebSEAL runtime container. The value for the Route’s metadata.labels.type is dependent on the output from the cluster’s IngressController object:
oc get ingresses.config/cluster -o jsonpath={.spec.loadBalancer.platform.type}
Deploy the Verify Access containers:
For this integration you will need a configuration container, a reverse proxy container, and a runtime container. An example deployment (including the supporting PostgreSQL and OpenLDAP containers) can be found here
Generate PKI for WebSEAL:
This integration requires the x509 certificate used by WebSEAL to contain a valid Subject Alternative Name (SAN) extension for the domain we will be using. To do this, we will use OpenSSL to create a mock CA certificate and key pair, then use that key pair to sign a certificate for WebSEAL which has a valid SAN. To get started you should generate a key pair to use as a trust root.
openssl req -x509 -subj "/C=AU/O=IBM/OU=Security/CN=isva.ca" -newkey rsa:2048 -keyout isva-ca.key -out isva-ca.pem -passout pass:Passw0rd
Next we will create the WebSEAL PKI. This will first create a .ext file with the required SAN entries, you should update the values of these DNS entries (and IP addresses) to match your deployment/route created in the previous step.
cat > webseal.v3.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = isamwebseal
DNS.2 = isamwebseal.apps-crc.testing
IP.1 = 192.168.130.11
EOF
# Run the OpenSSL commands to generate key files and certificates
openssl req -new -out webseal.csr -passout pass:Passw0rd -newkey rsa:4096 -keyout webseal.key -subj "/C=AU/O=IBM/OU=Security/CN=webseal.ibm.com"
openssl x509 -req -in webseal.csr -CA isva-ca.pem -CAkey isva-ca.key -CAcreateserial -out webseal.pem -days 9999 -sha256 -extfile webseal.v3.ext -passin pass:Passw0rd
openssl pkcs12 -export -out webseal.p12 -inkey webseal.key -in webseal.pem -passout pass:Passw0rd -passin pass:Passw0rd
# Remove the temporary file we created with the key usage and SAN extension information
rm webseal.v3.ext
And you are done, we will need to import the isva-ca.pem X509 and webseal.p12 PCKS12 files into the WebSEAL SSL database in a subsequent step.
Installing the IBM Licensing Operators:
The next steps this article will cover is installing the IBM Licensing and IBM License Service Reporter Operators. First you should install the IBM Licensing Operator, by default this operator will create a new namespace (OpenShift project) called ibm-licensing.
Next you need to install the IBM License Service Reporter Operator. This should be installed into the same namespace (ibm-licensing) as the IBM License Operator.
Next we will create an instance of the IBM License Service Reporter custom resource. This will contain the OIDC client information we will use in Verify Access, so you will need to decide on a client id and client secret here. We will also have to create two secrets, one for the client secret, and one for the WebSEAL CA X509 certificate.
The name of each of these secrets is important, so you will need to copy (or rename) the CA certificate for Verify Access to ca.crt. The name of the --oidc-issuer-url property is also important, this should be the domain name of the OpenShift Route you just created, and must exactly natch the Issuer Identifier in the OIDC definition we will create in Verify Access.
oc create secret generic ilmt-oidc-client-secret --from-literal='data=ibmreportingserviceclientsecret' -n ibm-licensing
cp isva-ca.pem ca.crt
oc create secret generic ilmt-oidc-ca-secret --from-file=ca.crt -n ibm-licensing
cat <<EOF | oc create -f -
apiVersion: operator.ibm.com/v1alpha1
kind: IBMLicenseServiceReporter
metadata:
name: ilmt-service-reporter
namespace: ibm-licensing
labels:
app.kubernetes.io/created-by: ibm-license-service-reporter-operator
app.kubernetes.io/instance: ibmlicenseservicereporter-instance
app.kubernetes.io/managed-by: operator
app.kubernetes.io/name: ibmlicenseservicereporter
app.kubernetes.io/part-of: ibm-license-service-reporter-operator
spec:
authentication:
oauth:
enabled: true
parameters:
- '--provider=oidc'
- '--provider-display-name=IBM Security Verify Access'
- '--oidc-issuer-url=https://isamwebseal.apps-crc.testing/'
- '--client-id=ibmreportingserviceclientid'
- '--client-secret-name=ilmt-oidc-client-secret'
- '--provider-ca-secret-name=ilmt-oidc-ca-secret'
- '--email-domain=*'
httpsCertsSource: self-signed
license:
accept: true
logLevel: VERBOSE
version: 4.2.1
EOF
Finally you will need to edit the default instance for the IBM Licensing Operator and add in the url and Secret name for the Reporter Service. Because we deployed the License Service and License Service Reporter to the same namespace, we do not need to create this secret (the License Service Reporter did it for us!). You will need to determine the correct URL for the reporterURL, you should be able to use the OpenShift console to work this out.
Add the following code to the spec property of the IBM Licensing instance, like so:
sender:
reporterSecretToken: ibm-license-service-reporter-token
reporterURL: 'https://ibm-license-service-reporter-ibm-licensing.apps-crc.testing'
Configuring Verify Access:
WebSEAL configuration:
Create a reverse proxy instance, and configure it to use the runtime component as a user registry.
Now we need to import the X509 certificate and PKCS12 file we previously generated into the SSL database used by WebSEAL. By default this is the pdsrv database, but this value may be different in your environment. Navigate to the System / Secure Settings / SSL Certificates menu, then edit the pdsrv database to import the required files.
Next we will create some LUA HTTP transformation rules. We will use these rules to provide the /.well-known/ OIDC endpoints. The rule will redirect any requests for the openid-configuration and jwks.json endpoints to the Federated runtime server. Note the name of the OIDC definition used for this integration may be different for you deployment; and consequently the path may also change.
Use the following code block to create a new LUA HTTP transformation rule called ilmt-wellknown.lua:
--[[
A simple transformation that returns metadata for the OIDC well known URL.
Activated in Reverse Proxy config with:
================
[http-transformations]
wellknown = wellknown.lua
[http-transformations:wellknown]
request-match = request:GET /.well-known/*
================
--]]
function return_error()
HTTPResponse.setStatusCode(404)
HTTPResponse.setStatusMsg("NOT FOUND")
HTTPResponse.setHeader("Content-Type", "text/plain")
HTTPResponse.setBody("404 Not Found!")
Control.responseGenerated(true)
end
if HTTPRequest.getURL() == "/.well-known/openid-configuration" then
-- Replace ILMTIntegration with your OIDC Definition name
HTTPRequest.setURL("/mga/sps/oauth/oauth20/metadata/ILMTIntegration")
elseif HTTPRequest.getURL() == "/.well-known/jwks.json" then
-- Replace ILMTIntegration with your OIDC Definition name
HTTPRequest.setURL("/mga/sps/oauth/oauth20/jwks/ILMTIntegration")
else
return_error()
end
You can create the rule by navigating to the Web / Global Settings / HTTP Transformation menu and creating a new rule. Once the rule has been created you can edit the contents to the above rule.
Next we will configure the Reverse Proxy we just created to use the HTTP transformation rule. Navigate to the Web / Reverse Proxy menu, select your reverse proxy instance and then edit the configuration file. You can search for the [http-transformation] stanza where you will need to add a new entry for the rule we just created. Then you will also have to add a new stanza underneath this for the request matching pattern that this rule will use. Example for each of these edits can be found in the above HTTP transformation rule.
We will also add configuration to collect the email LDAP attribute after a user has authenticated and add them to the credential that is generated by WebSEAL. This is done by creating a TAM_CRED_ATTRS_SVC entry for the LDAP ObjectClass that the user's email address is stored in.
And finally we will update the SSL configuration to use the PKCS12 file we previously imported. This is done by updating the webseal-cert-keyfile-label entry to the Distinguished Name of the X509 certificate previously created (in this demo CN=webseal.ibm.com,OU=Security,O=IBM,C=AU) and imported into the WebSEAL SSL database.
Finally we will need to create some users and groups. By default the License Service Reporter expects valid users to be part of the license-administrator group. This option is configurable, but beyond the scope of this demonstration. Navigate to the Web / Policy Administration menu, authenticate as the sec_master user, then create the required users and/or groups. For this example I will be using the user testuser and the group license-administrator, created in the dc=ibm,dc=com LDAP suffix.
OIDC Configuration:
In this section we will configure an API protection definition and client, this will contain the details for the integration with the License Service Reporter. The details of this integration will depend on how user's are authenticated in your Verify Access deployment and how attributes are sources. For this demonstration, users authenticate using WebSEAL's user registry (LDAP), and attributes are added to the user's credential, which is available to the federated runtime server. We will create attribute sources to select the emailAddress and AZN_CRED_GROUPS attributes from the user's credential.
Navigate to the Federation / Manage / Attribute Sources menu. Create two new attribute sources, on for emailAddress and one for AZN_CRED_GROUPS
Next create the OIDC API Protection definition. We will use the OpenShift route we created previously as the Issuer Identifier, and use the default junction name of /mga (we will create this in a subsequent step). For this integration you will need to enable the client credentials and authorization code grant types. we will also need to add the Attribute Sources we just created as attribute mappings for the groups and email token claims.
Now we can create the API Protection Client for the integration. You will need to set (and remember) a client ID and client secret. You will also need to set the Redirect URI for the License Service Reporter. By default this is OpenShift Route for the License Service Reporter console endpoint with the /license-service-reporter/oauth2/callback path; eg: https://ibm-lsr-console-ibm-licesning.apps-crc.testing/license-service-reporter/oauth2/callback. You can check this value by inspecting the spec.containers[name == 'auth'].args property for the --redirect-url property of the Pod deployed by the IBM License Service Reporter Operator.
You should also ensure that the Require PKCE option is not enabled (this is enabled by default when creating clients). The client ID and client secret values should be the same as the configuration you created when deploying the License Service Reporter.
At this point you can deploy the pending changes and publish a configuration snapshot. We will need to start the Federated runtime server to run the WebSEAL configuration wizard for OIDC.
Once you have published a configuration snapshot, restart the deployment for the reverse proxy and the runtime server to ensure the correct snapshot has been applied. Once the runtime container has finished bootstrapping we can run the WebSEAL OIDC configuration wizard
oc rollout restart deployment/isamwebseal
oc rollout restart deployment/isamruntime
Navigate to the Web / Reverse Proxy menu, select you reverse proxy instance and run the OIDC Configuration wizard. The runtime connection properties should match the service name and port that your runtime pod is listening on. Make sure the junction name (/mga) matches the point of contact prefix you set when you created the OIDC API Protection Definition.
Deploy the changes, publish a new configuration file and restart the reverse proxy and runtime containers once more. At this point Verify Access should be configured to provide identity to the IBM License Service Reporter. The final step we will take is to force the License Service Reporter deployment to restart. This will restart the auth pod and allow it to bootstrap with the correct information from Verify Access. This can be done via the OpenShift console, or the command line
oc rollout restart deployment/ibm-license-service-reporter-ilmt-service-reporter -n ibm-licensing
Testing it out:
Use the OpenShift console to find the Route to the License Service Reporter console. when you open this link in your browser you should be shown a prompt to log in with Verify Access. After you have successfully authenticated (make sure your user is a member of the license-administrator group), you will be redirected back to the License Service Reporter console and you can see a summary of the IBM license usage for your cluster!