Introduction
With the release of the IBM® App Connect Operator version 12.1.0, you can now use your existing Keycloak instance to configure authentication and authorization for App Connect Dashboard and Designer Authoring.
Building on top of the capability to use Keycloak, which was first available in IBM® App Connect Operator version 11.0.0, this new feature extends the supported platforms from Red Hat® OpenShift® Container Platform (OCP) only to also include Kubernetes. It has in addition removed the dependencies on the IBM® Cloud Pak foundational services and IBM® Cloud Pak for Integration operators. It is worth noting that this new feature is only available with App Connect licenses.
This article contains a tutorial on how to use your Keycloak instance to manage authentication and authorization for App Connect Dashboard and Designer Authoring. There are two scenarios. Scenario 1 covers how to configure App Connect Dashboard with your Keycloak instance on Kubernetes, whilst scenario 2 covers configuring App Connect Designer Authoring on Kubernetes. While you can follow this tutorial for OCP with the kubectl command-line tool, the App Connect documentation and a related tutorial on how to use Keycloak with IBM® App Connect Operator version 11.0.0 provide further guidance on how to use your Keycloak instance from the Red Hat UI.
Prerequisites
- Install the IBM® App Connect Operator version 12.1.0 or later
- Use App Connect licenses only (such as AppConnectEnterpriseProduction)
- Use App Connect Dashboard and Designer Authoring versions 12.0.12.3-r1 or later
- Kubernetes version 1.25, 1.27, 1.28 or 1.29
- Install the kubectl command-line tool
- Install a Keycloak instance and obtain the following information:
- The URL of Keycloak endpoint
- The Certificate Authority (CA) certificate from Keycloak
- The URL and credentials to access the Keycloak Admin Concole
For this tutorial, we configured a keycloak instance with the Keycloak operator on Kubernetes. If you do not have an existing Keycloak instance and would like to create one to complete this tutorial, you can follow the documentation for the Keycloak operator. When you are following that documentation to set up a database for Keycloak, you must modify the default values for POSTGRES_USER and POSTGRES_PASSWORD in the example yaml.
Article index
Note: In this article, resource names are highlighted in dark red. Keywords that are displayed on a UI are highlighted in bold.
Part 1: Create a Keycloak client for App Connect Dashboard
Let's create and configure a Keycloak client, so that your Keycloak instance can authenticate incoming requests from the App Connect Dashboard.
- From your Keycloak admin console, use the navigation pane to select a realm from the drop-down list. In this tutorial, we have set up a realm called exampleRealm. Next, on the navigation pane, select Clients, and then click Create client to create a Keycloak client.
- Set Client ID and click Next. In this tutorial, the client ID for App Connect Dashboard is set to dash-ace-keycloak-k8s-example-iam-11111. It contains a number of parts to make it uniquely identifiable, such as the App Connect resource type (dash for App Connect Dasbhoard), the namespace where the App Connect resource will be created, the name of the App Connect resource and a random five digits at the end.
- Toggle to enable Client authentication and Authorization. Click Next.
- Click Save to create the client. You will come back to set Valid redirect URIs later, so that Keycloak can redirect you to the App Connect Dashboard UI after a successful login.
-
Next you need to configure the client with the available roles and required client scope for App Connect Dashboard. On the navigation pane, select Clients. Click the client ID you have created from the Client ID column.
- To create roles, click Roles, then click Create role. There are two roles available for App Connect Dashboard, which are dashboard-viewer and dashboard-admin. The former gives you a view-only access to the Dashboard, which means you can only view resources. The latter enables you to perform administrative tasks, such as creating an IntegrationRuntime and uploading a BAR file.
In this tutorial, we will create both roles for the Keycloak client. To create a viewer role, enter dashboard-viewer in Role name and click Save. Next, repeat this step to create a dashboard-admin role.
- Now you will add a required mapper to the Keycloak client. Click Client scopes, then click Add client scope. Next, click the client scope named dash-ace-keycloak-k8s-example-iam-11111-dedicated.
Click Add mapper and select By configuration.
From the Add mapper editing window for the User Client Role mapper type:
- Set Name to a name of your choice. In this tutorial, we set it to effective-client-role.
- From the Client ID drop-down list, select your Keycloak client.
- Set Token Claim Name to effective-roles, which is a required value for the App Connect Dashboard and Designer Authoring to validate user roles.
- Toggle to enable Multivalued, Add to ID token, Add to access token, Add to userinfo and Add to token introspection.
- Finally, click Save to complete this mapper.
- Note: The Red Hat Keycloak interface might not have the toggle option for Add to token introspection. In that case, it is enabled by default.
Part 2: Create Keycloak related secrets on your Kubernetes cluster
To enable Transport Layer Security (TLS) between Keycloak and App Connect resources (Dashboard and Designer Authoring), you need to provide a couple of credentials on your Kubernetes cluster. The credentials should be stored as a Kubernetes Secret resource, and in a namespace that is accessible by your App Connect resources.