Installing a CP4BA multi-pattern or FileNet® Content Manager production deployment with Okta or Microsoft Entra ID integration

Okta and Microsoft Entra ID (formerly Azure Active Directory or Azure AD) are cloud-based identity management services that support the System for Cross-domain Identity Management (SCIM) standard. They are used by organizations to manage employee access with well-defined groups of users that have the necessary authorization to access protected applications.

Before you begin

Your CP4BA deployment that you plan to use with Okta or Microsoft Entra ID must provide the Platform UI (Zen) route and Identity Management (IM) route (cp-console) with a valid trust certificate. The cp-console route must be accessible and trusted by the SCIM service (Okta or Microsoft Entra ID). For more information, see Customizing the Cloud Pak Identity Management (IM) service.

You must have a valid active Okta account and an Okta Org before you can configure your CP4BA deployment to use Okta. You can create an Okta developer Org by signing up on the Okta Dev portal.

Integration of the cloud-based services with Cloud Pak for Business Automation cannot be automated, so the configuration with the Identity Management (IM) service must be done before you install your CP4BA deployment.

Restriction: You cannot use the no cost (free) version of Microsoft Entra ID because it does not support Microsoft Entra ID groups.

About this task

Use the following steps to integrate Okta or Azure AD with your CP4BA production deployment.

Procedure

  1. Create a target namespace for your CP4BA deployment, apply the CP4BA catalog sources, and install the CP4BA operators.
    Set up the cluster by running the cp4a-clusteradmin-setup.sh script. For more information, see Preparing your cluster for an online deployment.
  2. Create the Cloud Pak foundational services resources that are needed to configure IM with Okta or Microsoft Entra ID.
    1. Create a YAML file (cs.yaml) with the following lines, and replace the values between << and >> with the values that you used to set up your cluster in Step 1.

      The instances where <<namespace>> appear in the following example refer to the dedicated-namespace or separate namespaces if you chose to install with Separation of Duties. When you are configuring a deployment that has separate namespaces for the CP4BA operators and the CP4BA deployments:

      • The operatorNamespace is where the operators are installed. The namespace must be different from the servicesNamespace.

      • The servicesNamespace is where the Operands (pods) are installed. The namespace must be different from the operatorNamespace.

      • Use oc get sc to identify the storage classes on your cluster. The retain-gold classes, like ibmc-block-retain-gold and ibmc-file-retain-gold, are good choices.

      apiVersion: operator.ibm.com/v3
      kind: CommonService
      metadata:
        namespace: <<namespace>>
        name: common-service
      spec:
        license:
          accept: true 
        operatorNamespace: <<namespace>>
        servicesNamespace: <<namespace>>
        size: starterset
        storageClass: <<block storage class in CP4BA cr>>
      ---
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: iaf-system-automationui-aui-zen-ss-issuer # fixed name
        namespace: <<namespace>>
      spec:
        selfSigned: {}
      ---
      apiVersion: cert-manager.io/v1
      kind: Certificate
      metadata:
        name: iaf-system-automationui-aui-zen-ca # fixed name
        namespace: <<namespace>>
      spec:
        commonName: IBM Automation Foundation CA
        duration: 2160h0m0s
        isCA: true
        issuerRef:
          kind: Issuer
          name: iaf-system-automationui-aui-zen-ss-issuer
        renewBefore: 720h0m0s
        secretName: iaf-system-automationui-aui-zen-ca # fixed value
        usages:
          - cert sign
          - signing
      ---
      apiVersion: cert-manager.io/v1
      kind: Issuer
      metadata:
        name: iaf-system-automationui-aui-zen-issuer # fixed name
        namespace: <<namespace>>
      spec:
        ca:
          secretName: iaf-system-automationui-aui-zen-ca
      ---
      apiVersion: cert-manager.io/v1
      kind: Certificate
      metadata:
        name: iaf-system-automationui-aui-zen-cert # fixed name
        namespace: <<namespace>>
      spec:
        commonName: cpd
        dnsNames:
          - cpd
          - cpd.{{ meta.namespace }} 
          - cpd.{{ meta.namespace }}.svc
          - <<sc_zen.zen_custom_route.route_host in cp4ba cr (default value is 'cpd-'+namespace+'.'+cluster_hostname_suffix)>>
        duration: 2160h0m0s
        issuerRef:
          kind: Issuer
          name: iaf-system-automationui-aui-zen-issuer
        renewBefore: 720h0m0s
        secretName: iaf-system-automationui-aui-zen-cert # fixed value
        usages:
          - key encipherment
          - server auth
          - digital signature
    2. Apply the resources by running the following command.
      Note: In the case that your deployment has Separation of Duties, then the Common Service CR must be created in the namespace of the operatorNamespace.
      oc apply -f cs.yaml
    3. Make sure that the iaf-system-automationui-aui-zen-cert secret is on the cluster by running the following command.
      oc get secret iaf-system-automationui-aui-zen-cert -o yaml
    4. Use the output of the previous command in two YAML files (OperandRequest.yaml) and (ZenService.yaml), and replace the values between << and >> with the values that you used to set up your cluster.

      OperandRequest.yaml file

      kind: Secret
      apiVersion: v1
      metadata:
        name: external-tls-secret # fixed name
        namespace: <<namespace>>
      data:
        ca.crt: <<ca.crt in secret iaf-system-automationui-aui-zen-cert>>
        cert.crt: <<tls.crt in secret iaf-system-automationui-aui-zen-cert>>
        cert.key: <<tls.key in secret iaf-system-automationui-aui-zen-cert>>
      type: Opaque
      ---
      apiVersion: operator.ibm.com/v1alpha1
      kind: OperandRequest
      metadata:
        namespace: <<namespace>>
        name: iaf-system-common-service
      spec:
        requests:
        - operands:
            - name: ibm-platformui-operator
            - name: ibm-im-operator
          registry: common-service
          registryNamespace: "ibm-common-services"  # fixed value

      ZenService.yaml file

      apiVersion: zen.cpd.ibm.com/v1
      kind: ZenService
      metadata:
        namespace: <<namespace>>
        name: iaf-zen-cpdservice
      spec:
        iamIntegration: true
        scaleConfig: starterset
        zenCustomRoute:
          route_host: <<sc_zen.zen_custom_route.route_host in cp4ba cr (default value is 'cpd-'+namespace+'.'+cluster_hostname_suffix)>>
          route_reencrypt: true 
          route_secret: iaf-system-automationui-aui-zen-cert
        fileStorageClass: <<faster storage class in CP4BA cr>>
        blockStorageClass: <<block storage class in CP4BA cr>>
      Tip: Use oc get sc to identify the storage classes on your cluster.
    5. Apply the changes by running the following commands.
      oc apply -f OperandRequest.yaml

      Wait a few minutes before you apply the Zen service.

      oc apply -f ZenService.yaml
      Note: It can take 30 minutes or more for the Zen and IM services to be ready. To check that the Zen service is ready, run the following command.
      oc get ZenService

      Continue to Step 3 only when the output shows that Zen is ready.

      NAME                   READY
      iaf-zen-cpdservice     True
  3. Complete the configuration of Okta or Microsoft Entra ID with the IM service.
    1. Follow the instructions on how to integrate IM with Okta or Microsoft Entra ID.
      For integration with Okta
      Use the Cloud Pak foundational services documentation here to complete the configuration with IM.
      For integration with Microsoft Entra ID
      Use the Cloud Pak foundational services documentation here to complete the configuration with IM.
      Tip: When you register the identity provider (IdP) in IM, use the IdP V3 API to pass the key values in a Curl command instead of parameters in a shell command. Save the value of the name for a later step. In this example, the value is AzureSAML.
      curl --location --request POST 'https://cpconsoleroute/idprovider/v3/auth/idsource' \
      --header 'Authorization: Bearer $accessToken' \
      --header 'Content-Type: application/json' \
      --data-raw
      '{
         "name": "AzureSAML",
         "description": "AzureSAML",
         "protocol": "saml",
         "type": "azuread",
         "idp_config":
          {
            "token_attribute_mappings": {
              "sub": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
              "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
              "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
              "groups": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
              "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
              "first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
              "last_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
          },
            "idp_metadata": "Base64-encoded-metadata"
          },
          "jit": false,
          "scim_config":
          {
            "redirect_url": ["azure_redirect_url"],
              "scim_attribute_mappings": {
                "user":
                {
                  "principalName": "userName",
                  "name":
                  {
                    "givenName": "givenName",
                    "familyName": "familyName"
                  },
                  "displayName": "displayName",
                  "emails":
                  [
                  {
                    "value": "emails",
                    "type": "home"
                  }
                  ],
                  "id": "id",
                  "userName": "userName"
                  },
                  "group":
                  {
                   "principalName": "displayName",
                   "id": "displayName"
                   "displayName": "displayName"
                  }
                }
            }
      }' 
    2. Make sure that Okta or Microsoft Entra ID users can login to the Zen (CPD) route.
      1. Get the Zen (CPD) route by running the following command.
        oc get route | grep cpd
      2. Open a browser by using the Zen route in the output of the previous command.
      3. Login with an Okta or Microsoft Entra ID user and make sure that the login is successful.
  4. Prepare for your CP4BA deployment.

    Use the steps in Preparing your chosen capabilities.

    Tip: Before you create a CP4BA deployment that integrates with Okta or Microsoft Entra ID, it is important to have the needed secrets and files in your cluster. The provided cp4a-prerequisites.sh script helps you to create all the necessary property files. To use Okta or Microsoft Entra ID, leave the values for the LDAP property files empty. Make sure that you enter valid information from your Okta or Azure AD for the credentials and initialization values in the cp4ba_user_profile.property file.
  5. Generate the custom resource (CR) for your CP4BA deployment.
  6. Configure the CR to integrate Okta or Microsoft Entra ID.
    Open the CR file to make the following changes:
    1. If the ldap_configuration section is present, then remove it.
    2. Set the shared_configuration.sc_skip_ldap_config parameter to true.
    3. Set the ecm_configuration.disable_basic_auth parameter to false.
    4. Set the navigator_configuration.disable_basic_auth parameter to false.
    5. Set the sc_content_initialization parameter to true and also define the initialize_configuration section in the CR for the operator to use the parameters.
    6. Add YAML to configure IM with Okta or Microsoft Entra ID.

      To configure Microsoft Entra ID, add the following YAML at the same level as the shared_configuration section.

      idp_iam_configuration:
        - idp_id: <this name must match with the Idp provider name in IM>
          idp_type: azuread
          idp_allow_email_or_upn_short_names: true (Optional - default value is true)

      Where idp_id is the name that matches the identity provider (IdP) name in IM. An example from a previous step is AzureSAML.

      To configure Okta, add the following YAML at the same level as the shared_configuration section.

      idp_iam_configuration:
        - idp_id: <this name must match with the Idp provider name in IM>
          idp_type: okta
          idp_allow_email_or_upn_short_names: true (Optional - default value is true)

    For more information about editing the CR, see Checking and completing your custom resource.

  7. Apply your CP4BA custom resource.
  8. Add new users for Zen from the IM service.
    Add users

    You can also create groups of users in Zen from the IM service.

    Create groups
  9. Login to the Zen UI with the new users.
    Login to Zen

    Members of a group can also login to the Zen UI.