Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift

To manage security and access for your App Connect Designer and App Connect Dashboard instances, enable identity and access management (IAM) for the instances and then configure user access. IAM is implemented by using Keycloak, which provides a single sign-on solution for web applications and RESTful web services.

Availability: Support for IAM by using Keycloak is available only for App Connect Designer and App Connect Dashboard instances at version 12.0.10.0-r2 or later, which you create by using IBM® App Connect Operator 11.0.0 or later.

Creating App Connect Designer or App Connect Dashboard instances with IAM enabled

You enable IAM for an App Connect Designer or App Connect Dashboard instance when you create the instance.

Before you begin

Ensure that you have cluster administrator authority with cluster-admin permissions.
Ensure that your IBM App Connect Operator is installed as part of an IBM Cloud Pak for Integration deployment that also includes the IBM Cloud Pak foundational services and certificate manager Operators. For more information, see Installing IBM App Connect with identity and access management on Red Hat OpenShift.
If you are using an online cluster with access to public registries, and do not already have an entitlement key, obtain an entitlement key, which will enable you to pull the software images for your product components from the IBM Entitled Registry. You supply this key as a Kubernetes pull secret. To obtain and apply your entitlement key, see Finding and applying your entitlement key (online installation) in the Cloud Pak for Integration documentation.
If you are licensed to use the IBM Cloud Pak Platform UI and intend to use it to create App Connect Designer or App Connect Dashboard instances, ensure that a Platform UI instance is deployed. For more information, see Deploying the Platform UI.
Ensure that the required storage is set up for the App Connect Designer or App Connect Dashboard instances that you want to create.
Storage requirements for IAM:
The Keycloak deployment that is used to configure IAM for your App Connect Designer or App Connect Dashboard instances requires block storage and a storage class that is set as the default class. Therefore, you must set up this required storage before you try to create any instances. For more information, see Storage options for Keycloak in the Cloud Pak for Integration documentation.
To set the storage class as the default class, you can add an annotation to the metadata block in the StorageClass custom resource (CR) as shown in the following example.
```
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: rook-ceph-block
  annotations:
    storageclass.kubernetes.io/is-default-class: 'true'
...
```

About this task

Apart from the Operators that you manually install as a prerequisite for IAM, a Keycloak Operator is also automatically installed, which you can use to configure user access, as described later. The Operators are installed in a number of namespaces depending on whether the installation was cluster-scoped or namespace-scoped, and you might find it useful to know these locations.

In a cluster-scoped Cloud Pak for Integration environment, the IBM Cloud Pak for Integration, IBM App Connect, IBM Cloud Pak foundational services, and Operand Deployment Lifecycle Manager Operators are all installed in the openshift-operators namespace. However, the certificate manager Operator is installed in the cert-manager-operator namespace, and the Keycloak Operator is installed in the ibm-common-services namespace.
In a namespace-scoped Cloud Pak for Integration environment, the IBM Cloud Pak for Integration, IBM App Connect, IBM Cloud Pak foundational services, Operand Deployment Lifecycle Manager, and Keycloak Operators are all installed in the same (specific) namespace. However, the cert-manager Operator is installed in the cert-manager-operator namespace.

Procedure

To create an IAM-enabled App Connect Designer or App Connect Dashboard instance, complete the relevant step:

To create an IAM-enabled App Connect Designer instance, follow the instructions in App Connect Designer reference: Creating an instance.
Notable settings for IAM:
- Specify the license that you are entitled to use.
  - If you purchased Cloud Pak for Integration, you are entitled to use either CloudPakForIntegration* or AppConnectEnterprise* style licenses for your App Connect Designer and App Connect Dashboard instances (and other App Connect resources). However, to use a CloudPakForIntegration* license, a Platform UI instance must be deployed.
  - If you purchased the IBM App Connect Operator for an independent deployment, installation of the Cloud Pak for Integration and other Operators is permitted, but you are restricted to AppConnectEnterprise* style licenses for your App Connect Designer and App Connect Dashboard instances (and other App Connect resources). You are also not licensed to deploy the Platform UI.
- Ensure that Keycloak is enabled for both authentication and authorization. Keycloak is enabled by default.
- Set the version of the instance (spec.version) to the 12.0 channel, or to a fully qualified value of 12.0.10.0-r2 or later.
To create an IAM-enabled App Connect Dashboard instance, follow the instructions in App Connect Dashboard reference: Creating an instance.
Notable settings for IAM:
- Specify the license that you are entitled to use.
  - If you purchased Cloud Pak for Integration, you are entitled to use either CloudPakForIntegration* or AppConnectEnterprise* style licenses for your App Connect Designer and App Connect Dashboard instances (and other App Connect resources). However, to use a CloudPakForIntegration* license, a Platform UI instance must be deployed.
  - If you purchased the IBM App Connect Operator for an independent deployment, installation of the Cloud Pak for Integration and other Operators is permitted, but you are restricted to AppConnectEnterprise* style licenses for your App Connect Designer and App Connect Dashboard instances (and other App Connect resources). You are also not licensed to deploy the Platform UI.
- Ensure that Keycloak is enabled for both authentication and authorization. Keycloak is enabled by default.
- Set the version of the instance (spec.version) to the 12.0 channel, or to a fully qualified value of 12.0.10.0-r2 or later.

Results

After you click Create or run oc apply to create the Designer or Dashboard instance, the following sequence of events occurs:

The IBM App Connect Operator automatically deploys a CP4iServicesBinding resource for the Designer or Dashboard instance.
The CP4iServicesBinding resource requests an IntegrationKeycloakClient resource for the instance from the IBM Cloud Pak for Integration Operator (to enable IAM).
The IBM Cloud Pak for Integration Operator passes the request to the IBM Cloud Pak foundational services Operator to provision a Keycloak instance if one is not yet available.
Note: The very first time that you create an App Connect Designer or App Connect Dashboard instance that has Keycloak enabled for IAM, the IBM Cloud Pak foundational services Operator automatically installs the Keycloak Operator if it is not yet installed in your cluster-scoped or namespace-scoped deployment. This Keycloak Operator is used to provision the Keycloak instance.

The status messages for the Designer or Dashboard instance reflect this process.

What to do next

When the status of a Designer or Dashboard instance is shown as Ready, you can view the Keycloak artifacts that are created.
Locate the URL for your Keycloak instance. You need this URL to access the Keycloak Administration Console so that you can set up user access to the Designer or Dashboard instance.

Viewing the Keycloak artifacts

If you want to obtain an overall view of the Keycloak deployment, you can examine the Keycloak artifacts that are automatically deployed by Operators in your cluster.

Procedure

From the Red Hat® OpenShift® web console, you can view the Keycloak artifacts as follows:

To locate and view details about the Keycloak Operator that is installed, click Operators > Installed Operators. In a cluster-scoped Cloud Pak for Integration environment, you can view the Keycloak Operator in the ibm-common-services namespace. In a namespace-scoped environment, you can view the Keycloak Operator in the same namespace as the IBM App Connect Operator. A Keycloak instance and KeycloakRealmImport instance, which were provisioned by the IBM Cloud Pak foundational services Operator, are available in this namespace.
- The Keycloak instance is named cs-keycloak and is created with an internal PostgreSQL database for storing resources.
  Tip: In the custom resource (CR) for this instance, the spec.hostname.hostname parameter provides the generated host name of the instance. You can construct the URL for the cs-keycloak instance by adding the https:// prefix to the spec.hostname.hostname value. Other ways to obtain this URL from a CP4iServicesBinding resource, or from your Designer or Dashboard instance, are described later.
  You can also obtain the host name by running oc get routes from the namespace where the Keycloak Operator is installed; for example:
  oc get routes -n ibm-common-services
  The Keycloak instance runs on pod cs-keycloak-0 in the namespace where the Keycloak Operator is installed. You can view this pod under Workloads > Pods or by running the oc get pods command.
- The KeycloakRealmImport instance is named cs-cloudpak-realm, and it represents a Keycloak realm called cloudpak, which is specified in spec.realm.realm in the CR. Realms are used to manage isolated sets of users, credentials, roles, and groups within a Keycloak instance. You will use the cloudpak realm (as an administrator) to manage users and their access to the Designer or Dashboard instance. The users that you create will belong to, and log in to this realm.
To locate and view details about the CP4iServicesBinding resource that is created for the Designer or Dashboard instance, see Locating the URL for your Keycloak instance. This resource also provides information about the set of generated endpoints including the URL of the Keycloak instance.
To locate and view details about the IntegrationKeycloakClient resource that is created for the Designer or Dashboard instance, complete the following steps. This resource represents the secured Designer or Dashboard instance that presents a request to Keycloak to authenticate a user in the cloudpak realm.
1. From the Red Hat OpenShift web console, go to Home > API Explorer and search for IntegrationKeycloakClient.
2. Click the IntegrationKeycloakClient kind (or resource) that is displayed.
3. Switch the namespace to All projects or to the namespace in which you created the Designer or Dashboard instance.
4. Click the Instances tab to view each individual IntegrationKeycloakClient resource that is created for a Designer or Dashboard instance. Each resource is named in the format designer-namespace-designerName-uniqueID (for a Designer instance) or dash-namespace-dashboardName-uniqueID (for a Dashboard instance); for example, designer-ace-des-fd-keycloak-cp4ilic-58d5 or dash-ace-db-fd-keycloak-acelic-ir-ec0f8.
5. Click the resource for the Designer or Dashboard instance, and switch to YAML view to examine the CR.
Note:
If a Platform UI instance is deployed, the IBM Cloud Pak for Integration Operator also creates a CP4iServicesBinding resource in the namespace where the Platform UI is deployed, and creates an IntegrationKeycloakClient resource in the cloudpak realm.

The Cp4iServicesBinding is named platformUI_name-ibm-integration-platform-navigator (for example, integration-quickstart-ibm-integration-platform-navigator). In the CR, the status.metadata.integrationKeycloak.clientName parameter displays the name of the IntegrationKeycloakClient resource (for example, integration-uniqueID), which is available in the cloudpak realm and owned by cs-keycloak.

Locating the URL for your Keycloak instance

To access your Keycloak instance, you need to first locate its URL. These instructions describe how to find this URL from your Designer or Dashboard instance, or from the Cp4iServicesBinding resource for the Designer or Dashboard instance.

Tip: You can also obtain the URL from the CR of the Keycloak instance named cs-keycloak as described in Viewing the Keycloak artifacts.

Before you begin

Ensure that you have cluster administrator authority with cluster-admin permissions.

Procedure

To locate the URL for your Keycloak instance, complete either of the following steps:

If you created the Designer or Dashboard instance by using IBM App Connect Operator 11.2.0 or later, locate the URL by viewing details about the instance.
- From the Red Hat OpenShift web console, complete the following steps:
  1. From the navigation, click Operators > Installed Operators.
  2. If required, select the namespace (project) in which you installed the Designer or Dashboard instance.
  3. From the Installed Operators page, click IBM App Connect.
  4. From the Operator details page for the App Connect Operator, click the Designer Authoring tab to view the existing Designer instances, or click the Dashboard tab to view the existing Dashboard instances.
  5. Click the name of the Designer or Dashboard instance to view additional details. On the Details tab, the URL of the Keycloak instance is displayed as the Keycloak UI value.
  6. Copy and then paste the Keycloak UI value into the address bar of a browser window or tab to access the URL.
    The Welcome page for Red Hat build of Keycloak opens with links to access the Keycloak Administration Console or documentation.
    
    Bookmark the URL of the Welcome page and leave the page open.
- From the Red Hat OpenShift CLI, run the following command:
  - View Designer details.
```
oc get designerauthorings -n namespace
```
    The output provides the URL of the Designer instance and the URL of the Keycloak instance as shown in the following example.
```
NAME             RESOLVEDVERSION   URL                                                              KEYCLOAKURL                                                       CUSTOMIMAGES   STATUS   AGE
des-fd-keyclk    12.0.12.2-r1      https://des-fd-keyclk-ui-ace-fiona.apps.acecc-1120-cd-abc.com    https://keycloak-ibm-common-services.apps.acecc-1120-cd-abc.com   false          Ready    3h11m
```
  - View Dashboard details.
```
oc get dashboards -n namespace
```
    The output provides the URL of the Dashboard instance and the URL of the Keycloak instance as shown in the following example.
```
NAME          RESOLVEDVERSION   REPLICAS   CUSTOMIMAGES   STATUS  URL                                                              KEYCLOAKURL                                                          AGE
db-testdash   12.0.12.2-r1      1          false          Ready   https://db-testdash-ui-ace-fiona.apps.acecc-1120-cd-abc.com      https://keycloak-ibm-common-services.apps.acecc-1120-cd-abc.com      30h
```
  Copy and then paste the KEYCLOAKURL value into the address bar of a browser window or tab to access the URL.
  
  The Welcome page for Red Hat build of Keycloak opens with links to access the Keycloak Administration Console or documentation.
  
  Bookmark the URL of the Welcome page and leave the page open.
If you created the Designer or Dashboard instance by using IBM App Connect Operator 11.1.0 or earlier, locate the URL from the Cp4iServicesBinding resource for the Designer or Dashboard instance.
- Use the Red Hat OpenShift web console.
  1. Log in to the Red Hat OpenShift web console for your cluster.
  2. Ensure that you are in the Administrator perspective .
  3. From the navigation, click Home > API Explorer and search for Cp4iServicesBinding in all groups, versions, and scopes.
  4. Click the Cp4iServicesBinding kind (or resource) that is displayed.
  5. Switch the namespace to All projects or to the namespace in which you created the Designer or Dashboard instance.
  6. Click the Instances tab to view the individual Cp4iServicesBinding resources for the Designer and Dashboard instances.These resources are named in the format designerName-designer (for a Designer instance) or dashboardName-dash (for a Dashboard instance).
  7. Click the resource for the Designer or Dashboard instance.
  8. Switch to YAML view and then locate the status.endpoints[name=keycloak].uri value in the CR.
  9. Copy and then paste the status.endpoints[name=keycloak].uri value into the address bar of a browser window or tab to access the URL.
    The Welcome page for Red Hat build of Keycloak opens with links to access the Keycloak Administration Console or documentation.
    
    Bookmark the URL of the Welcome page and leave the page open.
- Use the Red Hat OpenShift CLI.
  1. From the command line, log in to your OpenShift cluster by using the oc login command.
  2. Run the following command to output the status.endpoints[name=keycloak].uri value in the Cp4iServicesBinding CR, where:
    - bindingName is a name in the format designerName-designer or dashboardName-dash.
    - namespaceName is the namespace where the Designer or Dashboard instance is deployed.
    Linux®:
```
oc get Cp4iServicesBinding bindingName -n namespaceName -o jsonpath='{.status.endpoints[?(.name=="keycloak")].uri}'
```
    Windows:
```
oc get Cp4iServicesBinding bindingName -n namespaceName -o jsonpath='{.status.endpoints[?(.name==\"keycloak\")].uri}'
```
  3. Copy and then paste the status.endpoints[name=keycloak].uri value into the address bar of a browser window or tab to access the URL.
    The Welcome page for Red Hat build of Keycloak opens with links to access the Keycloak Administration Console or documentation.
    
    Bookmark the URL of the Welcome page and leave the page open.

What to do next

Locate the credentials that you can use to access the Keycloak Administration Console.

Locating the credentials for the Keycloak Administration Console

To log in to the Keycloak Admin Console, you need to first obtain the login credentials, which are stored as a secret in your cluster. The name and location of this secret depends on the installation mode of the IBM App Connect Operator and the type of license that you specified when you created the Designer or Dashboard instance.

Procedure

To obtain the admin login credentials for the Keycloak Admin Console, complete the following steps:

From the Red Hat OpenShift web console, click Workloads > Secrets in the navigation.
Select a namespace ( or project).
- For a cluster-scoped deployment, select ibm-common-services.
- For a namespace-scoped deployment, select the namespace ( or project) in which the Designer or Dashboard instance is deployed.
Locate the secret that stores the credentials for the Keycloak Admin Console.
- If you specified an AppConnectEnterprise* style license for the Designer or Dashboard instance, search for a secret called cs-keycloak-initial-admin and then click the name to view its details.
- If you specified a CloudPakForIntegration* style license and have a Platform UI instance installed, search for a secret called integration-admin-initial-temporary-credentials and then click the name to view its details.
Reveal the values for the username and password. Then, copy and save the values in a safe location.

These values are the admin credentials for Keycloak.

What to do next

Logging in to the Keycloak Administration Console

Use the URL of the Keycloak instance and the credentials for the Keycloak Admin Console to access the Admin Console.

Procedure

To log in to the Keycloak Admin Console, complete the following steps:

If you need to, open the Welcome page for Red Hat build of Keycloak.

You can use the bookmark that you saved earlier to access this page or follow the steps in Locating the URL for your Keycloak instance.
Click Administration Console and then use the credentials that you obtained from the previous task to log in.

If you used the credentials in the integration-admin-initial-temporary-credentials secret to log in, you are prompted to change the password the first time that you log in. Follow the prompts to change this password and make a note of the new password.

What to do next

Use the Keycloak Admin Console to manage user access to the Designer or Dashboard instance that you created.

Managing user access in the Keycloak Administration Console

After you log in to the Keycloak Admin Console, you can view information about your Designer and Dashboard instances, and set up users with assigned roles to access these instances. You must be in the cloudpak realm that was created earlier.

About this task

In the Keycloak Admin Console, your Designer and Dashboard instances (which require user authentication) are represented as clients. Each client is identified by its IntegrationKeycloakClient resource name.

App Connect provides predefined roles that determine what type of access permissions a user has to a Designer or Dashboard instance. You can view the roles for each Designer or Dashboard instance in the Keycloak Admin Console, and then choose which roles to assign to a user.

Complete the following procedure if you are using App Connect and IAM with an AppConnectEnterprise license that permits installation of the Operators that are required to enable Keycloak, but prohibits access to the Platform UI and other product capabilities. The instructions provide a simple sequence for quickly setting up users with App Connect roles, but it is possible to configure Keycloak further as described in the Server Administration Guide for the Red Hat build of Keycloak.

If you are using App Connect and IAM with a Cloud Pak for Integration license that entitles you to use the Platform UI and other product capabilities, see Identity and access management for information about adding users, details about the supplied roles and permissions, and details about Keycloak configuration options.

Procedure

To view clients, create users, and assign roles, complete the following steps:

From the Keycloak Admin Console, use the realm drop-down list in the navigation pane to switch to the cloudpak realm.

(Ensure that the cloudpak realm is selected because the default realm is master. For information about the master realm, see Controlling access to the Admin Console in the Server Administration Guide for the Red Hat build of Keycloak.)
Optional: View the Keycloak clients.
1. From the navigation, click Clients to open the Clients page.
  On the Clients list tab, you see the list of Designer and Dashboard instances for which Keycloak is enabled, as well as other applications and services. The instances are identified by their IntegrationKeycloakClient resource names in the format designer-namespace-designerName-uniqueID or dash-namespace-dashboardName-uniqueID.
2. Click the client ID of a Designer or Dashboard instance to view additional details such as the roles that are associated with the instance.
Create a user and set a password.
1. From the navigation, click Users to open the Users page.
2. Click Add user.
3. Optional. If you want to specify any actions that the user must complete when they first log in, select those actions from the Required user actions drop-down list. For example, you might want the user to update their password, profile, or locale.
  
  Note: When the user first signs in to the Designer or Dashboard instance with the credentials that you supply, prompts are displayed for this information. For example, the following types of prompts are displayed if a user needs to provide (and confirm) a new password, or update their profile.
4. In the remaining fields, specify the user's details.
5. Click Create.
  
  A set of tabs is displayed in which you can specify additional details for the new user.
6. Set a password for the user and indicate whether it is temporary.
  1. Click the Credentials tab.
  2. Click Set password.
  3. Specify a password for the user. The Temporary switch is set to on by default to indicate that the password is temporary and needs to be changed when the user signs in to the Designer or Dashboard instance for the first time. Set this switch to off to allow the user to retain the password that you specify.
  4. Click Save. An entry is displayed to represent the password.
Assign user permissions by using roles.
1. Click the Role mapping tab.
  If you clear the Hide inherited roles checkbox, you can see any roles that this user inherits by default.
2. Click Assign role.
3. In the Assign roles to user panel, click the Filter by drop-down list and then select Filter by clients.
  
  A list of all the Keycloak clients in the cloudpak realm is displayed.
4. Search this list to quickly locate your Designer or Dashboard instances. An instance is identified by the name of its IntegrationKeycloakClient resource in the format designer-namespace-designerName-uniqueID (for a Designer instance) or dash-namespace-dashboardName-uniqueID (for a Dashboard instance). So, you could start off by using designer-namespace or dash-namespace as the search string.
  
  In the search results, separate entries are shown for each role that is associated with an instance.
  
  The following example shows the search results for roles that are associated with Designer instances, which were created with the names des-fd-kcloak-acecclic and des-fd-keycloak-cp4ilic. Notice that only a single App Connect role (named designerauthoring-admin) is associated with a Designer instance.
  
  The following example shows the search results for roles that are associated with Dashboard instances, which were created with the names db-fd-keycloak-acecclic-ir and db-fd2-keycloak-cp4ilic-ir. Notice that two App Connect roles (named dashboard-admin and dashboard-viewer) are associated with each Dashboard instance.
5. Select the checkbox for each instance and role combination that you want to assign to the user. For information about these roles, see Roles and permissions for App Connect Designer on Red Hat OpenShift and Roles and permissions for the App Connect Dashboard on Red Hat OpenShift.
6. Click Assign. An entry is displayed to represent each instance/role mapping.
For more information about setting up users, roles, and permissions in Keycloak, see Managing users and Assigning permissions using roles and groups in the Server Administration Guide for the Red Hat build of Keycloak.

What to do next

Provide login details to the user that you created.

Supplying the user with login URLs and credentials

Provide the URL of the Designer or Dashboard instance to the user, and supply the configured authentication credentials that they can use to log in.

If you want to enable the user to manage the Keycloak user account that you created for them, also provide the URL of the Keycloak Account Console. For example, users can configure their profiles, update their password, configure two-factor authentication, or view device activity. For more information, see Account Console in the Server Administration Guide for the Red Hat build of Keycloak.

Procedure

To supply login details to the user, complete the following steps.

Provide the login details for the Designer or Dashboard instance that the user is authorized to access.
1. Locate and provide the URL of the instance from the Platform UI, or from the Red Hat OpenShift web console or CLI. This URL is generated when you create an instance. For more information, see App Connect Designer reference: Creating an instance and App Connect Dashboard reference: Creating an instance.
2. Provide the credentials that you set up for the user in the Keycloak Admin Console as described in Managing user access in the Keycloak Administration Console.
Optional: Locate and then provide the URL of the Keycloak Account Console.
1. From the Keycloak Admin Console, ensure that the cloudpak realm is selected.
2. From the navigation, click Clients.
3. From the Clients list tab, locate the account-console client ID and then copy the Home URL value.
  
  The URL is shown in the following format: https://server-root/realms/cloudpak/account.
  
  For example:
  
  https://keycloak-ibm-common-services.apps.acecc.abc.com/realms/cloudpak/account
  
  A user can use this URL and the login credentials for the Designer or Dashboard instance to sign in to the Keycloak Account Console.

Tutorial

The following tutorial provides scenarios for cluster-scoped and namespace-scoped deployments of IBM App Connect, and describes how to secure access to App Connect Designer and App Connect Dashboard instances within these deployments.

Follow this worked example to obtain an end-to-end view of how to install the Operators that are required for IAM, create your Designer and Dashboard instances with different license entitlements, enable and disable IAM, and configure user access for the instances: How to use Keycloak to provide authentication and authorization for App Connect Dashboard and Designer Authoring.