Implementing identity and access management in IBM App Connect by using a self-managed Keycloak solution on Red Hat OpenShift or Kubernetes

To host a self-managed Keycloak solution, install the Keycloak Operator and then configure a Keycloak deployment that you can use to implement IAM for your App Connect Designer and App Connect Dashboard instances.

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

• Locate the URL from the Red Hat OpenShift web console or CLI.
  • From the Red Hat OpenShift web console, complete the following steps:
    1. Log in to the web console and ensure that you are in the Administrator perspective .
    2. From the navigation, click Workloads > Pods to display the list of pods.
    3. Select the namespace (project) where you created the Keycloak instance.
    4. Locate the pod (keycloakInstanceName-0) where the Keycloak instance is running.
    5. Click the name of the pod to view the pod details and then click the YAML tab to view the custom resource (CR) settings.
    6. Look for the spec.containers.env.name parameter that is set to KC_HOSTNAME. The corresponding spec.containers.env.value parameter displays the hostname of the Keycloak instance.
       Note: To construct the URL for the Keycloak instance, you need to add the https:// prefix to the KC_HOSTNAME value.

       kind: Pod
       apiVersion: v1
       metadata:
         ...
         name: example-keycloak-0
       ...
       spec:
         ... 
         containers:
           - resources:
               ... 
             env:
               - name: KC_HOSTNAME
                 value: keycloak-mynamespace.apps.acecc-somedomain.abc.com
               - name: KC_FEATURES
                 value: token-exchange
       ...

    7. Copy and paste the constructed URL for the Keycloak instance into the address bar of a browser window or tab.

       https://KC_HOSTNAMEvalue

       Example:

       https://keycloak-mynamespace.apps.acecc-somedomain.abc.com

       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, complete the following steps:
    1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
    2. Run the following command to output the spec.containers.env[name=KC_HOSTNAME].value value in the Pod CR, where:
       • podName is the name of the Keycloak pod.
       • namespaceName is the namespace where the pod is running.
       Linux®:

       oc get pod podName -n namespaceName -o=jsonpath='{.spec.containers[0].env[?(@.name == "KC_HOSTNAME")].value}'

       Windows:

       oc get pod podName -n namespaceName -o=jsonpath='{.spec.containers[0].env[?(@.name==\"KC_HOSTNAME\")].value}'

       You see output that is similar to this:

       'keycloak-mynamespace.apps.acecc-somedomain.abc.com'

       Note: To construct the URL for the Keycloak instance, you need to add the https:// prefix to the KC_HOSTNAME value.
    3. Copy and paste the constructed URL for the Keycloak instance into the address bar of a browser window or tab.

       https://KC_HOSTNAMEvalue

       Example:

       https://keycloak-mynamespace.apps.acecc-somedomain.abc.com

       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.

• Locate the URL from the UI of your Kubernetes service or from the CLI.
  • If you are using an IBM Cloud Kubernetes Service cluster, you can complete the following steps. The steps for other Kubernetes systems might be similar.
    1. Log in to the Kubernetes UI.
    2. Select the namespace where you created the Keycloak instance.
    3. From the navigation, click Workloads > Pods.
    4. Locate the pod (keycloakInstanceName-0) where the Keycloak instance is running.
    5. Open the Actions menu for the pod and then click Edit.
       
    6. Search for KC_HOSTNAME in the CR settings that are displayed.

       In this CR, KC_HOSTNAME is set as the name for one of the spec.containers.env.name parameters and the corresponding spec.containers.env.value parameter displays the hostname of the Keycloak instance.

       Note: To construct the URL for the Keycloak instance, you need to add the https:// prefix to the KC_HOSTNAME value.
       
    7. Copy and paste the constructed URL for the Keycloak instance into the address bar of a browser window or tab.

       https://KC_HOSTNAMEvalue

       Example:

       https://example-keycloak-ab1234cde56fg789h0b7cd114438a79t4-0000.us-south.containers.appdomain.cloud

       The login page for the Keycloak Administration Console opens.

       

       Bookmark the URL of the login page and leave the page open.

  • From the Kubernetes CLI, complete the following steps:
    1. From the command line, log in to your Kubernetes cluster.
    2. Run the following command to output the spec.containers.env[name=KC_HOSTNAME].value value in the Pod CR, where:
       • podName is the name of the Keycloak pod.
       • namespaceName is the namespace where the pod is running.

       kubectl get pod podName -n namespaceName -o=jsonpath='{.spec.containers[0].env[?(@.name == "KC_HOSTNAME")].value}'

       You see output that is similar to this:

       'example-keycloak-ab1234cde56fg789h0b7cd114438a79t4-0000.us-south.containers.appdomain.cloud'

       Note: To construct the URL for the Keycloak instance, you need to add the https:// prefix to the KC_HOSTNAME value.
    3. Copy and paste the constructed URL for the Keycloak instance into the address bar of a browser window or tab.

       https://KC_HOSTNAMEvalue

       Example:

       https://example-keycloak-ab1234cde56fg789h0b7cd114438a79t4-0000.us-south.containers.appdomain.cloud

       The login page for the Keycloak Administration Console opens.

       Bookmark the URL of the login page and leave the page open.

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

• Locate the credentials from the Red Hat OpenShift web console or CLI.
  • From the Red Hat OpenShift web console, complete the following steps:
    1. Ensure that you are in the Administrator perspective .
    2. From the navigation, click Workloads > Secrets to display the list of secrets.
    3. Select the namespace (project) where you created the Keycloak instance.
    4. Search for the secret that is named keycloakInstanceName-initial-admin and then click the name to view its details.
       
    5. Go to the Data section on the Details tab, and then reveal the values for the username and password.
    6. Copy and save the values in a safe location.
  • From the Red Hat OpenShift CLI, run the following commands to decode and output the username and password, where:
    • keycloakInstanceName is the Keycloak instance name.
    • namespaceName is the namespace (project) where you created the Keycloak instance.

    oc get secret keycloakInstanceName-initial-admin -n namespaceName -o jsonpath='{.data.username}' | base64 --decode

    oc get secret keycloakInstanceName-initial-admin -n namespaceName -o jsonpath='{.data.password}' | base64 --decode

    Tip: On Windows, you can output the Base64-encoded username or password to a file, edit the file to remove the surrounding single quotation marks (' '), and save the file. You can then run the certutil command to decode the username or password to another output file. For example:

    oc get secret example-keycloak-initial-admin -n ace-test -o jsonpath='{.data.username}' > C:\tmp\usernameBase64.txt
    certutil -decode C:\tmp\userBase65.txt C:\tmp\usernameDecode.txt

• Locate the credentials from the UI of your Kubernetes service or from the CLI.
  • If you are using an IBM Cloud Kubernetes Service cluster, you can complete the following steps. The steps for other Kubernetes systems might be similar.
    1. From the Kubernetes UI, select the namespace where you created the Keycloak instance.
    2. From the navigation, click Config And Storage > Secrets.
    3. Locate the secret that is named in the format keycloakInstanceName-initial-admin.
       
    4. Click the name to view details about the secret.
    5. Reveal the credentials for the Keycloak Admin Console, which are shown in the Data section.
       
  • From the Kubernetes CLI, run the following commands to decode and output the username and password, where:
    • keycloakInstanceName is the Keycloak instance name.
    • namespaceName is the namespace where you created the Keycloak instance.

    kubectl get secret keycloakInstanceName-initial-admin -n namespaceName -o jsonpath='{.data.username}' | base64 --decode

    kubectl get secret keycloakInstanceName-initial-admin -n namespaceName -o jsonpath='{.data.password}' | base64 --decode

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

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

• Log in to the console on Red Hat OpenShift:
  1. 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.

  2. Click Administration Console and then use the credentials that you obtained from the previous task to log in.
• Log in to the console on Kubernetes:
  1. If you need to, open the login page for the Keycloak Administration Console.

     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.

  2. Use the credentials that you obtained from the previous task to log in.

To create a Keycloak client for a Designer or Dashboard instance, complete the following steps:

1. From the Keycloak Admin Console, use the realm drop-down list in the navigation pane to switch to the realm that you created in Setting up a self-managed deployment of Keycloak.

   Example of selecting a realm from the Keycloak Admin Console on Red Hat OpenShift	Example of selecting a realm from the Keycloak Admin Console on Kubernetes

   (Ensure that the correct realm is selected rather than the default master realm. 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.)

   Tip: If you inadvertently create a client in the master realm, you can export the client definition from the master realm, and then import the client into your realm. All settings except roles appear to be exported for the client, so you will need to set up roles again after you import the client into your realm. You can export and import a client as follows:

   1. From the master realm, click Clients in the navigation to open the list of clients on the Clients list tab.
   2. Open the options menu [⋮] for the client and click Export to download the client definition in .json format to a location of your choice.
      
   3. Switch to your realm, click Clients in the navigation, and then click Import client.
      
   4. Upload the .json file that you exported into the Import client page, and then click Save. The imported client details are displayed in tabs. You can review the fields and then use the Roles tab to create the roles for the Designer or Dashboard client again as described in step 8.
      
2. From the navigation, click Clients to open the Clients page.
3. On the Clients list tab, click Create client.
   
4. Complete the General settings fields as follows:
   1. Leave the client type as OpenID Connect.
   2. In the Client ID field, specify a unique name to associate the Designer or Dashboard instance that you plan to create later. For example, you can use the following format:
      • Designer instance: designer-namespace-designerName
      • Dashboard instance: dash-namespace-dashboardName

      Where:

      • namespace is the namespace where you plan to create the Designer or Dashboard instance.
      • designerName is the name that you will assign to the Designer instance. This name is the metadata.name value in the CR settings that are defined for the Designer instance.
      • dashboardName is the name that you will assign to the Dashboard instance. This name is the metadata.name value in the CR settings that are defined for the Dashboard instance.

      For example, if you plan to create instances for team AXE in the ace-shanna namespace, and intend to name their Designer instance des-axe-acecclic, and their Dashboard instance db-axe-acecclic, you can specify the client IDs as follows:

      • designer-ace-shanna-des-axe-acecclic
      • dash-ace-shanna-db-axe-acecclic
   3. Copy the Client ID to a text document for later use.
   4. Optional: Specify a name and description for the client.
      
      
   5. Click Next.
5. Complete the Capability config fields as follows:
   1. Set both Client authentication and Authorization to on.
   2. Ensure that the Standard flow and Direct access grants checkboxes are selected.
      
   3. Click Next.
6. Leave the Login settings fields blank for now and click Save.
   Note: After you create the Designer or Dashboard instance, you will need to revisit these client details to complete the Valid redirect URIs field with a callback URL for the instance. Because this value needs to include the URL that is generated for the instance when you create it, you cannot complete the field now.

   
7. On the Client details page, click the Credentials tab.

   The Client Secret field is automatically populated with a generated value that stores the client ID that you specified for the instance and a generated secret.

   Copy the Client Secret value to a text document for later use.

   
8. Create the reserved roles for the Designer or Dashboard instance as follows:
   1. Click the Roles tab and then click Create role.
      
      
   2. Complete the fields in the Create role page.

      For a Designer instance, set the following values and click Save.

      Role name	Description
      designerauthoring-admin	Assigns full access to App Connect Designer

      

      For a Dashboard instance, set the values in the following table in turn.

      1. Define the first role and click Save.
      2. Click Client details in the breadcrumbs to return to the Roles tab.
      3. Click Create role again, specify the details for the second role, and then click Save.

      Role name	Description
      dashboard-admin	Assigns full access to the App Connect Dashboard
      dashboard-viewer	Assigns read-only access to the App Connect Dashboard

      

      For more 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.

   3. Click Client details in the breadcrumbs to return to the Roles tab. Any roles that you defined are displayed in the list of roles.
9. Configure client scopes for the Designer or Dashboard instance.
   1. Click the Client scopes tab and locate the client scope that is automatically generated for the Designer or Dashboard client that you just created.

      The client scope is named in the format clientID-dedicated.

   2. Click the client scope in the table.
      
   3. On the Mappers tab, click Add mapper and then click By configuration.
      
   4. In the Configure a new mapper panel, locate and click User Client Role in the table.
      
   5. Complete the Add mapper page as follows. (The Mapper type value is inherited from your previous selection and cannot be changed.)
      1. Specify a unique name for this mapper in the Name field; for example, effective-client-role.
         Note: This name can be any string value that you prefer, but these instructions provide a suggested name.
      2. From the Client ID drop-down list, select the client ID that you created the Designer or Dashboard instance.
      3. Set the value for the Token Claim Name field to effective-roles, which is a reserved name that is referenced when verifying roles.
      4. Ensure that all of these switches are set to on: Multivalued, Add to ID token, Add to access token, and Add to userinfo.
         
      5. If you are using the Keycloak Admin Console in a Kubernetes environment, also ensure that the Add to token introspection switch is set to on. This switch is not visible on Red Hat OpenShift although it is on by default.
         
      6. Click Save.
   6. Applicable for a Designer instance only: Add three more mappers for the client scope for a Designer instance.
      1. Click the Dedicated scopes breadcrumb to return to the Mappers tab.
      2. Click Add mapper and then click By configuration.

         In the Configure a new mapper panel, locate and click User Attribute in the table.

         

         Then, complete the Add mapper page as described in step 9.e. For this mapper, set the Name value to LDAP_ID, and set the Token Claim Name value to ldap_id, which is a reserved name that is referenced when verifying roles. Also ensure that the Add to ID token, Add to access token, and Add to userinfo switches are set to on and then click Save.

         
      3. Click the Dedicated scopes breadcrumb to return to the Mappers tab.
      4. Click Add mapper and then click By configuration.

         In the Configure a new mapper panel, locate and click User Session Note in the table.

         

         Then, complete the Add mapper page as described in step 9.e. For this mapper, set the Name value to identity_provider, and set the Token Claim Name value to identity_provider, which is a reserved name that is referenced when verifying roles. Also ensure that the Add to ID token, Add to access token, and Add to userinfo switches are set to on and then click Save.

         
      5. Click the Dedicated scopes breadcrumb to return to the Mappers tab.
      6. Click Add mapper and then click By configuration.

         In the Configure a new mapper panel, locate and click User Session Note in the table.

         

         Then, complete the Add mapper page as described in step 9.e. For this mapper, set the Name value to identity_provider_identity, and set the Token Claim Name value to identity_provider_identity, which is a reserved name that is referenced when verifying roles. Also ensure that the Add to ID token, Add to access token, and Add to userinfo switches are set to on and then click Save.

         
   7. Click the Dedicated scopes breadcrumb to return to the Mappers tab. For a Designer client, the four mappers that you defined are included in the list of mappers on the Mappers tab. For a Dashboard client, the single mapper that you defined is included in the list of mappers on the Mappers tab.
      
      

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

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

1. Collate the following data, which you need to provide from the Red Hat OpenShift web console, or the Red Hat OpenShift or Kubernetes CLI, when you create the Designer or Dashboard instance.

   Data	How to locate and specify this value
   The URL that you can use to access your Keycloak instance.	To locate this value, which needs to be in the format https://KC_HOSTNAMEvalue, see Locating the URL for your Keycloak instance. Specify this value in the Endpoint fields, or in both spec.authentication.integrationKeycloak.endpoint and spec.authorization.integrationKeycloak.endpoint in the Designer or Dashboard CR settings.
   The name of the Keycloak realm that is used to manage users and their access to the Designer or Dashboard instance.	This value is the name of the realm that you created while configuring the Keycloak deployment. Specify this value in the Realm fields, or in both spec.authentication.integrationKeycloak.realm and spec.authorization.integrationKeycloak.realm in the Designer or Dashboard CR settings.
   The ingress host prefix and subdomain that are combined to form a hostname or ingress route for the Designer or Dashboard UI.	To determine this value, which is applicable only for a Kubernetes environment, see Manually creating ingress definitions for external access to your IBM App Connect instances in Kubernetes environments. Because you need to specify this value before you create the Designer or Dashboard instance, you can determine beforehand what <designerAuthoringUIHostPrefix> and <ingress_subdomain> should be for the Designer UI, or what <dashboardHostPrefix> and <ingress_subdomain> should be for the Dashboard UI. Then, specify the value in this format: Designer: <designerAuthoringUIHostPrefix>.<ingress_subdomain> Dashboard: <dashboardHostPrefix>.<ingress_subdomain> Specify this value in the Ingress Host fields, or in both spec.authentication.integrationKeycloak.tls.ingressHost and spec.authorization.integrationKeycloak.tls.ingressHost in the Designer or Dashboard CR settings.
   The name of a secret that stores the CA certificate from Keycloak, and which you need to establish secure communication between the Designer or Dashboard instance and the Keycloak instance. This secret uses a key/value pair to specify the certificate, where: The name of the key is ca.crt or your preferred name. The value specifies the Base64-encoded CA certificate from Keycloak.	To generate this secret, see step 2 of the current procedure. Specify this value in the Secret Name fields, or in both spec.authentication.integrationKeycloak.tls.secretName and spec.authorization.integrationKeycloak.tls.secretName in the Designer or Dashboard CR settings.
   The name of the key in a key/value pair that defines the CA certificate from Keycloak. The name of the key can be ca.crt or your preferred name, and the value specifies the Base64-encoded CA certificate. This key and the certificate are stored as a key/value pair in a secret.	To locate this value, see step 2 of the current procedure. Specify this value in the Ca Certificate fields, or in both spec.authentication.integrationKeycloak.tls.caCertificate and spec.authorization.integrationKeycloak.tls.caCertificate in the Designer or Dashboard CR settings.
   The name of a Kubernetes secret that stores the user-supplied client ID and generated client secret of the Keycloak client.	To generate this secret, see step 3 of the current procedure. Specify this value in the Client Secret Name fields, or in both spec.authentication.integrationKeycloak.auth.clientSecretName and spec.authorization.integrationKeycloak.auth.clientSecretName in the Designer or Dashboard CR settings.

2. In your cluster, create a Kubernetes secret that stores the certificate authority (CA) certificate from Keycloak. This certificate is needed to establish secure communication between the Designer or Dashboard instance and the Keycloak instance.
   1. Obtain the CA certificate that you used to configure your Keycloak deployment in Setting up a self-managed deployment of Keycloak.
   2. Base64 encode the certificate contents. (Depending on your operating system, you can use commands such as echo, base64, or certutil to do so.)

      echo -n '-----BEGIN CERTIFICATE-----\nxxx\n-----END CERTIFICATE-----' | base64

   3. To create the secret, use the following YAML manifest for a Secret resource, where:
      • secretName is a name that you assign to the secret.
      • namespaceName is the namespace where you intend to deploy the Designer or Dashboard instance.
      • caCertificateKeyName represents the key in a key/value pair that specifies the CA certificate from Keycloak. The key has a default name of ca.crt, but you can specify another name if preferred.
      • base64Encoded_CAcertificate represents the value in the key/value pair, and specifies the Base64-encoded value of the CA certificate from the previous step.

      apiVersion: v1
      kind: Secret
      metadata:
        name: secretName
        namespace: namespaceName
      data:
        caCertificateKeyName: "base64Encoded_CAcertificate"
      type: Opaque

      Use your preferred method to create the secret from the Red Hat OpenShift web console, or from the Red Hat OpenShift or Kubernetes CLI.

      • For example, from the Red Hat OpenShift web console, click the Import YAML icon in the banner, paste the updated YAML manifest, and then click Create.
      • Or, save the updated YAML manifest to a file (myCAFile.yaml) and then use the CLI to run the following command:
        

        oc apply -f myCAFile.yaml

        

        kubectl apply -f myCAFile.yaml

3. In your cluster, create a Kubernetes secret that stores the credentials for the Keycloak client that you created earlier for your Designer or Dashboard instance. The credentials define the client ID that you supplied and the client secret that was generated when you created the Keycloak client.
   1. Obtain the Client ID and Client Secret values for the Keycloak client that you created in Creating a Keycloak client for an App Connect Designer or App Connect Dashboard instance that you plan to deploy.
   2. Base64 encode the Client ID value and the Client Secret value in turn. (Depending on your operating system, you can use commands such as echo, base64, or certutil to do so.)

      echo -n 'clientIDValue' | base64

      echo -n 'clientSecretValue' | base64

      Designer example:

      echo -n 'designer-ace-shanna-des-axe-acecclic' | base64

      echo -n '0N1qOSHabcPmGY8irWEp6CpASSmpXYz5' | base64

      Dashboard example:

      echo -n 'dash-ace-shanna-db-axe-acecclic' | base64

      echo -n 'aBc5sgWe9zo5vEMXT88viykzSYJpeHlM' | base64

   3. To create the secret, use the following YAML manifest for a Secret resource, where:
      • clientSecretName is a name that you assign to the secret.
      • namesapceName is the namespace where you intend to deploy the Designer or Dashboard instance.
      • base64Encoded_clientIDvalue is the Base64-encoded Client ID value in a key/value pair, where CLIENT_ID is the key.
      • base64Encoded_clientSsecretValue is the Base64-encoded Client Secret value in a key/value pair, where CLIENT_SECRET is the key.

      apiVersion: v1
      kind: Secret
      metadata:
        name: clientSecretName
        namespace: namesapceName
      data:
        CLIENT_ID: base64Encoded_clientIDvalue
        CLIENT_SECRET: base64Encoded_clientSsecretValue
      type: Opaque

      Use your preferred method to create the secret from the Red Hat OpenShift web console, or from the Red Hat OpenShift or Kubernetes CLI.

      • For example, from the Red Hat OpenShift web console, click the Import YAML icon in the banner, paste the updated YAML manifest, and then click Create.
      • Or, save the updated YAML manifest to a file (myCredentialsFile.yaml) and then use the CLI to run the following command:
        

        oc apply -f myCredentialsFile.yaml

        

        kubectl apply -f myCredentialsFile.yaml

4. Create an IAM-enabled App Connect Designer or App Connect Dashboard instance.
   • To create an IAM-enabled App Connect Designer instance, follow the instructions in App Connect Designer reference: Creating an instance.
     Notable settings for IAM:

     • For an independent deployment of the IBM App Connect Operator, you are entitled to use only AppConnectEnterprise* style licenses for your App Connect Designer and App Connect Dashboard instances (and other App Connect resources).
     • Specify the Keycloak settings.
       • Ensure that Keycloak is enabled for both authentication and authorization. The Auth/Enabled checkboxes for authentication and authorization must both be selected, or both spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled must be set to true in the Designer or Dashboard CR settings. Keycloak is enabled by default.
       • Specify the remaining Keycloak authentication and authorization values that you collated in step 1.
     • Set the version of the instance (spec.version) to the 12.0 channel, or to a fully qualified value of 12.0.12.3-r1 or later.

     The following examples (Example 1 and Example 2) show a Designer CR with settings to configure CouchDB storage, and configure an existing switch server for callable flow and private network connectivity. The settings also enable Mapping Assist and incremental learning with a persistent-claim storage definition for the AI model.

     Example 1: Keycloak enabled for IAM

     apiVersion: appconnect.ibm.com/v1beta1
     kind: DesignerAuthoring
     metadata:
       name: des-axe-acecclic
       labels:
         backup.appconnect.ibm.com/component: designerauthoring
       namespace: mynamespace
     spec:
       license:
         accept: true
         license: L-KPRV-AUG9NC
         use: AppConnectEnterpriseProduction
       couchdb:
         storage:
           size: 10Gi
           type: persistent-claim
           class: ocs-storagecluster-cephfs
         replicas: 1
       designerMappingAssist:
         incrementalLearning:
           storage:
             type: persistent-claim
             class: ocs-storagecluster-cephfs
           schedule: Every 15 days
           useIncrementalLearning: true
         enabled: true
       switchServer:
         name: default
       authentication:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-des-axe-acecclic
           tls:
             caCertificate: ca.crt
             secretName: secretname-tls
           enabled: true
           endpoint: 'https://keycloak-mynamespace.apps.acecc-somedomain.abc.com'
           realm: exampleRealm
       authorization:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-des-axe-acecclic
           tls:
             secretName: secretname-tls
             caCertificate: ca.crt
           enabled: true
           realm: exampleRealm
           endpoint: 'https://keycloak-mynamespace.apps.acecc-somedomain.abc.com'
       designerFlowsOperationMode: local
       replicas: 1
       version: '13.0'

     Example 2: Keycloak enabled for IAM (with an additional setting for ingress)

     apiVersion: appconnect.ibm.com/v1beta1
     kind: DesignerAuthoring
     metadata:
       name: des-axe-acecclic
       labels:
         backup.appconnect.ibm.com/component: designerauthoring
       namespace: mynamespace
     spec:
       license:
         accept: true
         license: L-KPRV-AUG9NC
         use: AppConnectEnterpriseProduction
       couchdb:
         storage:
           size: 10Gi
           type: persistent-claim
           class: ibmc-file-gold-gid
         replicas: 1
       designerMappingAssist:
         incrementalLearning:
           storage:
             type: persistent-claim
             class: ibmc-file-gold-gid
           schedule: Every 15 days
           useIncrementalLearning: true
         enabled: true
       switchServer:
         name: default
       authentication:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-des-axe-acecclic
           tls:
             caCertificate: ca.crt
             ingressHost: designerAuthoringUIHostPrefix.ingress_subdomain
             secretName: secretname-tls
           enabled: true
           endpoint: 'https://example-keycloak-ab1234cde56fg789h0b7cd114438a79t4-0000.us-south.containers.appdomain.cloud'
           realm: exampleRealm
       authorization:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-des-axe-acecclic
           tls:
             secretName: secretname-tls
             ingressHost: designerAuthoringUIHostPrefix.ingress_subdomain
             caCertificate: ca.crt
           enabled: true
           realm: exampleRealm
           endpoint: 'https://example-keycloak-ab1234cde56fg789h0b7cd114438a79t4-0000.us-south.containers.appdomain.cloud'
       designerFlowsOperationMode: local
       replicas: 1
       version: '13.0'

   • To create an IAM-enabled App Connect Dashboard instance, follow the instructions in App Connect Dashboard reference: Creating an instance.
     Notable settings for IAM:

     • For an independent deployment of the IBM App Connect Operator, you are entitled to use only AppConnectEnterprise* style licenses for your App Connect Designer and App Connect Dashboard instances (and other App Connect resources).
     • Specify the Keycloak settings.
       • Ensure that Keycloak is enabled for both authentication and authorization. The Auth/Enabled checkboxes for authentication and authorization must both be selected, or both spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled must be set to true in the Designer or Dashboard CR settings. Keycloak is enabled by default.
       • Specify the remaining Keycloak authentication and authorization values that you collated in step 1.
     • Set the version of the instance (spec.version) to the 12.0 channel, or to a fully qualified value of 12.0.12.3-r1 or later.

     The following examples (Example 3 and Example 4) show a Dashboard CR with settings for a persistent-claim storage type and a display mode that provides a view of integration runtimes only. The spec.switchServer.name setting references an existing switch server that is used for callable flow and private network connectivity, and spec.api.enabled is set to true to enable the API for IBM App Connect in containers.

     Example 3: Keycloak enabled for IAM

     apiVersion: appconnect.ibm.com/v1beta1
     kind: Dashboard
     metadata:
       name: db-axe-acecclic
       labels:
         backup.appconnect.ibm.com/component: dashboard
       namespace: mynamespace
     spec:
       license:
         accept: true
         license: L-KPRV-AUG9NC
         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
       switchServer:
         name: default
       authentication:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-db-axe-acecclic
           tls:
             caCertificate: ca.crt
             secretName: secretname-tls
           enabled: true
           endpoint: 'https://keycloak-mynamespace.apps.acecc-somedomain.abc.com'
           realm: exampleRealm
       authorization:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-db-axe-acecclic
           tls:
             caCertificate: ca.crt
             secretName: secretname-tls
           enabled: true
           endpoint: 'https://keycloak-mynamespace.apps.acecc-somedomain.abc.com'
           realm: exampleRealm
       api:
         enabled: true
       storage:
         size: 5Gi
         type: persistent-claim
         class: ocs-storagecluster-cephfs
       displayMode: IntegrationRuntimes
       replicas: 1
       version: '13.0'

     Example 4: Keycloak enabled for IAM (with an additional setting for ingress)

     apiVersion: appconnect.ibm.com/v1beta1
     kind: Dashboard
     metadata:
       name: db-axe-acecclic
       labels:
         backup.appconnect.ibm.com/component: dashboard
       namespace: mynamespace
     spec:
       license:
         accept: true
         license: L-KPRV-AUG9NC
         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
       switchServer:
         name: default
       authentication:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-db-axe-acecclic
           tls:
             caCertificate: ca.crt
             secretName: secretname-tls
             ingressHost: dashboardHostPrefix.ingress_subdomain
           enabled: true
           endpoint: 'https://example-keycloak-ab1234cde56fg789h0b7cd114438a79t4-0000.us-south.containers.appdomain.cloud'
           realm: exampleRealm
       authorization:
         integrationKeycloak:
           auth:
             clientSecretName: clientsecretname-db-axe-acecclic
           tls:
             caCertificate: ca.crt
             secretName: secretname-tls
             ingressHost: dashboardHostPrefix.ingress_subdomain
           enabled: true
           endpoint: 'https://example-keycloak-ab1234cde56fg789h0b7cd114438a79t4-0000.us-south.containers.appdomain.cloud'
           realm: exampleRealm
       api:
         enabled: true
       storage:
         size: 5Gi
         type: persistent-claim
         class: ibmc-file-gold-gid
       displayMode: IntegrationRuntimes
       replicas: 1
       version: '13.0'

   Note: After the Designer or Dashboard instance is created with a Ready status, follow the instructions to display the URL that is generated for accessing the instance. Make a note of this URL so that you can provide it in the next step.

   • For a Designer instance, this value is displayed in the Designer UI field when you view the Designer instance details from the Red Hat OpenShift web console. Alternatively, you can view this value in the URL column of the output that you get when you run oc get designerauthorings.
   • For a Dashboard instance, this value is displayed in the Dashboard UI field when you view the Dashboard instance details from the Red Hat OpenShift web console. Alternatively, you can view this value in the UI URL column of the output that you get when you run oc get dashboards.
5. To make the instance ready for user access, complete these additional configuration steps.
   • If you are working in a Kubernetes environment, create an ingress resource that will be used to route external traffic to the Designer or Dashboard instance. (On Red Hat OpenShift, a route is automatically created.)

     For more information, see Manually creating ingress definitions for external access to your IBM App Connect instances in Kubernetes environments.

   • Complete the setup for the Keycloak client that you created earlier for the Designer or Dashboard instance.
     1. Open the Keycloak Admin Console to complete the setup.
     2. Ensure that your realm is selected.
     3. From the navigation, click Clients to open the Clients page.

        On the Clients list tab, you see the list of clients that are created for your Designer and Dashboard instances and for other Keycloak applications and services.

     4. Click the client ID of the Designer or Dashboard instance to view additional details about the instance.
     5. On the Settings tab, go to the Access settings section and complete the Valid redirect URIs field. This value identifies the URL that validated users should be redirected to after they enter their Keycloak credentials to log in to the Designer or Dashboard instance.
        • For a Designer instance on Red Hat OpenShift, construct the full value as follows, where designerUI is the URL for accessing the instance.

          https://designerUI/auth/icp/callback

          Example:

          https://des-axe-acecclic-ui-ace-shanna.apps.acecc-somedomain.abc.com/auth/icp/callback

          
        • For a Designer instance on Kubernetes, construct the full value as follows, where the combination of designerAuthoringUIHostPrefix and ingress_subdomain represent the ingress route that you created for accessing the instance. In the ingress route, designerAuthoringUIHostPrefix is a unique user-supplied name for the instance and ingress_subdomain is the ingress subdomain.

          https://designerAuthoringUIHostPrefix.ingress_subdomain/auth/icp/callback

          Example:

          https://ace-des.mycluster-a1b2cdef345678g9hi012j3kl4567890-0000.us-south.containers.appdomain.cloud/auth/icp/callback

        • For a Dashboard instance on Red Hat OpenShift, construct the full value as follows, where dashboardUI is the URL for accessing the instance.

          https://dashboardUI/oauth/callback

          Example:

          https://db-axe-acecclic-ui-ace-shanna.apps.acecc-somedomain.abc.com/oauth/callback

          
        • For a Dashboard instance on Kubernetes, construct the full value as follows, where the combination of dashboardHostPrefix and ingress_subdomain represent the ingress route that you created for accessing the instance. In the ingress route, dashboardHostPrefix is a unique user-supplied name for the instance and ingress_subdomain is the ingress subdomain.

          https://dashboardHostPrefix.ingress_subdomain/oauth/callback

          Example:

          https://ace-dash.mycluster-a1b2cdef345678g9hi012j3kl4567890-0000.us-south.containers.appdomain.cloud/oauth/callback

     6. Optional: In the Web origins field, specify the designerUI URL (or its equivalent ingress route), or the dashboardUI URL (or its equivalent ingress route).
        
        
     7. Click Save. After you see the Client successfully updated message, click Clients in the breadcrumbs to return to the Clients list tab on the Clients page.

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 realm that was created earlier.

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

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

   (Ensure that your 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, or Controlling access to the Admin Console in the Server Administration Guide from https://www.keycloak.org/.)

2. 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 and confirm. An entry is displayed to represent the password.
3. 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 your realm is displayed.

   4. Search this list to quickly locate the clients that you created for your Designer or Dashboard instances.

      In the search results, separate entries are shown for each role that is associated with a client and its related Designer or Dashboard instance.

      The following example shows the search results for roles that are associated with Designer and Dashboard instances that were created with the names des-axe-acecclic and db-axe-acecclic. The App Connect role named designerauthoring-admin is associated with the Designer client and its related instance, and the two App Connect roles named dashboard-admin and dashboard-viewer are associated with the Dashboard client and its related instance.

      
   5. Select the checkbox for each client 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 client/role mapping.
      
   For more information about setting up users, roles, and permissions in Keycloak, see the following information:

   • Managing users and Assigning permissions using roles and groups in the Server Administration Guide for the Red Hat build of Keycloak
   • Managing users and Assigning permissions using roles and groups in the Server Administration Guide from https://www.keycloak.org/

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

1. 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 Red Hat OpenShift web console, or the Red Hat OpenShift or Kubernetes 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.
      Note: On Kubernetes, provide the ingress route that you created for the Designer or Dashboard UI. For more information, see Manually creating ingress definitions for external access to your IBM App Connect instances in Kubernetes environments.
   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.
2. Optional: Locate and then provide the URL of the Keycloak Account Console.
   1. From the Keycloak Admin Console, ensure that your realm is selected as shown in this example.
      
   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/realmName/account.

      For example:

      https://keycloak-mynamespace.apps.acecc-somedomain.abc.com/realms/exampleRealm/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.