Integrating IBM Cloud Pak SAML with Azure Active Directory

Learn how to integrate the IBM Cloud Pak® SAML with Azure Active Directory.

IBM Cloud Pak foundational services provides single sign-on (SSO) to IBM Cloud Paks and to workloads that run on the IBM Cloud Paks.

The SAML authentication flow supports automated onboarding by just-in-time (JIT) provisioning of users. You can configure SSO with Azure Active Directory, and grant user access to Cloud Pak Platform based on user's group membership from Azure Active Directory. After you complete the configuration, users who belong to an Azure Active Directory group are granted access to the IBM Cloud Pak.

To integrate the SAML with Azure Active Directory, complete the following steps:

• Prerequisites
• Configuring SSO with Azure Active Directory
• Configuring Azure as SAML IdP at IBM Cloud Pak®
• Configuring JIT support for Azure Active Directory integration

Prerequisites

To complete the configuration, you must meet the following requirements:

• Subscribe to Microsoft Azure.
• Be able to run oc or kubectl commands with admin access to the Red Hat® OpenShift® Container Platform cluster.
• Install foundational services with your IBM Cloud Pak.
• Grant a user administrator access to your IBM Cloud Pak.

Configuring SSO with Azure Active Directory

Complete the steps in the following sections to configure SSO with Azure Active Directory.

Retrieve the SAML metadata file from your IBM Cloud Pak

Complete these steps to download the SAML metadata file:

1. Retrieve your IBM Cloud Pak login URL by checking the foundational services route. For example, by using the following command:

    oc get route -n <your-foundational-services-namespace>
   

2. Log in to your IBM Cloud Pak console as an admin user.

3. Click Identity providers > New connection.

4. Select SAML 2.0.

5. On the New SAML connection page, click Download metadata.

Configure your Azure Active Directory application with SAML SSO

Complete the following tasks in the Microsoft Azure portal.

Create your own Azure Active Directory application. Add users and groups to your application. Set up SSO

Create your own Azure Active Directory application

1. Log in to the Microsoft Azure portal.
2. From the Azure menu, select Azure Active Directory.
3. From the navigation menu, select Enterprise applications.
4. Create you application.
   1. Click Create your own application.
   2. Enter the name of your application.
   3. Select the Integrate any other application you don't find in the gallery (Non-gallery) option.
   4. Click Create and wait a few seconds. The Overview page of your application opens.

Add users and groups to your application

1. On the Overview page, select the 1. Assign users and groups tile from the Getting started section.
2. Click Add user/group.
3. On the Add assignment page, under Users and groups, click None selected. The list of users and groups opens in a Users and groups window.
4. Select the users and groups that you want to add to your application from the list, and click Select.
5. On the Add assignment page, click Assign.
6. Go back to your application overview.

Set up SSO

1. On the Overview page, select the 2. Set up single sign on tile from the Getting started section.
2. Choose SAML.
3. Provide basic SAML configuration.
   1. On the Set up Single Sing-On with SAML page, click Upload metadata file.
   2. Select the SAML metadata file that you downloaded in the Retrieve the SAML metadata file section.
   3. Click Add.
      After you upload the metadata file, the Basic SAML configuration window opens. The following fields are automatically filled from the metadata file: Identifier, Reply URL, and Logout Url.
   4. Click Save, and go back to the Set up Single Sing-On with SAML page.
4. Configure group claim.
   1. On the Single Sing-On with SAML page, under Attributes and Claims, click Edit.
   2. Click Add a group claim. For more information, see Configure group claims for applications with Azure Active Directory in Microsoft documentation.
      Note: If an existing application expects to consume group information by using claims, Azure Active Directory can be configured with different claim formats.
   3. Select Groups assigned to the application as the groups that should be returned in the claim, and click Save.
5. Configure the SAML signing certificate. On the Single Sing-On with SAML page, under SAML Signing Certificate, click Download to save the Federation Metadata XML to your local drive.

Upload the Federation Metadata XML configuration to your IBM Cloud Pak

Complete these steps from your IBM Cloud Pak console:

1. Log in to your console as an admin user.

2. Click Identity providers.

3. Click the SAML connection that you created in Retrieve the SAML metadata file from your IBM Cloud Pak section.

4. Click Token attribute mapping.

5. Update the token attribute-mapping fields from the Azure Active Directory Federation Metadata XML file that you downloaded in the Set up SSO section.

6. Click Create.

7. From the Workloads page, restart all pods with platform- and usermgmt- in their name.

Test SAML login from the IBM Cloud Pak

1. To get your IBM Cloud Pak console URL, run the following command:

   oc get route -n <your-foundational-services-namespace>
   

2. Copy the URL and paste it into your browser.

3. On the login screen, select Enterprise SAML. Use your Microsoft email to log in, for example, user@cloudpak.onmicrosoft.com. You can log in. However, your view of the Administration panel is limited. When you click at your profile avatar, you see that you have a viewer access role.

Grant an admin role

Use the Zen console to assign the admin role to users.

Grant access to capabilities within an IBM Cloud Pak

You can customize access and grant users access to capabilities within the IBM Cloud Pak. Each capability can have a granular access control policy to control who can access different resources or APIs.

You can grant access to Cloud Pak Platform to users. By default, Cloud Pak Platform comes with two roles:

• User - Basic role that gives minimal access to the platform.
• Administrator - Admin role that gives access to the entire Cloud Pak Platform.

The user needs a User role to access the IBM Cloud Pak capabilities.

Complete the following steps to grant a User role for Cloud Pak Platform. The procedure is based on APIs.

1. Configure environment variables.

   1. Set $TOKEN variable.
      1. Log in as an admin by using oc.
      2. Obtain an IM access token for the default admin user. For more information, see Preparing to run API commands.
      3. Store the access token in the TOKEN environment variable.

          export TOKEN=<access-token-value>
         

   2. Set $HOST variable.
      1. Get the foundational services host value.

          oc get route -n <your-foundational-services-namespace>
         

      2. Set the HOST variable to the cp-console route.

          export HOST=<cp-console address>
         

         1. Set $CPHOST environment variable. To get the value, run the following command:
      3. Get the IBM Cloud Pak host value.

          oc get route -n <cloud-pak-namespace>
         

      4. Set the CPHOST variable to the cpd route. For example, CPHOST=cpd-cp4i.apps.bunny.cp.abc.ibm.com.

          export CPHOST=<cpd-route>
         

2. Set the project to the namespace where foundational services pods are running.

   oc project <your-foundational-services-namespace>
   

3. Get the IBM Cloud Pak access token for the admin user with the following command:

   curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=password&username=$(oc get secret platform-auth-idp-credentials -o json | jq -r) .data.admin_username| base64 -d&password=$(oc get secret platform-auth-idp-credentials -o json | jq -r) .data.admin_password | base64 -d&scope=openid" https://$(oc get routes cp-console -o jsonpath='{.spec.host}')/idprovider/v1/auth/identitytoken
   

4. Get the $IAMTOKEN value.

   IAM_TOKEN=$(curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d "grant_type=password&username=${USERNAME}&password=${PASSWORD}&scope=openid" "https://${CP_CONSOLE url}/idprovider/v1/auth/identitytoken" 2> /dev/null | jq -r ".access_token")
   

5. Extract and set the $CPTOKEN value from the $IAMTOKEN value that you got from the previous step.

   CPTOKEN=$(curl -k -X GET "${ZEN_URL}/v1/preauth/validateAuth" --header "username: ${USERNAME}" --header "iam-token: ${IAM_TOKEN}" 2> /dev/null | jq -r '.accessToken')
   

6. Create a user group with the role that you want to assign to the user.

   curl -k -s -X POST 'https://'$CPHOST'/usermgmt/v2/groups' \
   --header 'Content-Type: application/json'   \
   --header 'Accept: application/json'   \
   --header "Authorization: Bearer $CPTOKEN" \
   -d   '{"name": "azuregroup",
   "description": "Group default Azure group",
   "role_identifiers": ["zen_user_role"]
   }'
   

   Note: To create an admin group, specify "zen_administrator_role" in the role identifiers field.

   Verify that the group is listed, and get the group ID:

   curl -k -s -X GET 'https://'$CPHOST'/usermgmt/v2/groups' \
   --header 'Content-Type: application/json'   \
   --header 'Accept: application/json'   \
   --header "Authorization: Bearer $CPTOKEN"
   

   Save the Azure group ID, you will need it in the next step.

   Note: Azure SAML response contains the IDs or names of all groups to which a user belongs. You can check the Azure group ID or group name in the Microsoft Azure portal. Go to the Groups page, and find the Object Id or group name of the specific group.

7. Add the Azure group to the LDAP, SAML, or OIDC user group. You can specify the group ID or group name of the LDAP, SAML, or OIDC user group in the "idp_groups" parameter.

   curl -k -s -X POST 'https://'$CPHOST'/usermgmt/v2/groups/<azuregroup_ID>/members'
   --header 'Content-Type: application/json'
   --header 'Accept: application/json'
   --header "Authorization: Bearer $CPTOKEN"
   -d '{
   "idp_groups": ["group ID or group name of the user group"]
   }'
   

   In the command, the <azuregroup_ID> is the Azure group ID that you got in the previous step.

   Configuration is completed.

8. Verify whether the user who is a member of the Azure group can log in to Cloud Pak Platform with proper permissions. Open Cloud Pak Platform in your browser by using the URL of $CPHOST.

Configuring Azure as SAML IdP at CloudPak

To configure azure as SAML IdP, see Configure Azure as SAML IdP at CloudPak.

Configuring JIT support for Azure Active Directory integration

To configure JIT support for Azure Active Directory integration, see IBM Cloud Pak JIT support for SCIM OKTA and Azure AD.