Self-Managed Keycloak for App Connect Dashboard and Designer Authoring

Part 1: Create a Keycloak Client for App Connect Dashboard

• 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, 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. 
     
     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.
  
  
  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, create an ingress resource for your App Connect Dashboard. Follow the documentation to create one and note down the spec.tls.hosts in the ingress YAML file.
   Note: With App Connect Operator 12.8.0 or later, an App Connect Dashboard at version 13.0.2.1-r1 or later supports ingress out of the box on IBM Cloud Kubernetes Service. So, to automatically create an ingress resource for your Dashboard, simply set spec.ingress.enabled to true in the Dashboard CR, as described in the Creating ingress resources for your App Connect Dashboard and integration runtimes out of the box on IBM Cloud Kubernetes Service blog.
2. Copy the following YAML template into a file named dashboard_iam.yaml.
   YAML

    

   apiVersion: appconnect.ibm.com/v1beta1
   kind: Dashboard
   metadata:
     name: example-iam-dash
     labels:
       backup.appconnect.ibm.com/component: dashboard
     namespace: ace-keycloak-k8s
   spec:
     api:
       enabled: true
     license:
       accept: true
       license: L-XRNH-47FJAW
       use: AppConnectEnterpriseProduction
     pod:
       containers:
         content-server:
           resources:
             limits:
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 50Mi
         control-ui:
           resources:
             limits:
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 125Mi
     imagePullSecrets:
       - name: ibm-entitlement-key
     switchServer:
       name: default
     authentication:
       integrationKeycloak:
         auth:
           clientSecretName: dash-ace-keycloak-k8s-example-iam-11111
         enabled: true
         endpoint: 'https://example-keycloak.test.com'
         realm: exampleRealm
         tls:
           secretName: exmaple-tls-secret
           ingressHost: example-iam.example-keycloak.test.com
     authorization:
       integrationKeycloak:
         auth:
           clientSecretName: dash-ace-keycloak-k8s-example-iam-11111
         enabled: true
         endpoint: 'https://example-keycloak.test.com'
         realm: exampleRealm
         tls:
           secretName: exmaple-tls-secret
           ingressHost: example-iam.example-keycloak.test.com
     storage:
       size: 5Gi
       type: persistent-claim
       class: ibmc-file-gold-gid
     displayMode: IntegrationRuntimes
     replicas: 1
     version: '12.0.12.3-r1'

   
   
3. Set spec.authentication.integrationKeycloak.auth.clientSecretName and spec.authorization.integrationKeycloak.auth.clientSecretName to dash-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 Dashboard.
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_HOST 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 dash-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 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 dashboard_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 Dashboard instance at version 13.0.2.1-r1 or later and have set spec.ingress.enabled to true in the Dashboard CR.
9. Follow the documentation on entitlement key to create a ibm-entitlement-key Secret. This enables you to download the required images for App Connect Dashboard.
10. Follow the documentation on Dashboard storage to set spec.storage.class.
11. (Optional) Set spec.version to 12.0 to pick up the latest App Connect Dashboard operand version.
12. Create the App Connect Dashboard resource with the following command:
    kubectl apply -f dashboard_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 dash-ace-keycloak-k8s-example-iam-11111.
2. Set Valid redirect URIs to <ACE_INGRESS_HOSTNAME>/oauth/callback. ACE_INGRESS_HOSTNAME is the URL of the App Connect Dashboard UI. You can obtain the value of ACE_INGRESS_HOSTNAME with the following command:
   kubectl get configmap example-iam-dash-dash -o=jsonpath='{.data.ACE_INGRESS_HOSTNAME}' -n ace-keycloak-k8s 
   The name of the configmap resource is in the format of <dashboard metadata.name>-dash.
3. If you are on App Connect Operator version 12.4.0 or later and Dashboard operand version 13.0.1.0-r1 or later, set Valid post logout redirect URIs to https://<ACE_INGRESS_HOSTNAME>.
4. Now you need to create a user to log in to the Dashboard. To do so, you can follow steps 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 <ACE_INGRESS_HOSTNAME>. As a result, a request is sent to the control-ui container in the Dashboard pod. With information on the Keycloak client and Keycloak endpoint, the request is redirected to Keycloak to provide authentication and authorization for App Connect Dashboard. You can use the user 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 the Valid redirect URIs that you configured in the Keycloak client. As a result, congratulations, you are now logged into the App Connect Dashboard.
   

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

• Step 2: Set the client ID to designer-ace-keycloak-k8s-example-iam-11111.
• Step 5 and 6: Ensure the client ID designer-ace-keycloak-k8s-example-iam-11111 is selected.
• Step 7: Instead of creating Dashboard specific roles, you need to create a role for App Connect Designer Authoring. There is one role available, which is designerauthoring-admin. The role enables you to perform administrative tasks, such as creating and importing a flow.
• Step 8: In addition to adding a mapper named User Client Role, which is also required by App Connect Designer Authoring, you need to add three new mappers for App Connect Designer Authoring as follows:

1. Add a mapper of the User Attribute type:
   • Click Add mapper and select By configuration. Click User Attribute from the table of predefined mappings.
   • Set Name to a name of your choice. In this tutorial, we set it to LDAP_ID.
   • Set User Attribute to LDAP_ID.
   • Set Token Claim Name to ldap_id, which is a required value for the App Connect Designer Authoring to validate user roles.
   • Toggle to enable Add to ID token, Add to access token, Add to lightweight access token and Add to userinfo.
   • Finally, click Save to complete this mapper.
     
     
2. Add a mapper of the User Session Note type:
   • Click Add mapper and select By configuration. Click User Session Note from the table of predefined mappings.
   • Set Name to a name of your choice. In this tutorial, we set it to identity_provider.
   • Set User Session Note to identity_provider.
   • Set Token Claim Name to identity_provider, which is a required value for the App Connect Designer Authoring to validate user roles.
   • Toggle to enable Add to ID token, Add to access token, Add to lightweight access token and Add to userinfo.
     
   • Finally, click Save to complete this mapper.
3. Add a mapper of the User Session Note type:
   • Click Add mapper and select By configuration. Click User Session Note from the table of predefined mappings.
   • Set Name to a name of your choice. In this tutorial, we set it to identity_provider_identity.
   • Set User Session Note to identity_provider_identity.
   • Set Token Claim Name to identity_provider_identity, which is a required value for the App Connect Designer Authoring to validate user roles.
   • Toggle to enable Add to ID token, Add to access token, Add to lightweight access token and Add to userinfo.
     
   • Finally, click Save to complete this mapper.

Part 2: Create Keycloak Related Secrets on Your Kubernetes Cluster