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 to IBM Cloud Paks and the workloads that run on IBM Cloud Paks.

Starting from IBM Cloud Pak foundational services 3.16, the SAML authentication flow is enhanced to support automated onboarding by just-in-time provisioning of users. You can configure single sign-on 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.

Integration with Azure Active Directory.

Prerequisites

To complete the configuration, you must:

Have a subscription to Microsoft Azure.
Be able to run oc or kubectl commands 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 <your-foundational-services-namespace>.
Have IBM Cloud Pak CLI (cloudctl) installed.
Have administrator access to the IBM Cloud Pak.

Steps

Complete the following steps to configure single sign-on with Azure Active Directory.

Retrieving the SAML metadata file

Log in to your IBM Cloud Pak with the following cloudctl command:
```
cloudctl login -a https://cp-console.xxx.com
```
You can retrieve your login URL by checking the foundational services route, for example, with the following command:
```
oc get route -n <your-foundational-services-namespace>
```
Enable SAML by running the following command:
```
cloudctl iam saml-enable
```
Export the SAML metadata file of your IBM Cloud Pak to your file system with the following command:
```
cloudctl iam saml-export-metadata --file <file_name>.xml
```
You will need the metadata file to complete the configuration.

Configuring

Complete the following actions in Microsoft Azure portal.

1. Create your own Azure Active Directory application

Log in to the Microsoft Azure portal.
From the Azure menu, select Azure Active Directory.
Select Enterprise applications from the navigation menu.
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.

2. Add users and groups to your application

On the Overview page, select the 1. Assign users and groups tile from the Getting started section.
Click Add user/group.
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.
Select the users and groups that you want to add to your application from the list, and click Select.
On the Add assignment page, click Assign.
Go back to your application overview.

3. Set up single sign on

On the Overview page, select the 2. Set up single sign on tile from the Getting started section.
Choose SAML.
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 retrieved at the beginning.
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.
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 via 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.
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.

Uploading the SAML configuration to IBM Cloud Pak

Use the following cloudctl command to upload the SAML configuration to the IBM Cloud Pak:

cloudctl iam saml-upload-metadata --file <local_path>/IBMCloudPak.xml

Specifying the token attribute mapping

Run the idsource registration API to specify the token attribute mapping.

   curl -k -X POST 'https://'$HOST'/idprovider/v2/auth/idsource/registration' \ --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header "Authorization: Bearer $TOKEN" \
   --data-raw '{
     "name": "idp_saml_azure",
     "description": "This is a saml azure config",
     "protocol": "saml",
         "idp_type": "default",
             "scim": "no",
                 "jit": "yes",
   "saml_ldap": "None",
     "token_attribute_mappings": {
                       "uid": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
             "first_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
             "last_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"
             },
             "status": "enabled" }'

To get your IBM Cloud Pak console URL, run the following command:
```
oc get route -n <your-foundational-services-namespace>
```
Copy the URL and paste it into your browser.
On the login screen, select Enterprise SAML. Use your Microsoft e-mail 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.

Granting an admin role

Assign the admin role to the user for full access to the Administration panel.

To view all users, use one of the following methods:
- Run the following command: cloudctl iam users
- Use the following API: https://<cluster_address>/idmgmt/identity/api/v1/users

Run the following command to add an admin role for a user:

cloudctl iam team-add-users austin CloudPakAdministrator -u <user e-mail>`

Granting 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 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.

Configure environment variables:
1. Obtain an IM access token for the default admin user. Log in as an admin using cloudctl, and run the command to obtain the access token. Copy the value after Bearer. Set the TOKEN environment variable, for example, export TOKEN=123abc.
2. Set HOST environment variable. To get the value, run the following command:
```
oc get route -n <your-foundational-services-namespace>
```
Set the HOST to the cp-console route. For example, `export HOST=
1. Set CPHOST environment variable. To get the value, run the following command:
```
oc get route -n <cloud-pak-namespace>
```
  Set CPHOST to be the cpd route with corresponding service name ibm-nginx-svc. For example, CPHOST=cpd-cp4i.apps.bunny.cp.abc.ibm.com.

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

curl -ki -X GET 'https://'$CPHOST'/v1/preauth/validateAuth' --header 'username: admin' --header "iam-token: $TOKEN"

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, in role identifiers specify "zen_administrator_role".

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 of all groupd to which a user belongs. You can check the Azure group ID in the Microsoft Azure portal. Go to Groups page, and find the Object Id of the specific group.

Add the Azure group into the user groups:

curl -k -s  -X POST 'https://'$CPHOST'/usermgmt/v2/groups/<group_ID>/members' \
--header 'Content-Type: application/json'   \
--header 'Accept: application/json'   \
--header "Authorization: Bearer $CPTOKEN" \
-d '{
"ldap_groups": ["e22aabc8-028e-49aa-9dd3-b6af8529bc46"]
}'

where the <group_ID> is the Azure group ID that you got in the previous step.

Configuration is complete.

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.