Introduction
Within Cloud Pak for Business Automation v21.0.3, the User Management Service (or UMS) no longer delivers the SSO capabilities as described in a previous article which focused on Cloud Pak for Business Automation v20.0.3
The Identity and Access Management (IAM) component in IBM Cloud Pak foundational services manages the security and access to Cloud Pak for Business Automation. IAM provides authentication support via the OpenID Connect (OIDC) specification. It also supports Security Assertion Markup Language (SAML)-based federated authentication.
What is Keycloak
Keycloak is an open-source Identity and Access Management (IAM) solution which allows applications to delegate authentication and manage authorization functions. It can federate multiple user registries such as LDAP and other OpenID Connect or SAML identity providers.
A key construct in Keycloak is a realm that provides logical separation of configuration. It is often referred to as multi-tenancy. Each realm has a set of users, roles, groups and set of federated user repositories and external ID providers that it manages. A default realm named master is created automatically by Keycloak during installation.
In this article we cover a scenario where IBM Cloud Pak for Business Automation v21.0.3 (henceforth referred to as CP4BA) uses Single Sign On provided by w3id using SAML (Security Assertion Markup Language). SAML is an open standard for exchanging identity, authentication, and authorization information between an identity provider (Keycloak - which in turn federates IBM w3id via OIDC) and a service provider (CP4BA cluster). As of v21.0.3, CP4BA only works with SAML for external SSO configuration.
The SSO flow can be summarized as follows:
- A user attempts to access a UI in CP4BA through a web browser. Access to any UI service is through the Zen front door component.
- If the user is unauthenticated, the user is redirected to IAM
- If no authentication token is present, IAM redirects the request to Keycloak server for authentication.
- The user is allowed to chose from a list of authentication providers, such as w3id and redirected to the provider.
- The enterprise Id provider presents a login page to the user who enter their credentials. This is validated against the corporate LDAP directory.
- If the user logs in successfully, the Id provider server redirects the user back to Keycloak, along with the OIDC response. The user is asserted in Keycloak.
- The user is redirected back to IAM with the SAML response and is authenticated.
- IAM generates an authentication token and grants access to the CP4BA UI that the user requested.
To be noted that the interaction between IAM and Keycloak uses SAML and the interaction between Keycloak and w3id uses OpenID Connect (OIDC). The sequence of steps is represented with orange circles in the diagram below.
During setup time, as represented by blue circles in the above diagram, the following sequence of activities need to be performed.
- IAM is configured with an LDAP server. IAM exposes a SCIM interface to allow CP4BA components to query user details.
- IAM is enabled for SAML and is integrated with Keycloak as the SAML provider.
- Keycloak is integrated with w3id using OIDC.
- Keycloak is configured with the LDAP server, used in step A.
Setting up Keycloak
Installation of Keycloak is not in the scope of this discussion, though for exploration, the following article provides an easy reference for installing Keycloak in your OpenShift cluster. Once Keycloak is installed create a realm named cp4ba to work with CP4BA.
https://www.keycloak.org/getting-started/getting-started-openshift
Please note that the setup described above is for a non-production environment. In addition, Keycloak is configured with an ephemeral storage. If a permanent storage is required, modify the template and ensure that /opt/keycloak/data is associated with a persistent volume as shown below.
Setting up IAM for SAML in IBM Cloud Pak foundational services
- As an installation pre-requisite for CP4BA, it is assumed that an LDAP sever is already configured with IAM. If not, please refer to https://www.ibm.com/docs/en/cpfs?topic=apis-directory-management#connect
- Please note that users that are asserted by Keycloak must be found in this LDAP server.
- Execute the following snippet, after having connected to your CP4BA cluster using oc and as the cluster administrator. This enables SAML in IAM. Ensure you receive a response Configuration successful in the last step.
iamadmin='admin'
iamadminpwd=$(oc get secret -n ibm-common-services -o json ibm-iam-bindinfo-platform-auth-idp-credentials |jq .data.admin_password -r | base64 -d; echo "")
iamhost=https://$(oc get route -n ibm-common-services cp-console -o jsonpath="{.spec.host}")
iamaccesstoken=$(curl -sk -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=password&username=$iamadmin&password=$iamadminpwd&scope=openid" $iamhost/idprovider/v1/auth/identitytoken | jq -r .access_token)
curl -skH "Authorization: Bearer $iamaccesstoken" -H "Content-Type: application/json" -d '{"enable": true}' -X PUT $iamhost/idmgmt/v1/saml/management
- Download the SAML SP metadata file to be imported into Keycloak
curl -skH "Authorization: Bearer $iamaccesstoken" "$iamhost/idauth/ibm/saml20/defaultSP/samlmetadata" -o ./iamMetadata.xml
- Execute this step after having exported the SAML metadata file from Keycloak. The export of SAML metadata file from Keycloak is covered in the next section. Ensure the path to the metadata file downloaded from Keycloak is correctly provided.
curl -vk -X POST --header "Authorization: Bearer $iamaccesstoken" -F "data=@./idp-metadata.xml" "$iamhost/idmgmt/v1/saml/upload"
You would receive an HTTP 200 response if the upload is successful, with a message stating Metadata uploaded successfully.
Setting up SAML Id Provider in Keycloak
- While logged into Keycloak in the cp4ba realm, create an SSO client.
- Import the SP metadata xml file (created in the above section). Save the setting.
- In the following screen the contents of the SP metadata xml are displayed along with a few default values in Keycloak. For the purposes of this exploration, the following flags are turned off. Encrypt Assertions and Client Signature Required
- Select Save to update the SAML client configuration.
- Export the IdP metadata xml file to be imported into CP4BA. In the Installation tab, select the format as shown below and click the Download
- Extract the contents of the downloaded zip file and use the idp-metadata.xml file for the next step.
- Execute the step 5, in the previous section, i.e. Setting up IAM for SAML in IBM Cloud Pak.
Setting up ODIC with w3id
We use IBM’s w3id which is the corporate SSO provider. You are free to choose any other OIDC IdP per your requirements. The details for registering a client with OIDC IdP (e.g., w3id) is not covered in this article.
Setting w3id OIDC Identity Provider in Keycloak
- Create a new OIDC Identity Provider in Keycloak.
- Copy the Redirect URI which needs to be provided to w3id (or to the chosen OpenID connect IdP)
- Create a First Login Flow named Simple Login Flow. The following link provides the details https://ultimatesecurity.pro/post/first-login-flow/. This flow creates a user in Keycloak if it doesn’t already exist. Once Simple Login Flow is created, update the ODIC identify provider’s configuration with this value as shown below.
Ensure Simple Login Flow has the following two executions including one for Automatically Set Existing User
Lastly we will federate the LDAP server to Keycloak so that IAM users can be accessed in Keycloak.
Federate IAM LDAP with Keycloak
- Add LDAP under User Federation
- Provide the LDAP details as shown below. The values would correspond to the values provided in IAM LDAP configuration.
- Click save and open this LDAP configuration in Keycloak.
- Go to the Mappers section.
- Edit first name attribute as shown below, by providing the LDAP attribute as givenName instead of cn. Save the update.
- Similarly ensure that the last name attribute is mapped to sn attribute in LDAP.
- Synchronize all users by selecting the option in the LDAP configuration. Please note that this was tested against an LDAP with a few entries, without SSL. Additional configuration may be required in Keycloak to handle federation of large LDAP directories.
- If the synchronization was successful, in the Users section in Keycloak, a set of users pulled from LDAP would display as shown.
Testing the SAML SSO Flow in CP4BA
We can test the end-to-end login flow within CP4BA as described below. The user tries to access the Business Automation Studio URL.
- Before we can allow a user to be logged in through Keycloak SSO and be able to work with CP4BA, the user needs to be “onboarded” into Zen.
- As the platform administrator, access the Zen main page at https://cpd-{namespace}.{my-clusters-url-suffix}/zen/#/homepage.
- From the left-hand side navigator, choose Administration > Access control:
- Add the user(s) and assign the required roles to the user.
- The onboarded user, can now login to CP4BA Business Automation Studio, with the URL provided in the icp4adeploy-cp4ba-access-info ConfigMap
- In the login screen, select Enterprise SAML for login.
- Select oidc in the Keycloack login screen. oidc is the name of the identity provider corresponding to w3id, and configured in a preceding step.
- Keycloak will re-direct your browser to the w3id (or your enterprise SSO provider’s login screen)
- If successfully logged in, the user will be redirected back to CP4BA UI. Please note that if the user is not onboarded to Zen, after login the user will not be able to perform any actions, i.e. the user remains unauthorized.