1. 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.
   

   
2. 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.
   
3. Toggle to enable Client authentication and Authorization. Click Next.
   
    
4. Click Save to create the client. You will come back to set Valid redirect URIs and Valid post logout redirect URIs later, so that Keycloak can redirect you to the App Connect Dashboard UI after a successful login, and to the landing page after logout respectively.  Note that logout is only available on App Connect Operator version 12.4.0 or later and operand version 13.0.1.0-r1 or later,
   
5. When using a Keycloak version from v24.0.0 onwards, you should make use of light-weight access tokens.  Without light-weight access tokens you may see problems logging in when a user is assigned a large number of roles. On the navigation pane, select Clients. Click the client ID you have created from the Client ID column. Click Advanced, then jump to the Advanced settings section. Toggle on the setting for Always use lightweight access token and then click Save.
   
6. 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.

   
7. 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.
   
8. 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.
   
   This displays a table of predefined mappings. From the table, click to select User Client Role.

   
   
   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 lightweight access token and 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.

• Create a namespace named ace-keycloak-k8s.  In this tutorial, this namespace will be used to install these secrets as well as App Connect resources.  To create the namespace with the kubectl command, you need to log into your Kubernetes cluster from a terminal, and then run the following command:

  kubectl create namespace ace-keycloak-k8s

• Secret 1: Keycloak client secret - Create a secret to store credentials of the Keycloak client
  1. This secret must contain two key-value pairs. The keys must be named CLIENT_ID and CLIENT_SECRET. Copy the following YAML template into a file named kcClientSecret.yaml.

     kind: Secret
     apiVersion: v1
     metadata:
       name: dash-ace-keycloak-k8s-example-iam-11111
       namespace: ace-keycloak-k8s
       labels:
         app: keycloak
     data:
       CLIENT_ID: ZGFzaC1hY2Uta2V5Y2xvYWstazhzLWV4YW1wbGUtaWFtLTExMTEx
       CLIENT_SECRET: modify-this-value
     type: Opaque

     The value of CLIENT_ID is a base64-encoded value of the client ID that you created in part 1.  The base64-encoded value can be obtained by running the following command in a terminal:

     echo -n "dash-ace-keycloak-k8s-example-iam-11111" | base64

     • Note: You should change metadata.name and the CLIENT_ID values accordingly, when you are creating a client secret for App Connect Designer Authoring.
  2. You must replace the value of CLIENT_SECRET with the following steps:
     • Select your Keycloak client from the Keycloak admin console, and then click Credentials.  Copy the client secret from the Client Secret field.  Note that the following example shows a Keycloak client for App Connect Dashboard, you should change the CLIENT_SECRET value accordingly, when you are creating a client secret for Designer Authoring.
       
     • Base64 encode the copied value. For example, run the following command in a terminal:

       echo -n "client-secret-value" | base64

  3. Use the base64-encoded value to set CLIENT_SECRET in the yaml file.
  4. Create the secret on your cluster by running the following command:

     kubectl apply -f kcClientSecret.yaml -n ace-keycloak-k8s

• Secret 2: CA certificate Secret - Create a secret to store the CA certificate from Keycloak
  This secret must contain a key-value pair.  The name of the key is not fixed, but is default to ca.crt.  You can specify your own key name, such as myca.crt.  In that case, you must specify it in the App Connect Dashboard or Designer Authoring CR fields spec.authentication.integrationKeycloak.tls.caCertificate and spec.authorization.integrationKeycloak.tls.caCertificate. Copy the following YAML template into a file called kcCASecret.yaml.

  kind: Secret
  apiVersion: v1
  metadata:
    name: example-tls-secret
    namespace: ace-keycloak-k8s
    labels:
      app: keycloak
  data:
    ca.crt: modify-this-value
  type: Opaque

  You must replace the value for ca.crt with the following steps:
  1. See your Certification Authority to obtain the CA certificate.
  2. Base64 encode the CA certificate. For example, in a terminal, run the following command:

     echo -n "-----BEGIN CERTIFICATE-----
     abcdefg
     -----END CERTIFICATE-----" | base64

  3. Use the base64-encoded value to set the value for ca.crt in the yaml file.
  4. Create the secret on your cluster by running the following command:

     kubectl apply -f kcCASecret.yaml -n ace-keycloak-k8s

1. On Kubernetes you need to create an ingress route for your Designer Authoring.  Follow the documentation to create one and note down the spec.tls.hosts in the ingress yaml.
   Note: With App Connect Operator 12.9.0 or later, an App Connect Designer Authoring at version 13.0.2.2-r1 or later supports ingress out of the box on IBM Cloud Kubernetes Service. So, to automatically create an ingress resource for your Designer Authoring, simply set spec.ingress.enabled to true in the Designer Authoring CR, as described in the Creating ingress resources for your App Connect Designer Authoring and switch servers out of the box on IBM Cloud Kubernetes Service blog.
2. Copy the following YAML template into a file named designer_iam.yaml.

   apiVersion: appconnect.ibm.com/v1beta1
   kind: DesignerAuthoring
   metadata:
     name: example-iam-designer
     labels:
       backup.appconnect.ibm.com/component: designerauthoring
     namespace: ace-keycloak-k8s
   spec:
     imagePullSecrets:
       - name: ibm-entitlement-key
     license:
       accept: true
       license: L-XRNH-47FJAW
       use: AppConnectEnterpriseProduction
     couchdb:
       storage:
         size: 10Gi
         type: persistent-claim
         class: ibmc-file-gold-gid
     replicas: 1
     designerMappingAssist:
       incrementalLearning:
         schedule: Every 15 days
           enabled: false
     authentication:
       integrationKeycloak:
         auth:
           clientSecretName: designer-ace-keycloak-k8s-example-iam-11111
         enabled: true
         endpoint: 'https://example-keycloak.test.com'
         realm: exampleRealm
         tls:
           secretName: example-tls-secret
           ingressHost: example-iam-designer.example-keycloak.test.com
     authorization:
       integrationKeycloak:
         auth:
           clientSecretName: designer-ace-keycloak-k8s-example-iam-11111
         enabled: true
         endpoint: 'https://example-keycloak.test.com'
         realm: exampleRealm
         tls:
           secretName: example-tls-secret
           ingressHost: example-iam-designer.example-keycloak.test.com
     designerFlowsOperationMode: local
     replicas: 1
     version: '12.0.12.3-r1'

3. Set spec.authentication.integrationKeycloak.auth.clientSecretName and spec.authorization.integrationKeycloak.auth.clientSecretName to designer-ace-keycloak-k8s-example-iam-11111. This is the client secret that was created in part 2.
4. Ensure spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled are set to true, which enables authentication and authorization for App Connect Designer Authoring.
5. Set spec.authentication.integrationKeycloak.endpoint and spec.authorization.integrationKeycloak.endpoint to the URL of Keycloak endpoint. You can find the value in the KC_HOSTNAME environment variable in your Keycloak pod.  Run the following command to get the value:

   kubectl get pod <keycloak-pod-name> -n <namespace-for-keycloak-pod> -o=jsonpath='{.spec.containers[0].env[?(@.name == "KC_HOSTNAME")].value}'

   • Note: If the endpoints are not provided, whilst authentication and authorization are enabled, the IBM® Cloud Pak foundational services must be installed to provide authentication and authorization for App Connect Dashboard and Designer Authoring.  This is supported on OCP only.
6. Set spec.authentication.integrationKeycloak.realm and spec.authorization.integrationKeycloak.realm to the Keycloak realm, where the Keycloak client designer-ace-keycloak-k8s-example-iam-11111 exists. In this tutorial, it is exampleRealm.
7. Set spec.authentication.integrationKeycloak.tls.secretName and spec.authorization.integrationKeycloak.tls.secretName to example-tls-secret.  This is the CA secret that was created in part 2. Because we used the default key name ca.crt for the CA secret, we do not need to specify spec.authorization.integrationKeycloak.tls.caCertificate and spec.authorization.integrationKeycloak.tls.caCertificate. Therefore the caCertificate fields are not included in the example CR designer_iam.yaml.
8. Set spec.authentication.integrationKeycloak.tls.ingressHost and spec.authorization.integrationKeycloak.tls.ingressHost to the spec.tls.hosts value obtained in step 1.
   Note: Skip step 8 if you are creating a Designer Authoring instance at version 13.0.2.2-r1 or later and have set spec.ingress.enabled to true in the Designer Authoring CR.
9. Follow the documentation on entitlement key to create a ibm-entitlement-key Secret. This enables you to download the required images for the App Connect Designer Authoring.
10. Follow the documentation on Designer Authoring storage to set spec.storage.class.
11. (Optional) Set spec.version to 12.0 to pick up the latest App Connect Designer Authoring operand version.
12. Create the Designer Authoring resource with the following command:

    kubectl apply -f designer_iam.yaml -n ace-keycloak-k8s

1. 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 click the client designer-ace-keycloak-k8s-example-iam-11111.
   
2. Set Valid redirect URIs to <FIREFLY_ROUTE_UI>/auth/icp/callback, where FIREFLY_ROUTE_UI specifies the URL of the App Connect Designer UI.  You can get the value of FIREFLY_ROUTE_UI with the following command:

   kubectl get configmap example-iam-designer-designer-env -o=jsonpath='{.data.FIREFLY_ROUTE_UI}' -n ace-keycloak-k8s

   The name of the configmap resource is in the format of <designer authoring metadata.name>-designer-env.
3. If you are on App Connect Operator version 12.4.0 or later and Designer Authoring operand version 13.0.1.0-r1 or later, set Valid post logout redirect URIs to <FIREFLY_ROUTE_UI>.
4. Now you need to create a user to log in to App Connect Designer Authoring.  To do so, you can follow step 6 to 10 in the Create a user and configure user roles section of the Keycloak tutorial for IBM® App Connect Operator version 11.0.0.
5. In a Web browser, navigate to <FIREFLY_ROUTE_UI>.  As a result, a request is sent to the ui container in the Designer Authoring pod. With information on the Keycloak client and Keycloak endpoint, the request is redirected to Keycloak to provide authentication and authorization for App Connect Designer Authoring. You can use the user information created in step 3 to log in.
   
   • If you are directed to an error page, refer to the troubleshooting section.
6. Keycloak validates the user information, and forwards the request to Valid redirect URIs that you configured in the Keycloak client.  As a result, congratulations, you are logged into the App Connect Designer Authoring.
   

   

   • If you are directed to an error page, refer to the troubleshooting section.

Conclusion

The IBM® App Connect Operator (version 12.1.0 or later) offers enhanced Keycloak support, which enables you to use an existing Keycloak instance to configure authentication and authorization for App Connect Dashboard and Designer Authoring.  This new feature is available on both OCP and Kubernetes.

Troubleshooting

• We are sorry: Invalid parameter: redirect_uri
  How to recreate this problem?  You entered the URL of the App Connect Dashboard UI or Designer UI on a Web browser.  It directed you to the following error page, before reaching the Keycloak UI.
  
  
  This could indicate one of the following:
  1. The client secret, which you created in part 2, does not contain the correct name or credential for the Keycloak client.  You need to verify that the secret contains the expected keys and correct values.  You then need to update the secret otherwise.
     • If you updated the client secret, you must recreate the related App Connect Dashboard or Designer Authoring to pick up the change.
  2. The Keycloak client does not contain a correct Valid redirect URIs.  You need to verify this parameter on your Keycloak client.

• Something went wrong: initial connection from App Connect Dashboard or Designer UI to Keycloak
  How to recreate this problem?  You entered the URL of the App Connect Dashboard UI or Designer UI on a Web browser.  It directed you to the following error page, before reaching the Keycloak UI.
  

  
  This could indicate one of the following:

  1. Check the logs from your App Connect Dashboard or Designer Authoring pod.  Run the following commands:

     kubectl logs <dashboard pod name> -c control-ui | grep -i "InternalOAuthError: Failed to obtain access token"

     kubectl logs <designer authoring ui pod name> -c <designer-authoring-name>-ui | grep -i "InternalOAuthError: Failed to obtain access token"

     If the InternalOAuthError: Failed to obtain access token error message is in the pod log, it indicates that the value of ca.crt, which you set as a key-value pair in the CA certificate secret in part 2 in scenario 1, is incorrect.  Check the value in the secret (which is named example-tls-secret in this tutorial).   If you have specified your own key name, you must specify it in spec.authorization.integrationKeycloak.tls.caCertificate and spec.authorization.integrationKeycloak.tls.caCertificate in the App Connect Dashboard or Designer Authoring CR.
     • You can run the following command to verify it matches the root CA certificate:

       openssl s_client -showcerts -verify 5 -connect example-keycloak.test.com:443 < /dev/null 

       Note: You must replace example-keycloak.test.com with your Keycloak endpoint. This command returns a certificate chain with a depth of five. Use the root CA from the chain, which is the last entry in the output.
     • The CA certificate is copied into /tmp/certs.crt for the App Connect Dashboard and Designer Authoring pods to access.  You can verify that the content matches the root CA certificate you obtained from the openssl command above.  The following shows how to exec into a Dashboard pod to check this file, from the Kubernetes UI.
       
       
       The following screen shows how to exec into a Designer Authoring UI pod to check this file, from the Kubernetes UI.
       
     • If you updated the client secret, you must recreate the related App Connect Dashboard or Designer Authoring to pick up the change.
  2. If you are using a Keycloak version from v24.0.0 onwards, check the logs from your App Connect Dashboard or Designer Authoring pod.  Run the following commands:

     kubectl logs <dashboard pod name> -c control-ui | grep -i "Cannot read properties of null (reading 'exp')"

     kubectl logs <designer authoring ui pod name> -c <designer-authoring-name>-ui | grep -i "Cannot read properties of null (reading 'exp')"

     If the Cannot read properties of null (reading 'exp') error message is in the pod log, it indicates that the size of the access token is too large for a cookie. Ensure you have followed step 5 in part 1 in scenario 1, and toggled on the setting for Always use lightweight access token. 

• Something went wrong: error validating Keycloak client roles
  How to recreate this problem?  You entered the URL of the App Connect Dashboard UI or Designer UI on a Web browser, which took you to the Keycloak UI to log in as follows.
  
  
  After you entered the username and password, and then clicked Sign In, you arrived at the following error page.
  
  • Check the logs from your App Connect Dashboard or Designer Authoring pod.  Run the following commands:

    kubectl logs <dashboard pod name> -c control-ui | grep -i "cannot find the highest role"

    kubectl logs <designer authoring ui pod name> -c <designer-authoring-name>-ui | grep -i "cannot find the highest role"

    If the cannot find the highest role error message is in the pod log, you need to ensure the User Client Role mapper, which you added in step 7 of part 1 in scenario 1, was added to your Keycloak client. Ensure the Token Claim Name is set to effective-roles, and Add to Token Introspection is enabled.
    Otherwise you can change the string after grep -i to failed to obtain access token or InternalOAuthError.  If one of these error message is found in the pod log, you need to ensure the App Connect Dashboard or Designer Authoring has been recreated, if you have updated the secret containing the CA certificate.