Cloud Pak for Business Automation

 View Only

Configuring IBM Cloud Pak for Business Automation 21.0.3 to work with Keycloak IAM using an external OIDC identity provider

By PARASURAM BALAKRISHNAN posted Sun June 19, 2022 11:15 PM

  

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:

  1. 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.
  2. If the user is unauthenticated, the user is redirected to IAM
  3. If no authentication token is present, IAM redirects the request to Keycloak server for authentication.
  4. The user is allowed to chose from a list of authentication providers, such as w3id and redirected to the provider.
  5. The enterprise Id provider presents a login page to the user who enter their credentials. This is validated against the corporate LDAP directory.
  6. 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.
  7. The user is redirected back to IAM with the SAML response and is authenticated.
  8. 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.
  1. IAM is configured with an LDAP server. IAM exposes a SCIM interface to allow CP4BA components to query user details.
  2. IAM is enabled for SAML and is integrated with Keycloak as the SAML provider.
  3. Keycloak is integrated with w3id using OIDC.
  4. 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

  1. 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
  2. Please note that users that are asserted by Keycloak must be found in this LDAP server.
  3. 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​
  1. 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​
  2. 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

  1. While logged into Keycloak in the cp4ba realm, create an SSO client.
  2. Import the SP metadata xml file (created in the above section). Save the setting.
  3. 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
  4. Select Save to update the SAML client configuration.
  5. 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
  6. Extract the contents of the downloaded zip file and use the idp-metadata.xml file for the next step.
  7. 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

  1. Create a new OIDC Identity Provider in Keycloak.
  2. Copy the Redirect URI which needs to be provided to w3id (or to the chosen OpenID connect IdP)
  3. 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

  1. Add LDAP under User Federation
  2. Provide the LDAP details as shown below. The values would correspond to the values provided in IAM LDAP configuration.
  3. Click save and open this LDAP configuration in Keycloak.
  4. Go to the Mappers section.
  5. Edit first name attribute as shown below, by providing the LDAP attribute as givenName instead of cn. Save the update.
  6. Similarly ensure that the last name attribute is mapped to sn attribute in LDAP.
  7. 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.
  8. 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.

  1. 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.
  2. As the platform administrator, access the Zen main page at https://cpd-{namespace}.{my-clusters-url-suffix}/zen/#/homepage.
  3. From the left-hand side navigator, choose Administration > Access control:
  4. Add the user(s) and assign the required roles to the user.
  5. The onboarded user, can now login to CP4BA Business Automation Studio, with the URL provided in the icp4adeploy-cp4ba-access-info ConfigMap
  6. In the login screen, select Enterprise SAML for login.
  7. Select oidc in the Keycloack login screen. oidc is the name of the identity provider corresponding to w3id, and configured in a preceding step.
  8. Keycloak will re-direct your browser to the w3id (or your enterprise SSO provider’s login screen)
  9. 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.

 

 

 

2 comments
41 views

Permalink

Comments

Fri October 28, 2022 03:25 AM

Some additional info, as per my implementation of this recipe on FYRE OCP 4.10.25 with CP4BA 21.0.3 FP9 (baw authoring capabs only, due to limitations in FYRE quotas):

1) I started with keycloak  v19 traditional (i.e. laset version, non-container), and I had a problem at downloading the metadata from Keyckoak ("Metadata mellon"). Thus I solved this by installing keycloak traditional v18, and everything went fine. However I submitted a bug report to the Keycloak team in this regard.

2) I suggest considering the execution of an additional step, namely "Register IdP - SAML registration without any dependency". In my case that helped to succeed with the implementation.

3) I noticed that if Keycloak is configured with https disabled (e.g. http only), SAML will not work as IBM CP Foundation needs https URLs in SAML metadata to interact with SAML the proper way.

4) I successfully implemented a SAML integration with Keycloak and OAuth client with Google, so that I was able to SSO with a Google account. Since my focus was mostly on ECM capabs, I needed to add the Google identity to the local CP4BA LDAP (OpenLDAP based on FYRE), in order to properly implement FileNet ACLs. In this regard, in my case I had to avoid using "@" in the "uid" attribute of OpenLDAP, and since then it looks like it's working fine.

Hope my comments will help to provide additional insights for those who want to practice with SSO topic on CP4BA. BringupLab provides even more details on SSO implem's (a CP4BA + Okta integration case study) at this link  

regards,

L.

Fri October 21, 2022 08:39 AM

Very well written and helpful article, I also want to hereby underline the writer's availability to spend some additional time to clarify some doubts and questions. Very good!

L. Modeo