Solution

  • Horizon

Type

  • Document

Level

  • Intermediate

Category

  • Operational Tutorial

Product

  • Horizon 7
  • Unified Access Gateway

Phase

  • Manage

Enabling SAML 2.0 Authentication for Horizon with Unified Access Gateway and Okta: VMware Horizon Operational Tutorial

VMware Unified Access Gateway 3.8 and later VMware Horizon 7.11 and later

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Horizon® environment. This tutorial walks through configuring a third-party SAML identity provider (IdP) integration with VMware Unified Access Gateway™ to access Horizon virtual desktops and applications.

This tutorial covers the following:

This tutorial uses Okta as a third-party IdP. You can integrate other IdPs if they provide SAML 2.0 integration.

The steps are sequential and build upon one another, so make sure that you complete each step before going to the next step.

Audience

This operational tutorial is intended for IT professionals and Horizon administrators of existing production environments. Both current and new administrators can benefit from using this tutorial. Familiarity with networking and storage in a virtual environment is assumed, including Active Directory and Identity solutions. Knowledge of additional technologies such as VMware Horizon is required.

Prerequisites

Before you begin, you must satisfy the following requirements:

  • Deploy a Horizon 7.11 (or later) Connection Server and configure it with at least one application and desktop pool.
  • Optional: True SSO configured for Horizon - more details on how to set up True SSO here.
  • Deploy Unified Access Gateway 3.8 and configure the Horizon edge service.
  • Install Horizon Client on a Windows 10 or macOS client machine.
  • Obtain access to an Okta environment to be used for this integration. You can create an Okta development environment here.

These exercises are sequential and build upon one another, so make sure to complete each exercise before moving on to the next.

Configuring the Okta Agent for Active Directory Syncronization

Introduction

By default, Horizon authenticates users against Microsoft Active Directory. With Unified Access Gateway 3.8, administrators can now leverage SAML 2.0 to authenticate Horizon users against third-party identity provider (IdP).

When using third-party IdP administrators can synchronize their organization's Microsoft Active Directory with the IdP directory, or leverage the native IdP directory. Integration with Microsoft Active Directory is the most common use case. In this section, you learn how to deploy and configure the Okta AD Agent to integrate with your Microsoft Active Directory.

Installing the Okta Agent

To integrate Okta with Unified Access Gateway, you must deploy the Okta agent on a Windows Server located in your internal network with access to the internal Active Directory, and allow outbound connections from that server to the Okta service in the cloud.

The Okta agent will be integrated to the same Active Directory used by Horizon.

In this exercise, you install the Okta agent in your on-premises environment.

1. Log In to Okta Administration Console

Access the Okta administration console and switch to Classic UI.

2. Navigate to Directory Integrations

  1. Click Directory.
  2. Click Directory Integrations.

3. Add Active Directory

Click Add Active Directory.

4. Review Requirements and Begin Active Directory Setup

Review the installation requirements and click Set Up Active Directory.

5. Download the Okta AD Agent

  1. Click Download Agent.
  2. Click Allow.

6. Launch the Okta AD Agent installer

Click the downloaded file to launch the OktaADAgent installer.

7. Define the Installation Folder

  1. Click Next.
  2. Confirm the installation folder.
  3. Click Install.

8. Define the AD Domain to be Managed by Okta

  1. Enter the Domain.
  2. Click Next.

9. Define the Service Account to Run Okta AD Agent

  1. Select Create or use the OktaService account (recommended).
  2. Click Next.

10. Set the Password for Okta AD Windows Service Account

  1. Enter the password.
  2. Retype the password.

11. Bypass Proxy Configuration

If your environment requires an outbound connection via proxy, select the Use proxy server option and provide the details.

For this exercise, Proxy is not required.

Click Next.

12. Register the Okta AD Agent

Select the type of Okta environment that to be integrated with the Okta AD Agent.

  1. Select Production.
  2. Enter the Subdomain. If you are using an Okta development environment, enter https://dev-XXXXXX.okta.com, where XXXXXX is your respective environment.
  3. Click Next.

13. Grant Permission to Okta AD Agent

  1. Click Allow Access.
  2. Click Finish.

14. Sign In to Okta

  1. Enter the Username.
  2. Enter the Password.
  3. Click Sign In.

15. Confirm Agent Installation

You should see a dialog box confirming the Agent Installation.

Click Next to continue.

Configuring Basic and User Profile Settings

Before you can sync users, you must integrate Okta with your AD. Steps in this exercise include connecting Okta with an OU to sync Users and Groups and defining the Okta username.

1. Configure Basic Settings

 

  1. Select the Organization Unites (OUs) that you want to sync Users from.
  2. Select the Organization Unites (OUs) that you want to sync Groups from.
  3. Select User Principal Name (UPN) for the Okta username format.
  4. Click Next.

2. Confirm the AD Agent Configuration

A successful AD configuration allows the import of AD users and groups.

Click Next.

3. Configure Okta User Profile

  1. Select the attributes that you want to use for the Okta User profile.
  2. Click Next.

4. Confirm the Agent Setup has Completed

At this point, your AD domain is integrated with Okta. The next step is to sync your AD users to Okta.

Click Done.

Importing Users into Okta

Now that Active Directory and the Okta Agent are integrated, you can import AD users and configure how often the sync will happen.

2. Begin the Import Process

Click Import Now.

3. Define the Import Method

Define the import method you would like to use.

  1. Select Incremental Import.
  2. Click Import.

4. Monitor the Import Process

The initial import time will depend on the number of users and groups to be synchronized.

5. Confirm the Imported Users

After the import completes, you can confirm how many users and groups were synchronized.

Click OK.

The integration is now complete. Okta can now synchronize with the organization's AD, and enable Horizon users to authenticate through SAML.

Configuring SAML Integration with Okta

Introduction

Identity provider metadata is required to enable the integration between Okta and Unified Access Gateway, which enables the flow of communication between the service provider (SP) and IdP during the authentication process.

When integrating the Unified Access Gateway with Okta, the IdP metadata is defined based on the creation of SAML 2.0 applications.

In this section, you learn how to configure the SAML application to obtain the IdP metadata to be used in the Unified Access Gateway.

Configuring SAML 2.0 Application

In this exercise, you create and configure a SAML 2.0 application in Okta to enable Single sign-on (SSO) with Unified Access Gateway.

1. Add New Application

  1. Click Applications.
  2. Click Add Application.

2. Create a New Application Integration

Click Create New App.

3. Configure the New Application Integration

  1. Select Web as Platform.
  2. Select SAML 2.0 for the Sign on method.
  3. Click Create.

4. Configure General Settings

  1. Enter Horizon as the App name.
  2. Define an App logo if you want—this is optional.
  3. Click Next.

5. Configure SAML Settings

Replace  <UAG-FQDN> from the following parameters with the respective FQDN from your environment. This example uses uaghzn.

  1. Enter https://<UAG-FQDN>/portal/samlsso for Single sign on URL.
  2. Ensure Use this for Recipient URL and Destination URL is selected.
  3. Enter https://<UAG-FQDN>/portal for Audience URI (SP Entity ID).
  4. Scroll down and click Next.

Keep the default values in the remaining text boxes.

6. Complete General Settings

Your selection on the feedback screen will not affect the configuration of your SAML application.

  1. Select an option for Are you a customer or partner? question. Depending on the answer, you may need to answer additional questions.
  2. Click Finish.

7. Download Identity Provider Metadata

After you configure the General settings, you are redirected to the Sign On page, which allows you to download the Identity Provider metadata. This metadata will be uploaded to Unified Access Gateway and Horizon Connection Server in a later exercise.

  1. Right-click Identity Provider metadata.
  2. Click Download Linked File As...
  3. Update the file name adding .xml as the file extension. The original file name does not include the file extension.
  4. Click Save.

8. Assign Groups and Users

  1. Click Assignments.
  2. Click Assign.
  3. Click Assign to Groups.

9. Selecting a Group

  1. Enter Domain Users in the search bar.
  2. Click Assign for Domain Users on the filtered list. The button label will be updated to Assigned.
  3. Click Done.

10. Return to Application List

Users that are part of the Domain Users group can now launch the Horizon SAML application. However, additional configuration is required and this is covered in the next exercises.

Click Back to Applications.

11. Confirm Horizon SAML 2.0 Application is Active

This concludes the configuration of the SAML 2.0 application, where the Horizon SAML 2.0 application is now listed as active on the Okta application list. The configuration for this app can be updated at any time by clicking the gear next to the application name.

Configuring Unified Access Gateway Integration with Okta

Introduction

On Unified Access Gateway, you must enforce SAML authentication and upload third-party metadata to enable third-party SAML 2.0 authentication when launching remote desktops and applications.

In this section, you learn how to upload the IdP metadata and configure Horizon edge service for SAML authentication using the Unified Access Gateway administration console.

Uploading Okta Metadata to Unified Access Gateway

In this exercise, you upload the Okta metadata on Unified Access Gateway to enable trust between the both.

1. Locate Identity Bridging Settings

Under Advanced Settings on Unified Access Gateway:

1. Click the gear next to Upload Identity Provider Metadata.

2. Upload Okta Metadata

Keep Entity ID empty, as this value will be defined based on the metadata XML file.

  1. Click Select for IDP Metadata.
  2. Select the Okta XML metadata file previously downloaded from Okta.
  3. Click Open.
  4. Click Save.

Configuring Horizon Edge Service for SAML and passthrough authentication

In this exercise, you configure SAML and passthrough as the authentication method for the Horizon service on Unified Access Gateway.

Also you will understand the difference when using SAML and SAML + passthrough as the authentication method for Horizon edge service.

1. Access Horizon Settings

Acessing Reverse Proxy Settings
  1. Click the Show toggle next to Edge Service Settings. After you click, it switches to display the Hide option.
  2. Click the gear icon next to Horizon Settings.

All items should be GREEN, representing that the appliance can communicate with the Horizon Connection Server through the multiple protocols configured. Items not fully functional are presented in RED.

2. Access Authentication Methods Configuration

Click More at the bottom of the Horizon settings.

3. Configure SAML as Authentication Method

  1. Select SAML and Passthrough.
  2. Select http://www.okta.com for Identity Provider.  http://www.okta.com is the name of the Entity ID specified in the Okta metadata.
  3. Scroll down.
  4. Click Save.

When Auth Methods is set to SAML, SAML assertion is validated by Unified Access Gateway and passed to the backend. User single sign-on leveraging True SSO to the remote desktops and applications.

When Auth Methods is set to SAML + passthrough, SAML assertion is validated by Unified Access Gateway and Connection Server authenticates the user against Active Directory when launching remote desktops and applications.

In both authentication methods user will be redirect to Okta for SAML authentication, service provider (SP) and IdP initiated flows are supported.

Validating Horizon Client Connection to a Remote Desktop and Application

In this exercise, you configure the Horizon Client to launch remote desktops and applications through Unified Access Gateway, and validate the SAML and passthrough authentication flow.

1. Configure Horizon Client

Horizon Client
  1. Launch Horizon Client.
  2. Click Add Server.
  3. Enter the Unified Access Gateway or load balancer IP or FQDN.
  4. Click Connect.

2. Authenticate through Okta

User is redirected to Okta for authentication (XML-API Protocol), and after successful authentication, the user is redirected back to the Horizon client with a valid token.

This step is related to the SAML part of the SAML and passthrough authentication configured on Horizon edge service.

  1. Enter the Username.
  2. Enter the Password.
  3. Click Sign In.

3. Launch a Virtual Desktop or Application (Secondary Protocol)

A successful connection will present the desktops and applications entitled to logged-in users. In this exercise, you can see one virtual desktop (Win10 1803) and four other virtual applications (Calculator, Notepad, Paint, WordPad).

  1. Right-click the desktop or one of the applications.
  2. Ensure that VMware Blast (default) is selected.
  3. Click Launch.

4. Entering AD credentials (passthrough)

As result of the SAML and passthrough configuration on Horizon edge service, the passthrough configuration results in prompt the user to enter his AD credentials to log in into the desktop or application.

  1. Enter your AD user name.
  2. Enter your AD password.
  3. Click Login.

5. Confirm the Virtual Desktop or Application has been Launched

As previously mentioned, you are prompted to enter your AD credentials to log in to the desktop if on Unified Access Gateway, you configure the Horizon edge service authentication method as SAML and passthrough. However, if you configure as SAML and your environment has True SSO enabled, the desktop login uses single sign-on (SSO).

Confirm that you have successfully launched the virtual resource.

  1. Click Options.
  2. Click Disconnect and Log Off.

Configuring Horizon Integration with Okta for True SSO

Introduction

To provide an end-to-end single sign on experience to the end-user you must configure True SSO on your Horizon environment. When True SSO is enable users are not required to also enter Active Directory credentials in order to use a remote desktop or applications.

When Unified Access Gateway is setup to use third-party IdP and True SSO is enabled on Horizon, you must create a SAML authenticator into the Horizon administration console to provide the same end-to-end single sign on experience, otherwise the end-user will have to enter their AD credentials when log in to the desktop or application. A SAML authenticator contains the IdP trust and metadata exchange between Horizon 7 and the device to which clients connect.

You associate a SAML authenticator with a Connection Server instance. If your deployment includes more than one Connection Server instance, you must configure the SAML authenticator with each instance.

In this section, you learn how to create a SAML authenticator for Okta on the Horizon administration console, and enable True SSO for the Okta SAML authenticator created.

If your use case DOES NOT require True SSO, there is no need to configure the SAML authenticator on Horizon and you can skip this section.

Configuring the SAML Authenticator for True SSO

In this exercise, you configure Okta as the SAML authenticator for Horizon.

Important to remainder that in case end-users authenticate directly against to the Connection Server, they will be required to provide their Active Directory credentials even if the SAML authenticator is configured. In order to authenticate against athird-party IdP, users must connect through the Unified Access Gateway.

1. Log In to Horizon Administration Console

To access the Horizon administration console, navigate to https://server/admin on your Web browser, where server is the host name of the Connection Server instance.

  1. Enter the user name.
  2. Enter the password.
  3. Enter the Domain.
  4. Click Sign in.

2. Configure Connection Server Settings

  1. Click Settings.
  2. Click Servers.
  3. Select Connection Servers.
  4. Select the Connection Server to be used as the front-end server for Unified Access Gateway deployed in this exercise.
  5. Click Edit.

3. Configure SAML Authentication Settings

  1. Select the Authentication tab.
  2. Select Allowed for Delegation of authentication to VMware Horizon (SAML 2.0 Authenticator).
  3. Click Manage SAML Authenticators.

4. Add SAML Authenticator

Click Add.

5. Configure SAML Authenticator for Okta

  1. Select Static for Type.
  2. Enter Okta for Label.
  3. Paste the content of the Okta metadata XML file you previously downloaded from Okta into the SAML Metadata text box.
  4. Make sure Enabled for Connection Server is selected.
  5. Click OK.

6. Confirm the SAML Authenticator is Enabled

  1. Confirm that Okta is now configured as a SAML authenticator for Horizon.
  2. Click OK.

Note: You can configure more than one SAML authenticator to a Connection Server and all the authenticators can be active simultaneously. However, the entity-ID of each SAML authenticator configured on the Connection Server must be different.

7. Enable True SSO for Third-party SAML Authenticator

If your environment leverages Horizon TrueSSO, you must enable the OKTA SAML Authenticator on True SSO.

Use the following command line to list all the authenticators and their True SSO mode status.

vdmutil --authAs <Horizon admin user> --authDomain <fqdn> --authPassword <Horizon admin password> --truesso --list --authenticator

Replace
<Horizon admin user> with the Horizon administrator user
<fqdn> with the fully qualified domain name for the Horizon admin user
<Horizon admin password> with the password for the Horizon administrator

If True SSO mode is DISABLED for the authenticator you are trying to configure, execute the following command line to enable.

vdmutil --authAs <Horizon admin user> --authDomain <fqdn> --authPassword <Horizon admin password> --truesso --authenticator --edit --name <SAML authenticator name> --truessoMode ENABLED

After you enable True SSO, the True SSO mode for the authenticator you are enabling displays as  ENABLE_IF_NO_PASSWORD.

Configuring Horizon Edge Service for SAML and True SSO authentication

This exercise assumes you already have True SSO setup on your Horizon environment, and in order to provide a end-to-end single sign-on experience to the end-user, you must set SAML as the authentication method for the Horizon service on Unified Access Gateway.

 

1. Access Horizon Settings

Acessing Reverse Proxy Settings

Log in to the Unified Access Gateway administration console.

  1. Click the Show toggle next to Edge Service Settings. After you click, it switches to display the Hide option.
  2. Click the gear icon next to Horizon Settings.

2. Access Authentication Methods Configuration

Click More at the bottom of the Horizon settings.

3. Configure SAML as Authentication Method

  1. Select SAML for Auth Methods.
  2. Select http://www.okta.com for Identity Provider.  http://www.okta.com is the name of the Entity ID specified in the Okta metadata.
  3. Scroll down.
  4. Click Save.

Validating Desktop and Application through SAML and True SSO authentication

In this exercise, you launch the Horizon Client to launch remote desktops and applications through Unified Access Gateway, and validate the SAML and True SSO authentication flow.

1. Launch Horizon Client

Horizon Client
  1. Launch Horizon Client.
  2. Double Click on your Unified Access Gateway connection, which was registered in one of the previous exercise.

2. Authenticate through Okta

User is redirected to Okta for authentication (XML-API Protocol), and after successful authentication, the user is redirected back to the Horizon client with a valid token.

This step is related to the SAML authentication configured on Horizon edge service.

  1. Enter the Username.
  2. Enter the Password.
  3. Click Sign In.

3. Launch a Virtual Desktop or Application (Secondary Protocol)

A successful connection will present the desktops and applications entitled to logged-in users. In this exercise, you can see one virtual desktop (Win10 1803) and four other virtual applications (Calculator, Notepad, Paint, WordPad).

  1. Double Click in one of your Desktop or Applications icons to launch the resource.

4. Confirm the Virtual Desktop or Application has been Launched

As result of the SAML Authenticator and True SSO configuration in Horizon, single sign-on kicked in and logged the user automatically.

Confirm that you have successfully launched the virtual resource.

  1. Click Options.
  2. Click Disconnect and Log Off.

Configuring Okta Bookmarks for Remote Desktops and Applications

Introduction

Organizations using Okta as their primary IdP most likely leverage Okta portal as the central catalog of applications for their end users.

In this section, you learn how to configure Okta bookmarks to launch Horizon virtual desktops and applications.

Configuring Okta Bookmarks to Launch Horizon Desktop and Applications

In this exercise, you configure an Okta bookmark to launch a Horizon desktop. You can repeat the same steps to create multiple bookmarks.

1. Add New Application

  1. Click Applications.
  2. Click Add Application.

2. Search for Bookmark Template

  1. Enter Bookmark in the search bar.
  2. Click Add for the Bookmark App.

3. Configure Bookmark App

  1. Enter Windows Desktop for Application Label.
  2. For URL add the URL to launch a desktop. For example, to launch a desktop from the Win10 1803 pool using the Native Client and BLAST protocol, use https://<UAG-hostname>/portal/nativeclient/Win10%201803?action=start-session&desktopProtocol=BLAST
  3. Click Done.

To learn more about the syntax and parameters that can be used as part of the URL, see Syntax for Creating vmware-view URIs.

4. Assign Groups and Users

  1. Make sure the Assignments tab is selected.
  2. Click Assign.
  3. Click Assign to Groups.

5. Select a Group

  1. Enter Domain Users in the search bar.
  2. Click Assign for Domain Users on the filtering list. The button label will be updated to Assigned.
  3. Click Done.

6. Add New Bookmark to Launch a Horizon Application

You can repeat the same steps from this exercise to configure a new bookmark, this time to launch a virtual application using the Horizon HTML5 client (Web Client).

For example, the URL syntax to launch Notepad from the Application Pool using an Okta bookmark would be:

https://<UAG-hostname>/portal/webclient/index.html?applicationName=Notepad

To launch a virtual desktop named Win10Desktop from the Desktop Pool using an Okta bookmark, the URL syntax is as follows:

https://<UAG-hostname>/portal/webclient/index.html?desktopName=Win10Desktop

Validating Desktop and Application Launch from Okta Portal

In this exercise, you log in to the Okta portal to validate the bookmark assignments and to launch remote desktops and applications through Unified Access Gateway.

1. Log In to the Okta Portal

  1. Enter a domain username.
  2. Enter the password.
  3. Click Sign In.

2. Launch Apps

A successful login will present all the applications assigned to your account.

If you follow all the steps from this tutorial, you should see:

  • Horizon — This is the SAML 2.0 application used to generate the IdP metadata. Launching this app redirects you to the Horizon HTML client. You can hide this app on the Okta administration console as previously explained.
  • Notepad — Refers to the Notepad application pool, which will launch a new Notepad session.
  • Windows Desktop — Refers to the Win10-1803 desktop pool, which will launch a new Desktop session.

Select an application to launch.

 

3. Confirm the Virtual Desktop or Application has been Launched

Confirm that you have successfully launched the virtual resource.

  1. Click Options.
  2. Click Disconnect and Log Off.

Summary and Additional Resources

Conclusion

This operational tutorial provided steps to integrate a third-party SAML IdP (Okta) with VMware Unified Access Gateway to access Horizon virtual desktops and applications.

Procedures included:

  • Configuring Okta agent for Active Directory synchronization
  • Configuring Okta SAML 2.0 integration with Unified Access Gateway
  • Configuring Unified Access Gateway integration with Okta through SAML
  • Configuring SAML and True SSO and SAML + passthrough for authentication
  • Configuring Okta bookmarks for remote desktops and applications

Appendix: Alternative Methods to Launch Horizon Desktops and Applications

Launching Horizon desktops and applications are not restricted to the third-party IdP portal. 

Administrators can also launch desktops and applications using:

  • The Horizon native client connected to Unified Access Gateway
  • The Horizon native and web client using bookmarks
  • Bookmarks on the Company custom portal. See the following URL examples to launch resources from the specific Horizon clients:
    • Using Horizon native client
      • https://<UAG hostname>/portal/nativeclient/index.html - to launch the native client with SSO
      • https://<UAG hostname>/portal/nativeclient/Notepad?action=start-session&desktopProtocol=BLAST&launchMinimized=false  - to launch the Notepad applications
    • Using Horizon Web Client
      • https://<UAG hostname>/portal/webclient/index.html  - to launch the web client with SSO
      • https://<UAG hostname>/portal/webclient/index.html?applicationName=Notepad  - to launch the Notepad app
      • https://<UAG hostname/portal/webclient/index.html?desktopName=Win10Desktop  - to launch the Win10Desktop

Additional Resources

For more information, explore the following Activity Paths on Digital Workspace Tech Zone. Activity paths provide step-by-step guidance to help you level-up in your product knowledge. You will find everything from beginner to advanced curated assets in the form of articles, videos, and labs.

Additionally, you can check out the VMware Workspace ONE and VMware Horizon Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using VMware Workspace ONE and VMware Horizon.

About the Author

This tutorial was written by:

  • Andreano Lanusse, End-User-Computing Staff Architect, Technical Marketing, VMware.

Feedback

Your feedback is valuable. 

To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.

Filter Tags

  • Horizon
  • Intermediate
  • Operational Tutorial
  • Document
  • Horizon 7
  • Unified Access Gateway
  • Manage