Configuring Application Engine for third-party app authentication

The following steps must be completed to create externally accessible business applications that use third-party authentication providers.

Before you begin

  • Be able to run the oc command with admin access to the Red Hat® OpenShift® Container Platform cluster.
  • Have foundational services version 3.14.x or later installed with your IBM Cloud Pak.
    Note: To check the foundational services version, run the following command: oc get csv -n ibm-common-services
  • Have administrator access to the IBM Cloud Pak.

Procedure

  1. Retrieve your IBM Cloud Pak console URL by running the following commands.
    cp_console_ns=<IBM Automation Foundation Namespace>
    cp_console_url=https://$(oc get route -n $cp_console_ns cp-console -o jsonpath="{.spec.host}")
  2. Retrieve your IBM access token by running the following commands.
    adminusr=$(oc get secret -n $cp_console_ns -o json ibm-iam-bindinfo-platform-auth-idp-credentials |jq .data.admin_username -r | base64 -d; echo "")
    adminusrpwd=$(oc get secret -n $cp_console_ns -o json ibm-iam-bindinfo-platform-auth-idp-credentials |jq .data.admin_password -r | base64 -d; echo "")
    adminiamtoken=$(curl -sk -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=password&username=$adminusr&password=$adminusrpwd&scope=openid" 
    $cp_console_url/idprovider/v1/auth/identitytoken  | jq -r .access_token)
  3. Enable IBM Cloud Pak SAML by running the following command.
    curl -k --location -g --request PUT "$cp_console_url/idmgmt/v1/saml/management" \
       --header "Authorization: Bearer $adminiamtoken" \
       --header 'Content-Type: application/json' \
       --data-raw '{
           "enable": true
       }'
  4. Export the IBM Cloud Pak SAML metadata by running the following command.
    curl -k --location -g --request GET "$cp_console_url/idauth/ibm/saml20/defaultSP/samlmetadata" \
       --header "Authorization: Bearer $adminiamtoken"
  5. Configure your identity provider SAML by using the IBM Cloud Pak SAML metadata. For this step, refer to your identity provider's documentation.
    If you're using Microsoft® Azure, see the Configuring section of Integrating IBM Cloud Pak SAML with Azure Active Directory.
    Note: The next step requires token attributes from your identity provider. When you configure your identify provider, take note of the following attributes:
    • sub
    • given_name
    • family_name
    • groups
    • email
    • uniqueSecurityName
  6. Upload the SAML configuration for your identity provider.
    1. Encode the IDP SAML configuration data as a Base64 string.
    2. Edit the values within < >, then run the following command.
      curl -k --location -g --request POST "$cp_console_url/idprovider/v3/auth/idsource" \
         --header "Authorization: Bearer $adminiamtoken" \
         --header 'Content-Type: application/json' \
         --data-raw '{
             "name": "<Your IDP name>",
             "description": "For SAML registration",
             "protocol": "saml",
             "type": "default",
             "idp_config": {
                 "token_attribute_mappings": {
                     "sub": "<IDP SAML Attribute for unique ID>",
                     "given_name": "<IDP SAML Attribute for given name>",
                     "family_name": "<IDP SAML Attribute for last name>",
                     "groups": "<IDP SAML Attribute for user groups>",
                     "email": "<IDP SAML Attribute for email address>",
                     "uniqueSecurityName": "<IDP SAML Attribute for unique Id>"
                 },
                 "idp_metadata": "<IDP SAML Configuration Base64 String>"
             },
             "jit": true
         }'
      Note: The values for the token_attribute_mappings come from your identity provider.
  7. Test the SAML login from the IBM Cloud Pak.
    1. Paste the value of cp_console_url into your browser. On the login screen, select Enterprise SAML. Use your SAML IDP credential to login. You can log in, but your view of the Administration page is limited. When you click at your profile avatar in the upper right, you see that you have a viewer access role.
  8. Grant access to capabilities within the IBM Cloud Pak.
    1. Retrieve the IBM Cloud Pak access token for the admin user by running the following commands.
      cp_ns=<IBM CP4BA Namespace>
      
      cp_url=https://$(oc get route -n $cp_ns cpd -o jsonpath="{.spec.host}")
      
      admincptoken=$(curl -sk -X GET "$cp_url/v1/preauth/validateAuth" --header "username: $adminusr" --header "iam-token: $adminiamtoken" |jq -r .accessToken)
    2. Create a user group with the role that you want to assign to the user.
      curl -k -s -X POST "$cp_url/usermgmt/v2/groups" \
      --header 'Content-Type: application/json'   \
      --header 'Accept: application/json'   \
      --header "Authorization: Bearer $admincptoken" \
      --data-raw '{
        "name": "saml_group",
        "description": "Default SAML user group",
        "role_identifiers": ["zen_user_role"]
      }'
      Note: To create an admin group, in role identifiers specify the zen_administrator_role.
    3. Verify that the group is listed, and remember the group ID.
      curl -k -s  -X GET "$cp_url/usermgmt/v2/groups" \
      --header 'Content-Type: application/json'   \
      --header 'Accept: application/json'   \
      --header "Authorization: Bearer $admincptoken"
    4. Configure automatic onboarding for the IDP user group to the IBM Cloud Pak.
      curl -k --location -g --request POST "$cp_url/usermgmt/v2/groups/<group_ID>/members" \
      --header "Authorization: Bearer $admincptoken" \
      --header 'Content-Type: application/json' \
      --data-raw '{
          "ldap_groups": [
              "<IDP SAML Group Attribute value>"
          ]
      }'
      Note: The <group_ID> is the group ID from the previous step.