Configuring VMware Identity Manager as a Claims Provider in AD FS: VMware Workspace ONE Operational Tutorial

VMware Workspace ONE UEM 9.4 and later VMware Identity Manager 3.3 and later

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Workspace ONE®environment. In this tutorial, you configure VMware Identity Manager™ as a claims provider within AD FS. You then test service provider-initiated login to an application federated with AD FS and AD FS authentication to the Workspace ONE catalog.

Audience

This operational tutorial is intended for IT professionals and Workspace ONE administrators of existing production environments. Familiarity with networking and storage in a virtual environment is assumed, including Active Directory, identity management, and directory services. Knowledge of additional technologies such as VMware Identity Manager™ and VMware Workspace ONE® UEM, is also helpful.

Configuring VMware Identity Manager as Claims Provider for AD FS

Introduction

With the rapid adoption of Office 365, more companies are looking to implement the Workspace ONE suite of solutions to improve the login experience for their end users into the Office 365 client applications.

VMware Identity Manager is certified to handle all authentication use cases for Office 365 as a standalone identity provider. Yet many companies that have transitioned to Office 365 have also implemented Microsoft’s identity provider of choice; Active Directory Federation Services (AD FS) to federate the authentication of their Office 365 domain. In many cases, it is not feasible for a company that has already deployed AD FS as their identity provider for Office 365 to change the configuration of their production tenant. This tutorial explores an alternative that allows a company to take advantage of the Workspace ONE end-user experience while avoiding having to make any critical changes to their current setup.

AD FS supports the use of a third-party identity provider and can redirect incoming authentication requests from an Office 365 client to VMware Identity Manager. VMware Identity Manager can then challenge the client device for the specific mobile SSO authentication method and seamlessly authenticate the user without the need to manually enter any credentials unless required by the company as a second factor of authentication.

This operational tutorial helps you to configure VMware Identity Manager as a third-party identity provider within AD FS. This guide assumes that Office 365 has already been set up and properly federated with an AD FS server. You need admin access to both the VMware Identity Manager tenant and AD FS server.

Prerequisites

Before you can perform the procedures in this tutorial, you must satisfy the following requirements. For more information, see the VMware Identity Manager Documentation and VMware Workspace ONE UEM Documentation.

Check whether you have the following components installed and configured:

  • Workspace ONE UEM tenant 9.4 and later with admin credentials
  • VMware Identity Manager tenant 3.3 and later
  • VMware Identity Manager login details
    • If your tenant is cloud-hosted, retrieve the login details from the email received when you set up the tenant
    • Or, retrieve your details from the Workspace ONE UEM Console; navigate to Content > Content Locker > List View and download the vIDM Tenant Details text file
  • Windows machine to install the VMware Identity Manager Connector
  • Use the VMware Identity Manager Connector to sync a domain and at least a single domain user to login with
  • Microsoft Active Directory Federated Services—this tutorial uses AD FS 2016
  • AD FS applications for testing—this tutorial uses Salesforce and MS Office 365
  • PowerShell with admin privileges

To ensure relying party trusts in AD FS can query Active Directory, you must meet the following requirements:

  • The claim rule has a value of type windowsaccountname (usually this value in the format domain\user).
  • In most cases, the Issuer of the claim value is set as AD AUTHORITY.

The following are examples of default claim rules for test applications used in this tutorial.

Office365: 

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/UPN", "http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID"), query = "samAccountName={0};userPrincipalName,objectGUID;{1}", param = regexreplace(c.Value, "(?<domain>[^\\]+)\\(?<user>.+)", "${user}"), param = c.Value);

Salesforce: 

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] 
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"), query = ";userPrincipalName;{0}", param = c.Value);

Logging In to the VMware Identity Manager Console

To perform most of the steps in this exercise, you must first log in to the VMware Identity Manager console.

1. Launch Google Chrome (If Needed)

If Google Chrome is not already open, launch Google Chrome by double-clicking the icon from the desktop.

2. Open a New Browser Tab

Click the Tab space to open a new tab.

4. Login to Your VMware Identity Manager Tenant

  1. Enter the Username, for example, Administrator.
  2. Enter the Password, for example, VMware1!.
  3. Click Sign In.

Adding VMware Identity Manager as a Claims Provider in AD FS

This section helps you to configure VMware Identity Manager as a claims provider within AD FS. This allows VMware Identity Manager to serve as an alternative method to authenticate incoming requests in AD FS, in addition to the default local Active Directory.

Note: Completing the steps within this section will add VMware Identity Manager as a claims provider for all relying parties within AD FS.

1. Navigate to Web Apps

In the VMware Identity Manager tenant:

  1. Select the Catalog drop-down menu.
  2. Select Web Apps.

2. Open Web Apps Settings Menu

Click Settings.

3. Download Identity Provider Metadata XML File

  1. Click SAML Metadata.
  2. Right-click Identity Provider (idP) metadata.
  3. Click Save Link As...

4. Save Metadata File Locally

Save the metadata file locally. You need to access this file from your AD FS console.

5. Open AD FS Management

On your AD FS server:

  1. Click the Server Manager icon from the taskbar.
  2. Click Tools.
  3. Click AD FS Management.

6. Add New Claims Provider in AD FS Management

  1. Click Claim Provider Trusts.
  2. Click Add New Claim Provider Trust.

7. Start the Add Claims Provider Wizard

Click Start.

8. Select the Data Source

  1. Select Import data about the claims provider from a file.
  2. Click Browse and select the idp metadata file from VMware Identity Manager. This is the idp file previously downloaded in Save Metadata File Locally.
  3. Click Next.

9. Specify Display Name

  1. Enter a friendly name for the new claims provider. For example, VMware Identity Manager.
  2. Click Next.

10. Review Settings

Review the settings and click Next.

11. Complete Claims Provider Wizard

  1. Select the check box Open the Edit Claim Rules...
  2. Click Close.

12. Validate New Claims Provider is Active

Test the service provider initiated authentication with one of the applications federated with AD FS.

When redirected to AD FS, you should now have VMware Identity Manager listed as an authentication option in addition to Active Directory.

Configuring a Claim Rule for VMware Identity Manager Claims Provider

This section helps you to add a claim rule for the VMware Identity Manager claims provider in AD FS. This claim rule should consume the value(s) received from the VMware Identity Manager SAML and issue a claim value that can be used as the target relying party trust. Instead of including all the values that might be needed for each relying party trust within the VMware Identity Manager SAML assertion, we include a single value that can identify the authenticated user, and be used to perform a query to Active Directory and retrieve the user values needed for each relying party trust.

In other words, in this exercise, you add a claim rule to the claim provider that will intake the user identifier from the SAML assertion, and in turn, issue a value of type windowsaccountname with the issuer set to AD AUTHORITY.

1. Add Claim Rule

Click Add Rule.

Note: The Edit Claim Rules window automatically opens if you previously selected the check box when completing the Claims Provider Wizard. If not, right-click the newly-created relying party and click Add Rule.

 

2. Send Claims Using a Custom Rule

  1. Select Send Claims Using a Custom Rule from the claim rule template drop-down menu.
  2. Click Next.

3. Configure Custom Claim Rule

The rule added in this step assumes that the SAML assertion issued by VMware Identity Manager contains a value in the form domain\samAccountName. If these values are not available in VMware Identity Manager, the integration can be configured to rely on the user's UserPrincipalName instead. If this is the case, see Appendix: Alternative Custom Claim Rules.

  1. Enter a friendly name for the new claim rule. For example, Transform NameID to windowsaccount + set AD as source.
  2. Copy the following claim rule into the Custom rule text box.

    c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] == "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer = "AD AUTHORITY", OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);
  4. Click Finish.

4. Accept Transform Rules

  1. Validate that the new claim rule has been added.
  2. Click OK.

5. Validate Custom Claim Rules are Added

  1. Validate that the new claim rules have been added.
  2. Click OK.

Downloading the AD FS Federation Metadata File

Before you configure the AD FS Application Source in VMware Identity Manager, you must download the AD FS federation metadata XML file. This exercise helps you to download the federation metadata file.

1. Download the Federation Metadata File

Navigate to https://<adfs_server_name>/FederationMetadata/2007-06/FederationMetadata.xml. Replace adfs_server_name with your AD FS server, for example, adfs.corp.local.

The FederationMetadata.xml downloads and automatically stores in your Downloads folder.

2. Copy AD FS Metadata Content

On your desktop, open and copy the contents of the federationmetadata.xml file downloaded from AD FS.

Configuring AD FS Application Source in VMware Identity Manager

After downloading the federation metadata, you are ready to begin configuring AD FS as an application source in VMware Identity Manager. In this exercise, create an access policy that applies only to SP-Initiated AuthN requests for applications federated with AD FS.

1. Navigate to Web Apps

In the VMware Identity Manager tenant:

  1. Select the Catalog drop-down menu.
  2. Select Web Apps.

2. Open Web Apps Settings Menu

Click Settings.

3. Configure AD FS Application Source

  1. Click Application Sources.
  2. Click ADFS.

4. Start the AD FS Application Source Wizard

Click Next.

5. Configure ADFS Application Source Single Sign-On

  1. Select URL/XML as the Configuration option.
  2. Paste the contents from the federationmetadata.xml file into the URL/XML text box.
  3. Click Next.

6. Configure AD FS Application Source Access Policy

  1. Select an Access Policy from the drop-down menu.
  2. Click Next.

7. Complete AD FS Application Source Wizard

Click Save.

8. Open AD FS Application Source

Click ADFS.

9. Modify AD FS Application Source Username Format and Value

  1. Click Configuration.
  2. Select Unspecified from the Username Format drop-down menu. This is the expected format from ADFS based on previously created claim rule.
  3. Enter the following in the Username Value:
    ${user.domain}\${user.userName}
  4. Click Advanced Properties.

10. Modify ADFS Application Source Signature Algorithm

Scroll-down to find the Signature Algorithm option.

  1. Select SHA256 with RSA from the Signature Algorithm drop-down menu.
    Note: This is the expected default signature algorithm for SAML assertion but this might differ in your environment.
  2. Click Summary.

11. Complete AD FS Application Source Wizard

Click Save.

Testing SP-Initiated Login with AD FS Applications

In this exercise, test SP-initiated login. Open an application federated with AD FS and confirm that you are prompted for VMware Identity Manager credentials. This example uses MS Office 365.

1. Test SP-Initiated Login with AD FS Application

Open MS Office 365.

2. Authenticate with VMware Identity Manager

When presented with the authentication options in AD FS, select VMware Identity Manager.

3. Enter User Credentials for VMware Identity Manager

Enter your user credentials and authenticate using VMware Identity Manager.

4. Validate Successful Authentication

Validate the the end user is successfully authenticated into the target application.

Copying the Relying Party Identifier

The relying party is your test application—in this case, MS Office 365. Before you can upload the MS Office 365 to the Workspace ONE catalog, you must copy its identifier.

1. Open Relying Party Properties in AD FS

In the AD FS Management console:

  1. Click Relying Party Trust.
  2. Right-click the Relying Party Trust for Microsoft Office 365 Identity Provider.
  3. Click Properties.

2. Copy Relying Party Identifier

  1. Select the Identifiers tab.
  2. Copy the Relying party identifier. For example, urn:federation:MicrosoftOnline for Office365.

Adding Microsoft Office 365 to Workspace ONE Catalog

Now that you have copied the identifier for Microsoft Office 365, you are ready to begin adding this AD FS application to the Workspace ONE Catalog. In this exercise, the authentication policy that you select applies only when launching the application from within the Workspace ONE catalog (IdP-initiated login).

1. Add New SaaS App in VMware Identity Manager

In the VMware Identity Manager console:

  1. Click Catalog.
  2. Click New.

2. Name the SaaS Application

  1. Enter a friendly name for the application. For example, ADFS 2016 - Office365.
  2. Click Next.

3. Configure Application Authentication Type and Target URL

  1. Select ADFS Application Source from the Authentication Type drop-down menu.
  2. Enter RPID= followed by the relying party identifier previously copied from ADFS. For example, RPID=urn:federation:MicrosoftOnline
  3. Click Next.

4. Configure Application Access Policy

  1. Select an Access Policy for the new application.
  2. Click Next.

5. Complete Application Configuration

Click Save & Assign.

6. Assign SaaS App to Users / Groups

  1. Assign the new application to a set of test users / user groups.
  2. Click Save.

7. Repeat Process for Additional Applications

Repeat the previous steps to add additional AD FS applications to the catalog. Modify the Target URL to match the relying party identifiers for those applications in AD FS.

Validating AD FS Authentication in the Workspace ONE Catalog

After you have added Microsoft Office 365 to the Workspace ONE catalog, complete the following steps to verify AD FS authentication to the Workspace ONE catalog.

1. Log In to Workspace ONE Catalog

Log in to the Workspace ONE catalog with a user assigned to the ADFS application.

Click Open to launch the ADFS application.

2. Launch Test Application Federated with AD FS

Verify that the user is successfully logged in to the target application.

Configuring VMware Identity Manager as Default Claims Provider

This section helps you to set VMware Identity Manager as the default claims provider for a specific relying party trust in AD FS. The example in this exercise uses the Salesforce application but you can also use MS Office 365. 

If you want to configure AD FS to redirect only mobile traffic to VMware Identity Manager, skip this section and go to Modifying AD FS to Forward Only Mobile Traffic to VMware Identity Manager.

1. Open PowerShell as Administrator

  1. Open Windows PowerShell from your AD FS server.
  2. Select Run as administrator.

2. Set the Default Claims Provider

Run the following command in PowerShell to set VMware Identity Manager as the default claims provider for a given relying party in ADFS:

Set-ADFSRelyingPartyTrust -TargetName Salesforce -ClaimsProviderName @("VMware Identity Manager")

Modify the command:

  • Replace Salesforce with the friendly name of the relying party within ADFS
  • Replace VMware Identity Manager if a different name was given to the VMware Identity Manager claims provider in AD FS.

For more information, see Home Realm Discovery Customization.

Verifying AD FS Forwards Traffic to VMware Identity Manager

After you have configured PowerShell, complete the steps in this section to verify that they applied successfully.

1. Test Authentication using Test Application

Test an SP-initiated authentication flow using the test application. In this example, the application is Salesforce.

2. Validate Default Redirection to VMware Identity Manager

You should be automatically presented with the VMware Identity Manager login screen.

Modifying AD FS to Forward Only Mobile Traffic to VMware Identity Manager

This section helps you to configure AD FS to forward only mobile traffic to VMware Identity Manager.

1. Open PowerShell as Administrator

  1. Open Windows PowerShell from your AD FS server.
  2. Select Run as administrator.

2. Create Working Folder

Run the following command to create a working folder:

mkdir c:\myscripts

3. Export Default AD FS Web Theme

Run the following command to export the AD FS Web Theme:

Export-AdfsWebTheme –Name default –DirectoryPath c:\myscripts

4. Open Text Editor as Administrator

  1. Open a text editor such as Notepad++.
  2. Select Run as administrator.

5. Open Onload.js File

  1. Select the onload.js file that was exported from AD FS.
  2. Click Open.

6. Insert JavaScript into Onload.js File

Replace {VIDMURL} with your VMware Identity Manager tenant URL.

If you are using AD FS version 4 and later, copy the following into the onload.js file and save.

var myCheckHRD = document.getElementById('hrdArea');
if (myCheckHRD) 
{	
	
	// redirect mobile traffic to Workspace ONE
	if (navigator.userAgent.match(/iPad|iPhone|Android|Windows Phone/i) != null)
	{
		HRD.selection('https://{VIDMURL}/SAAS/API/1.0/GET/metadata/idp.xml');
	}
	// else authenticate with local AD claims provider
	else 
	{
		HRD.selection('AD AUTHORITY');
	}
}
// hide HRD selector from user
	var hrdui = document.getElementById("bySelection");
	hrdui.style.display = "none";

If you are using AD FS version 3, copy the following into the onload.js file and save.

Replace {VIDMURL} with your VMware Identity Manager tenant URL.

Replace {ADFS Domain} with the domain name of your AD FS server.

var myCheckHRD = document.getElementById('hrdArea');
if (myCheckHRD) 
{	
	
	// redirect mobile traffic to Workspace ONE
	if (navigator.userAgent.match(/iPad|iPhone|Android|Windows Phone/i) != null)
	{
		HRD.selection('https://{VIDMURL}/SAAS/API/1.0/GET/metadata/idp.xml');
	}
	// else authenticate with local AD claims provider
	else 
	{
		HRD.selection('http://{ADFS Domain}/adfs/services/trust');
	}
}
// hide HRD selector from user
	var hrdui = document.getElementById("bySelection");
	hrdui.style.display = "none";

The previous code creates a redirection to VMware Identity Manager based on the AuthN request user agent (for example, iPad, iphone, and so on).

Any traffic that does not match the user agents listed are authenticated with the local Active Directory (for example, Windows or Mac desktops).

 

7. Verify Active Directory Identifier

In some cases the identifier used for Active Directory in the previous step (AD Authority) might be different in some installations of AD FS. Run the following in PowerShell to verify:

Get-AdfsClaimsProviderTrust | Format-List -Property Name,Identifier

8. Create New AD FS Web Theme

Run the following command to create a new AD FS Web Theme:

New-AdfsWebTheme –Name VIDM –SourceName default

9. Import Updated JavaScript File

Run the following command to import the modified onload javascript into the ADFS Web Theme:

Set-AdfsWebTheme -TargetName VIDM -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\myscripts\script\onload.js"}

10. Activate New ADFS Web Theme

Run the following command to activate the new ADFS Web Theme:

Set-AdfsWebConfig -ActiveThemeName VIDM

Verifying AD FS Forwards Mobile Traffic to VMware Identity Manager

After completing your PowerShell configurations, complete the steps in this section to verify that they applied successfully.

1. Test Authentication from Non-Mobile Device

Test an SP-inititated authentication flow using one of the applications federated with ADFS, from a non-mobile device (user agent not specified in the ADFS web theme rule).

2. Test Authentication from Mobile Device

Test an SP-inititated authentication flow using one of the applications federated with ADFS, from a mobile device (user agent specified in the ADFS web theme rule).

Applying Web Theme Modification to Specific Relying Party

The previous steps can be modified to target a specific relying party trust (for example, Salesforce) within AD FS instead of affecting all AuthN requests.

After modifying and saving the onload.js file, continue with the following steps.

1. Create New ADFS Web Theme

Run the following command to create a new ADFS Web Theme:

New-AdfsWebTheme –Name rpVIDM –SourceName default

2. Import Updated JavaScript File

Run the following command to import the modified javascript into the relying party specific web theme:

Set-AdfsWebTheme -TargetName rpVIDM -AdditionalFileResource @{Uri='/adfs/portal/script/onload.js';path="c:\myscripts\script\onload.js"}

3. Set Relying Party Web Theme

Run the following command to set the relying party (for example, Salesforce) web theme:

Set-AdfsRelyingPartyWebTheme -TargetRelyingPartyName Salesforce -SourceWebThemeName rpVIDM

Summary and Additional Resources

Conclusion

This operational tutorial provided steps to configure VMware Identity Manager as a claims provider for AD FS. Procedures included configuring a claim rule for VMware Identity Manager claims provider, configuring AD FS application source, adding AD FS applications to the Workspace ONE catalog, and modifying AD FS to forward mobile traffic to VMware Identity Manager.

Terminology Used in This Tutorial

The following terms are used in this tutorial:

application store A user interface (UI) framework that provides access to a self-service catalog, public examples of which include the Apple App Store, the Google Play Store, and the Microsoft Store.
auto-enrollment Auto-enrollment simplifies the enrollment process by automatically enrolling registered devices following the Out-of-Box-Experience.
catalog A user interface (UI) that displays a personalized set of virtual desktops and applications to users and administrators. These resources are available to be launched upon selection.
cloud Asset of securely accessed, network-based services and applications. A cloud can also host data storage. Clouds can be private or public, as well as hybrid, which is both private and public.
device enrollment The process of installing the mobile device management agent on an authorized device. This allows access to VMware products with application stores, such as VMware Identity Manager.
identity provider (IdP) A mechanism used in a single-sign-on (SSO) framework to automatically give a user access to a resource based on their authentication to a different resource.
mobile device management
(MDM) agent		 Software installed on an authorized device to monitor, manage, and secure end-user access to enterprise resources.
one-touch login A mechanism that provides single sign-on (SSO) from an authorized device to enterprise resources.
service provider (SP)
 A host that offers resources, tools, and applications to users and devices.
virtual desktop The user interface of a virtual machine that is made available to an end user.
virtual machine A software-based computer, running an operating system or application environment, that is located in the data center and backed by the resources of a physical computer.

For more information, see the VMware Glossary.

Additional Resources

For more information about Workspace ONE, you can explore the following resources:

About the Authors

This tutorial was written by:

  • Camilo Lotero, Senior Solutions Engineer, End-User-Computing Identity & Access Management, VMware

Contributors to this tutorial include:

  • Joe Rainone, Consulting Architect, AMER End-User Computing, VMware
  • Sascha Warno, Staff Customer Success Architect, Customer Success, VMware
  • Steven D'Sa, Staff Sales Engineer, End-User Computing, VMware

Feedback

The purpose of this tutorial is to assist you. Your feedback is valuable. To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.

Appendix: Alternative Custom Claim Rules

Alternative Custom Claim Rules

This section lists some alternative custom claim rules that rely on the user's UserPrincipalName, if the domain\samAccountName values are not available in VMware Identity Manager.

1. Alternative Custom Claim Rule for UPN (1)

To use UPN instead of a domain\username value from VMware Identity Manager, you must add four different custom rules to the VMware Identity Manager claims provider in AD FS.

The first rule is used to query AD for the user's UPN and samAccountName values, and save them in temporary variables.

  1. Enter a friendly name for the first rule. For example, Query AD for UPN and samAccountName + Save into temp variables.
  2. Copy the following into the custom rule text box:
    c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] == "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"]=> add(store = "Active Directory", types = ("ssupn", "sswindowsaccountname"), query = "userPrincipalName={0};userPrincipalName,sAMAccountName;domain\dummy", param = c.Value); Note: This rule needs to be adjusted slightly. Replace domain\dummy to include your logon domain (for example, clotero\dummy).
  3. Click Finish.

2. Alternative Custom Claim Rule for UPN (2)

  1. Enter a friendly name. For example, Extract Domain out of Value.
  2. Copy the following into the custom rule text box:
    c:[Type == "ssupn"] => add(Type = "ssnewupn", Value = RegExReplace(c.Value, "^(.*?)@", ""));
  3. Click Finish.

3. Alternative Custom Claim Rule for UPN (3)

  1. Enter a friendly name. For example, Extract Logon Domain.
  2. Copy the following into the custom rule text box:
    c:[Type == "ssnewupn"] => add(Type = "ssnewupn2", Value = RegExReplace(c.Value, "\.(.*?)$", ""));
  3. Click Finish.

4. Alternative Custom Claim Rule for UPN (4)

  1. Enter a friendly name. For example, Issue windowsacountname claim.
  2. Copy the following into the custom rule text box:
    c1:[Type == "ssnewupn2"] && c2:[Type == "sswindowsaccountname"] => issue(Type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer = "AD Authority", Value = c1.Value + "\" + c2.Value, ValueType = c2.ValueType);
  3. Click Finish.
https://techzone.vmware.com/sites/all/themes/vmware