IBM Security Verify

 View Only

Integrate IBM Cloud Identity into Current ADFS Architecture for Zero Trust Conditional Access on Mobile

By Adam Case posted Thu January 02, 2020 08:00 AM


Using Cloud Identity as an identity provider for ADFS during mobile sign-on for passwordless authentication in a zero trust architecture.

In order to take full advantage of IBM Cloud Identity, IBM MaaS360, and your current Active Directory Federation Service (ADFS) architecture / investment, there are a few things to understand. First, IBM Cloud Identity will become an alternate Identity Provider to ADFS. Meaning when ADFS detects the user agent is mobile based, it will redirect the authentication request over to IBM Cloud Identity to handle to the rest. IBM MaaS360 is used in this pattern because it provides you the mobile device management security component, which delivers compliance and enrollment information to IBM Cloud Identity.

ADFS has about 30% of the overall federation market, simply because it's convenient to install, works with your current Microsoft investment, and most companies are entitled to it through their Microsoft licenses. While IBM Cloud Identity is a full Identity as a Service provider, delivering easy SSO and MFA options that enrich your security prospectus, it is important to work hand in hand with our customer's current deployment models. This guide will demonstrate how to accomplish integrating all three into one cohesive, zero-trust, architecture without impacting your day to day business operations.

Table of Contents

  1. Architecture Overview
  2. User Experience
  3. Prerequisites
  4. Enable the Identity Service and MDM policy in IBM MaaS360 for Single Sign-on
  5. Configure IBM Cloud Identity as an Claims Provider Trust (identity provider) in ADFS
  6. Configure ADFS as an application (service provider) in IBM Cloud Identity
  7. Redirect mobile authentication to IBM Cloud Identity for conditional access
  8. Add additional ADFS protected apps to IBM MaaS360 for SSO
  9. Test the mobile authentication flow

Architecture Overview


Communication path:

  1. Device (iOS or Android) accesses an application protected with ADFS
  2. The application (ex. Office365) redirects the user over to ADFS for authentication
  3. ADFS detects that the device is mobile, and redirects the authentication request over to IBM Cloud Identity

Given IBM Cloud Identity handles the mobile authentication logic and requires a certificate for authentication, the mobile device will present it upon request. If the mobile authentication fails, you can either have IBM Cloud Identity perform username / password authentication or simply outright block the request.
IBM Cloud Identity uses a certificate, installed on the device via IBM MaaS360, to validate the device is enrolled, and compliant.

User Experience

Mobile (Passwordless) Desktop (Basic User/Password)
iOS-adfs-redirect.gif desktop-adfs-redirect.gif


Understand that this modification is a global change, meaning all authentication on mobile will be redirected to IBM Cloud Identity. You can modify the onload.js in the theme for ADFS to look at the URL request and make a logical decision as well. However, for this guide, we are going to make a global change. We'll explain how to segment this in a later guide.

1. ADFS configured as an Identity Source
2. IBM Cloud Identity + IBM MaaS360 (you can obtain trials for both via IBM Marketplace)
3. IBM MaaS360 with matching user data to Active Directory either via manual entry or IBM Cloud Extender

We will be using a MaaS360 instance with the username that matches the userPrincipalName of the user. The regex used in the ADFS claims rule will extract the username from the upn format and convert it to the Windows Account Name format. Using ADFS claim rules can provide you flexibility in how to convert the username from whatever format you have to what ADFS expects.

Enable the Identity Service and MDM policy in IBM MaaS360 for Single Sign-on

In order to obtain a IBM Cloud Identity and MaaS360 linked tenant, you need to provision the tenant via IBM MaaS360's services. This will allow device data to synchronize between the two systems.

Read more on enabling this service here.


  1. Login to the MaaS360 portal as an administrator.
  2. Navigate to SETUP, then select ServicesScreen_Shot_2019-12-23_at_10_26_25_AM.png
  3. Find Identity and Access Management service.Screen_Shot_2019-12-23_at_10_26_35_AM.png
  4. Enable it and click Configure.
  5. Enter a tenant name, this is a descriptor name for your tenant.

    For example, if you enter bigblue, then your tenant will become You should not enter in the full hostname of the URL.
  6. Enter your IBMid and then click Configure.
  7. Navigate to your tenant once the tenant has been successfully created to verify you can access IBM Cloud Identity as an administrator.

Note: If you support Windows 10 devices then you will see an additional checkbox for laptop conditional access. Only enable the laptop access if you want to use conditional access for Windows 10.

Configure IBM Cloud Identity as an Claims Provider Trust (identity provider) in ADFS

To allow ADFS to redirect authentication to IBM Cloud Identity, we need to onboard IBM Cloud Identity to ADFS as a Claim Provider Trust. This is also known as an Identity Provider in typical IAM terms.


  1. Download your IBM Cloud Identity identity provider metadata from the following URL:

Note: Replace yourtenant with your actual tenant name that was created.


  1. Log into your Windows server as an administrator that has ADFS management configured.
  2. Open the ADFS Management console.
  3. Right-click on "Claims Provider Trust" and click Add Claims Provider Trust. The wizard will open up. Click Start.Screen_Shot_2019-12-21_at_12_08_24_PM.png
  4. Select the second radio button called "Import data about the claims provider from a file". Browse to your downloaded metadata from IBM Cloud Identity.Screen_Shot_2019-12-21_at_12_09_08_PM.png
  5. Give the Identity Source a name. This is a descriptor name for reporting purposes.Screen_Shot_2019-12-21_at_12_09_45_PM.png
  6. Review the configuration to ensure it matches what you would expect (ex. tenant name, certificate expirations, etc)
  7. Select the option to open the claims rule editor upon close. Click Close.Screen_Shot_2019-12-21_at_12_10_13_PM.png

Claims rules for username mapping


  1. Click Add New to add a new claim ruleScreen_Shot_2019-12-21_at_12_10_34_PM.png
  2. Select the option "Send Claims Using a Custom Rule".Screen_Shot_2019-12-21_at_12_11_00_PM.png
  3. Give the rule a name. In this case, we are transforming the MaaS360 username to Windows user name. Screen_Shot_2019-12-21_at_12_11_47_PM.png
  4. Paste in the custom rule that matches your use case from below. 
  5. Click Finish.

IBM MaaS360 synchronizes the user data from it's directory to IBM Cloud Identity. There a few patterns of username that can be used. Use the below mapping rule that matches your users the best:

Username is the userPrincipalName (UPN) attribute

Use the following claim in your claims rule. Replace the DOMAIN with your domain.

c:[Type == "", Properties[""] == "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"] => issue(Type = "", Issuer = "AD AUTHORITY", OriginalIssuer = c.OriginalIssuer, Value = regexreplace(c.Value, "(?[^@].+)@(?.+)", "DOMAIN\${user}"), ValueType = c.ValueType);

Example from MaaS360:

Username is the samAccountName attribute (without domain)

Use the following claim in your claims rule. Replace the DOMAIN with your domain.

c:[Type == "", Properties[""] == "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"] => issue(Type = "", Issuer = "AD AUTHORITY", OriginalIssuer = c.OriginalIssuer, Value = regexreplace(c.Value, "(?.+)", "DOMAIN\${user}"), ValueType = c.ValueType);

Example from MaaS360:

Username is the email address

If your username is the email address, ensure that another attribute matches either the UPN or samAccountName and follow the steps below on how to map the attribute to the preferred username.


  1. Login to IBM Cloud Identity as an administrator.
  2. Open the menu and navigate to Configuration.
  3. Select Identity Sources.
  4. Under the global settings section, select the proper attribute for Unique User Identifer from the drop down that is populated with either the UPN or samAccountName.
  5. Follow one of the prior claim rules that matches the attribute you selected.

Note: Read more here on these settings. Additional note, custom attributes cannot be used as unique idenfiers.

Configure ADFS as an application (service provider) in IBM Cloud Identity

For ADFS to successfully trust the authentication message coming back from IBM Cloud Identity, ADFS will need to be onboarded as an application (service provider).


  1. Download the ADFS metadata. The standard URL by default for this is:
  2. Copy the entity ID, search for entityID in the XML file. Ex.
  3. Copy the AssertionConsumerService Location URL, search for AssertionConsumerService Location in the XML file. Ex.


  1. Login to your IBM Cloud Identity tenant as an administrator.
  2. Open the menu, navigate to Applications.Screen_Shot_2019-12-21_at_12_43_28_PM.png
  3. Click Add Application.
  4. Select Custom Application from the list of available connectors.Screen_Shot_2019-12-21_at_12_44_04_PM.png
  5. Provide the application a name, such as ADFS
  6. Provide a descriptor Organization Name; this is a required field.Screen_Shot_2019-12-21_at_12_45_27_PM.png
  7. Navigate to the Sign On tab.
  8. Enter the entity ID that was copied, and paste it into the Provider ID field.
  9. Enter the Assertion Consumer Service URL in the corresponding field.
  10. Check the box for "Identity provider initiated sign in".
  11. Scroll to the bottom of the configuration and under access policies, uncheck the box to select an access policy.
  12. Select an access policy that corresponds with your security requirements. To block all access unless the device is managed and compliant, select "Allow access from compliant devices only; block otherwise". Screen_Shot_2019-12-21_at_12_50_10_PM.png
  13. Click OK when you're done making your selection.
  14. Click Save.
  15. Select the entitlements tab and entitle all users to this application.
  16. Click Save again.

Test the federated authentication flow


  1. Create a local user in Cloud Identity to test with.
  2. In a separate browser session, go to your IdP intiiated login URL for ADFS. Ex.
  3. Select IBM Cloud Identity from the list.Screen_Shot_2019-12-21_at_1_03_21_PM.png
  4. Login with the test user you created.
  5. The test would be successful if you have an established ADFS session.

Note: To debug this issue, onboard the RSA application as a Relying Party Trust in ADFS to verify the session was established

Redirect mobile authentication to IBM Cloud Identity for conditional access

In order to capture the authentication request and forward the request to an alternate identity source, you will need to modify the onload.js file on the Theme applied to ADFS.


  1. Ensure the test was successful between IBM Cloud Identity and ADFS.


  1. Log into the server that is configured for ADFS Management as an Administrator.
  2. Open powershell as an Administrator.
  3. Run the command mkdir c:\ibmci\.
  4. Run the following command to download the current default ADFS theme to the folder: Export-AdfsWebTheme –Name "Default" –DirectoryPath c:\ibmci
  5. Open the following file in a text editor: C:\ibmci\script\onload.js
  6. Right after "use strict" line, paste the following code snippet. Replace the yourtenant information with your hostname.

    var captureHeader = document.getElementById('hrdArea');
    if (captureHeader) {
       /* If user agent matches, redirect to IBM Cloud Identity */
       if (navigator.userAgent.match(/iPad|iPhone|Android/i) != null) {
       /* If user agent does not matches, perform normal username/password authentication */
       else {
          HRD.selection('AD AUTHORITY');
    /* Hide the authentication selection from the user. */ 
    var selectorui = document.getElementById("bySelection"); = "none";​
  7. Save the file, ensure you overwrite the old onload.js file.

  8. In powershell, create a new theme by duplicating the Default template:

    New-AdfsWebTheme –Name "IBMCI" –SourceName "Default"
  9. Perform the following command to overwrite the onload.js in the new theme:

    Set-AdfsWebTheme -TargetName "IBMCI" -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\ibmci\script\onload.js"}
  10. Set the new theme to active

    Set-AdfsWebConfig -ActiveThemeName "IBMCI"

    Note: You always have the ability to revert back to the default theme by replacing "IBMCI" with "Default" and running the command again.

  11. Restart the ADFS service to set the theme. You can do this through services.msc or running this command: Restart-Service adfssrv

Important: This is a global change to the Theme. If you only want to apply the mobile redirect on specific applications, additional modificiations to the onload.js will be needed to look at the URL being requested. A tutorial on modifying themes based on relying party are found here:

Add additional ADFS protected apps to IBM MaaS360 for SSO

In the MaaS360 portal, you must add the mobile apps to the MaaS360 App Catalog and set the app for Enterprise Single Sign On. If you have an existing application in the catalog, you can edit the application entry and check the box for "Enterprise Single Sign on".

For example, if you wanted to protect an application like Office365, you must add the Office365 mobile app to the MaaS360 App Catalog and check the box for Enable Enterprise single sign-on.

Additionally, you must enable the MDM policy for Single Sign on for both Android and iOS. Add the applications you wish to entitle to the MDM policy. This is an explicit permission. If the app is not included in the MDM payload, the certificate used to authenticate will fail to work.

The apps display in the Application Name selection based on Enterprise Single sign being checked in the App Catalog. After you save and publish the policy, the updated policy must be assigned to the mobile devices to take advantage of SSO and conditional access. This can be accomplished by setting the policy as the default, assigning the policy to a device group or single device.

Test the mobile authentication flow

  1. Cloud Identity is successfuly configured as Claims provider trust in ADFS
  2. ADFS is an application in Cloud Identity
  3. MaaS360's applications are enabled for Enterprise Single Sign on
  4. MaaS360's MDM policies are configured for Single Sign on and distributed to devices.
  1. Using a device that is enrolled in IBM MaaS360, open an application that uses ADFS as an authentication provider or navigate in Safari/Chrome to the website protected with ADFS.
  2. Attempt the authentication.
If your authentication is successful then you will not see any username/password field in ADFS, nor in IBM Cloud Identity.

If you see an IBM Cloud Identity login page, that means that your certificate is not valid or installed, or the MDM payload is missing from your device.