Enabling SAML 2.0 Authentication for Horizon with Unified Access Gateway and Okta

Overview

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

This tutorial covers the following:

Configuring the Okta Agent for Active Directory Synchronization
Configuring SAML Integration with Okta
Configuring Unified Access Gateway Integration with Okta
Configuring Horizon Integration with Okta for True SSO
Configuring Okta Bookmarks for Remote Desktops and Applications

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 Horizon is required.

Prerequisites

Before you begin, you must satisfy the following requirements:

Deploy a Horizon 8 (or later) Connection Server and configure it with at least one application and desktop pool.
Deploy latest Unified Access Gateway (minimum 3.10 or later) and configure the Horizon Edge service.
Install Horizon Client on a Windows 10+ or macOS client machine.
Obtain access to an Okta environment for this integration, access to Secure Web Authentication (SWA) feature in Okta is required. SWA is not enabled by default on Okta development environments.

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 Synchronization

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 a 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 into the same Active Directory used by Horizon.

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

Log in to the Okta administration console and switch to Classic UI.
Navigate to Directory > Directory Integrations.
Click Add Active Directory.
Review the installation requirements and click Set Up Active Directory.
Click Download Agent and click Allow.
Click the downloaded file to launch the installer.
Define the installation folder and click Install.
Enter the AD domain and click Next.
Select Create or use the OktaService account (recommended) and click Next.
Set the password for the Okta AD service account and click Next.
Click Next to bypass proxy configuration. If your environment requires an outbound connection via proxy, select the Use proxy server option and enter the details.
Select the type of Okta environment 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.
Click Allow Access and click Finish.
Enter your username and password to log in to Okta.
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.

Configure basic settings:
1. Select the Organization Units (OUs) that you want to sync Users from.
2. Select the Organization Units (OUs) that you want to sync Groups from.
3. Select User Principal Name (UPN) for the Okta username format.
4. Click Next.
A successful AD configuration allows the import of AD users and groups. Click Next.
Select the attributes that you want for the Okta user profile and click Next.
At this point, your domain is integrated with 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.

Select the Import tab.
Click Import Now.
Select Incremental Report and click Import.
Monitor the import process. The initial import time will depend on the number of users and groups to be synchronized.
After the import completes, you can confirm how many users and groups were synchronized.
Click OK.

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

Configuring SAML Integration with Okta

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.

In the Okta console, navigate to Applications > Add Applications.
Click Create New App.
Configure the new application integration:
1. Select Web for Platform.
2. Select SAML 2.0 for Sign on method.
3. Click Create.
Configure the General Settings:
1. Enter the app name, for example, Horizon.
2. Define an app logo – this is optional.
3. Click Next.
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. Select the check box Use this for Recipient URL and Destination URL.
3. Enter https://<UAG-FQDN>/portal for Audience URI (SP Entity ID).
4. Scroll down and click Next.
Complete General Settings.
1. Select an option for Are you a customer or partner? Based on your selection, you might need to answer additional questions. Your selection will not affect the configuration of your SAML application.
2. Click Finish.
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.
Assign Groups and Users.
1. Select Assignments.
2. Click Assign > Assign to Groups.
Select a Group.
1. Enter Domain Users in the search bar.
2. Click Assign for Domain Users on the filtered list. The button label will update to Assign.
3. Click Done.
Return to Application List.
Users who 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.
1. Click Back to Applications.
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 Horizon

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 to Unified Access Gateway to enable trust between both.

Locate Identity Bridging Settings.
1. Under Advanced Settings, click the gear next to Upload Identity Provider Metadata.
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 and then 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 and passthrough as the authentication method for Horizon edge service.

Access Horizon 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.
Access Authentication Methods Configuration.
1. Click More at the end of the Horizon settings.
Configure SAML as the Authentication Method.
1. Select SAML and Passthrough 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 and 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 and 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, the user is redirected 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.

Configure Horizon Client.
1. Launch Horizon Client.
2. Click Add Server.
3. Enter the Unified Acces Gateway or load balancer IP or FQDN. For example, uaghzn.vmweuc.com.
4. Click Connect.
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 Okta credentials and click Sign In.
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 Blast (default) is selected.
3. Click Launch.
Enter AD Credentials (Passthrough)
As a result of the SAML and Passthrough configuration on Horizon Edge Service, the passthrough configuration results in prompting the user to enter their AD credentials to log in to the desktop (or application).
1. Enter your AD credentials and click Login.
Confirm the Virtual Desktop or Application has launched.

As previously mentioned, you are prompted to enter your AD credentials to log in to the desktop if you configured the Horizon edge service authentication method as SAML and passthrough on Unified Access Gateway. However, if you configured it as SAML and your environment has True SSO enabled, the desktop login uses SSO.
1. Confirm that you have successfully launched the virtual resource.
2. Click Options and then click Disconnect and Log Off.

Configuring Horizon Integration with Okta for True SSO

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

When Unified Access Gateway is set up 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 SSO experience, otherwise, the end-user will have to enter their AD credentials when logging in to the desktop or application. A SAML authenticator contains the IdP trust and metadata exchange between Horizon 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: In case end-users authenticate directly against 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 a third-party IdP, users must connect through the Unified Access Gateway.

Log in to Horizon Administration Console.
1. Navigate to https://server/admin on your Web browser where server is the host name of the Connection Server instance.
2. Enter the username, password, and domain, then click Sign in.
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.
Configure SAML Authentication Settings.
1. Select Authentication.
2. Select Allowed for Delegation of authentication to Horizon (SAML 2.0 Authenticator).
3. Click Manage SAML Authenticators.
Add SAML Authenticator – click Add.
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. Select the check box Enabled for Connection Server.
5. Click OK.
Confirm the SAML Authenticator is enabled and click OK.
Enable True SSO for Third-party SAML Authenticator.
If your environment leverages Horizon True SSO, you must enable the Okta SAML Authenticator for 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. To provide an end-to-end SSO experience for the end-user, you must set SAML as the authentication method for the Horizon service on Unified Access Gateway.

Access Horizon settings in 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.
Click the More button to access the authentication methods configuration.
Configure SAML as the 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 and click Save.

Validating Desktop and Application through SAML and True SSO Authentication

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

Launch Horizon Client and click your Unified Access Gateway connection which was registered in a previous exercise.
Authenticate through Okta.
The 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
1. Enter your username and password, and click Sign in.
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 one of your Desktop or Applications icons to launch the resource.
Confirm the virtual desktop or application has launched.

As a result of the SAML Authenticator and True SSO configuration in Horizon, SSO logged the user automatically.
1. Confirm that you have successfully launched the virtual resource.
2. Click Options then click Disconnect and Log Off.

Configuring Okta Bookmarks for Remote Desktops and Applications

Organizations using Okta as their primary IdP most likely leverage the 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

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

In Okta, click Applications > Add Application.
Search for the Bookmark template.
1. Enter bookmark in the search box.
2. Click Add for the Bookmark app.
Configure the 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 horizon-view URIs.
Assign Groups and Users.
1. On the Assignments tab, click Assign > Assign to Groups.
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 update to Assigned.
3. Click Done.
Add a 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.

Log in to the Okta portal.
Launch apps.
A successful login will present all the applications assigned to your account.

If you have followed the steps in this tutorial, you should see:
1. 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.
2. Notepad — Refers to the Notepad application pool, which will launch a new Notepad session.
3. Windows Desktop — Refers to the Win10-1803 desktop pool, which will launch a new Desktop session.
4. Select an application to launch.
Confirm the virtual desktop or application has been launched.
1. To exit, click Options and then click Disconnect and Log Off.

Summary and Additional Resources

This operational tutorial provided steps to integrate a third-party SAML IdP (Okta) with 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 and 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 Unified Access Gateway product page on Tech Zone.

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

Changelog

The following updates were made to this guide:

Date	Description of Changes
2024/10/30	Updated links and references to the latest documentation.
2019/12/10	Guide was published.

About the Author and Contributors

This tutorial was written by:

Andreano Lanusse, Staff Architect, Technical Marketing, Omnissa.

Feedback

Your feedback is valuable.

To comment on this paper, either use the feedback button or contact us at tech_content_feedback@omnissa.com.