Workspace ONE Access On-Premises to Cloud Migration

On-Premises to Cloud Migration Overview

We created this guide to help you understand what it takes to move Workspace ONE Access from on-premises to the cloud. The steps also apply if you move from one cloud tenant to another. This guide helps you understand typical migration efforts and describes the necessary steps to plan and execute the migration. The primary goal of migrating to the cloud is to simplify and reduce the on-premises infrastructure footprint, thereby reducing the ongoing maintenance and added cost around the Workspace ONE Access services.

Moving Workspace ONE Access from on-premises to Workspace ONE Access Cloud environment helps you to

  • Reduce high maintenance costs
  • Reduce IT (Information Technology) administration overheads
  • Increase consistency and reliability of the Workspace ONE Access services
  • Offer support for HA (High Availability) and scalability as the business grows
  • Reduce OpEx/CapEx because of lower infrastructure costs
  • Deliver in the cloud which is backed by a 99.9% uptime SLA (Service Level Agreement)


This tutorial is intended for IT professionals and VMware Workspace ONE administrators of existing production environments. Familiarity with Horizon, Active Directory, identity management, and directory services is assumed.

What is Workspace ONE Access as-a-service?

Workspace ONE Access as-a-service is a hosted (Cloud) environment that is a deployment choice that VMware offers for its customers.

  1. Workspace ONE Access as-a-service addresses use cases around user and device authentication, SSO, and conditional access across several types of apps (for example applications could be either Web or SAML) across the globe.
  2. Workspace ONE Access as-a-service is hosted on Amazon Web Services (AWS) in 7 locations around the world.
    1. US, Japan, Canada, Australia, Ireland, UK, and Germany.
    2. FedRAMP in the US.
  3. Depending on enterprise customer deployment and usage needs and the license purchased a Workspace ONE Access Cloud tenant will be provisioned for the customer in the right domain. (Note - Working with the respective account team, GSS (Global Support Services), or PSO (Professional Service Organization) to pre-determine the name of the customer’s Workspace ONE Access tenant.
    1. For US tenants are created under the domain.
    2. For GovCloud (US) US tenants are created under the, or domain.
    3. For EU at domain.
    4. For UK at domain.
    5. For Japan at domain.
    6. For Australia at domain.
    7. For Canada domain.
    8. For Germany at domain.
  4. Unlike the on-premises environment, Workspace ONE Access as-a-service only needs outbound connectivity from the connector to communicate with the cloud services. Hence minimal network ports are open for maximum network security.
    1. Requests to port 80 by a Workspace ONE Access hosted tenant, redirects on to port 443.
    2. 443 is not the only port used by the Cloud tenant. However, Kerberos authentication uses port 88 UDP. TCP and Android cert proxy use 5262.
  5. All user interactions in the Workspace ONE Access as-a-service environment get audited for compliance reasons.
    1. Customers have access to the audit logs which are kept for 90 days.
  1. Workspace ONE Access as-a-service offers support for user authentication using corporate account globally.
    1. Even though Workspace ONE Access is hosted, the connector for the directory server which is the user store is deployed on-premises. The Workspace ONE Access from different geo locations can communicate with the same instance of the directory server and cater to the needs of the users globally if needed.
    2. Allows the user data to stay on-premises with only the required user attributes to be synchronized to the cloud. This allows operating in a hybrid model to keep the company data secure thereby keeping the maintenance and infrastructure costs low.
    3. Supports business continuity for end users to continue support for non-password-based authentication methods even if the on-premises connector(s) or the directory server is down (for example, certification-based authentication is a non-password based that does not depend on directory server/user store connectivity).
  2. Workspace ONE Access as-a-service offers high availability and elasticity for all tenants at all times.
    1. Offers Reliability, performance, and operational simplicity for Workspace ONE Access delivered in the cloud is backed by a 99.9% uptime SLA which is defined in the Service Level Agreement for Workspace ONE Access.
    2. Supports HA (High Availability) and scalability as the tenant user base grows and new user scenarios can be easily enabled for each tenant individually.
  3. Workspace ONE Access as-a-service provides tenants with a quick time-to-market turnaround for new features and capabilities.

Planning the Migration

In this section, we go through the recommended migration on a high level and then lay out the steps commonly done by customers during migrations. Some of the steps are dependent on the use cases you leveraged Workspace ONE Access for and will be marked as optional.

Requirements for the migration

Before you can continue, you must have the following components installed and configured:

  • An existing Workspace ONE Access environment (On-Premises)

Migration outline

The general idea for the migration is to set up the new cloud-hosted Access environment in addition to the existing Access environment, configure the basic settings, connect both tenants with the help of a Security Assertion Markup Language (SAML) federation, link resources from the old environment in the new cloud tenant, and then start moving those resources to the new cloud tenant to minimize downtime on the services offering. Depending on your use cases, sections of the migration path may differ. For a Workspace ONE UEM customer, it will be necessary to migrate the Access and Hub Services integration. In the UEM environment, it might be important for a Horizon Universal Broker customer to relink Access in the Horizon cloud to Workspace ONE integration.

Migration steps

Step 1: Assessment

Migration of Workspace ONE Access from on-premises to the hosted (Cloud) environment involves rebuilding and reconfiguring the directory integrations, connectors, apps, and more. Hence a solid understanding of the existing on-premises environment is a good starting point.

The following table goes through an extensive but potentially not complete list of configurations to assess and document.



Directories configurations

Identify the structure and setup of user directories, including LDAP, Active Directory, etc.

Find the structure and setup of user directories, including LDAP, Active Directory

  • Server names
  • FQDN
  • Bind User DN & Bind User Password
  • SSL (Secure Sockets Layer) settings
  • For LDAP, also collect user and group search queries
  • Check sync settings for synced domains, users, and groups
  • User attribute settings

Connector settings

Understand the configuration settings for connectors connecting to AD (Active Directory), LDAP, or authentication methods

Understand the configuration settings for connectors connecting to AD (Active Directory), LDAP, or authentication methods

  • Server names
  • Which Directories they are associated with?
  • Which authentication methods are configured?
  • Are Virtual Desktops synchronized?
  • Are ThinApps synchronized?

Authentication Methods

Note down the authentication methods in use

Which authentication methods are enabled?

Mobile SSO/Certificate authentication

  • collect root CA (Certificate Authority) configured
  • revocation check settings

Network Ranges

Document network range configurations

Hosted Access cannot use internal ranges anymore, you can only configure egress IP addresses to differentiate all internal from internet traffic

Identity Provider settings

Review identity provider configurations integrated with Workspace ONE Access.

3rd party IdPs (identity provider)

  • Metadata used
  • NameID mapping
  • authentication Method
  • is JIT (Just In Time) configured

Built In IdPs

  • What directory is associated?
  • Which methods are enabled?
  • Are network ranges configured?

Access Policies

Review and document the existing access policies

Default access policy

Collect the rules and order

Resource specific policies

Collect the rules and order


Collect the roles applied to Administrators and Users

Collect any custom roles and applied settings

Login preferences

Document the login preferences settings

Domain visibility and drop-down

Unique Sign-in Identifier

iFrame render settings


Note any branding customizations done in the current environment

Logo and Color schema for sign-in screens

Hub Services

Review configurations related to Workspace ONE Hub services

  • Branding for catalog
  • Catalog settings
  • People Search
  • Notifications

Web app resources

Document all web app resources integrated into Workspace ONE Access

Workspace ONE Access Launch URLs for first step of migration

Configured App Sources

Virtual Desktop resources

Collect the currently configured Horizon Pods, Citrix, or Thin Apps

OAuth 2.0 Clients

Identify any OAuth 2.0 clients and their configurations

Service clients or OAuth Templates

Step 2: Set up a new cloud environment to run in parallel

Work with your account representative to get a new cloud-hosted Workspace ONE Access tenant. We will provide either direct administrator login credentials or provide access through the Workspace ONE Admin hub. Cloud-hosted access only allows you to customize the first part of the URL, e.g., and for any vanity URLs you can only use 302 redirects to the respective tenant URL. More information on customizing the tenant URL can be found in How Do You Change Your Workspace ONE Access URL? on VMware Docs.

Directory and Connector setup

With the information collected in Step 1, you can start with the basic configuration of the tenant. Start by adding your identity source to add administrators and admins to the tenant. To add a directory, you first need to install a connector that allows the cloud tenant to communicate with your Active Directory or LDAP.

Check the network requirements for the connector to communicate with the hosted environment:

Create the configuration for the connector in the Access admin console and download the connector installer from the customer connect portal. Then install the connector with all the services that would be required later besides the user sync and user authentication.

With the connector in place follow the documentation on integrating with your on-premises directory using the information you gathered in Step 1.

You can start with a test group and later configure all the users that should be migrated.

Authentication Methods

Setting up the authentication methods collected in Step 1 is similar to the way they were set up on-premises. There are new methods available now that were only introduced for cloud-hosted Access. The suggestion is to migrate the existing configurations and then use the documentation to become familiar with the now available methods like FIDO2, Hub Verify, or Risk Scoring for later implementation. Setting up methods like Mobile SSO might require configurations in Workspace ONE UEM as well.

Network Ranges

With the authentication methods required in place a good next step is to create the network ranges to be used in IdPs (identity provider) and access policies. As mentioned in Step 1, we cannot use internal network ranges in the cloud-hosted Access environment. You need to use the egress IP address(es) from your network edges to differentiate internal traffic from normal internet traffic. Add them as documented in the following:

Identity Provider settings

Check the built-in IdP (identity provider) created for the directory you configured and enable all configured authentication methods you want to use as well as all network ranges.

If you had 3rd party IdPs configured, configure them again by adding the metadata from the discovery phase or set the new tenant up as a new SP (Service Provider) in your IdP.

Access Policies

With the methods and IdPs in place, you can now configure and create the access policies to control access to the intelligent hub portal and resources. Leverage the information from Step 1 and potentially review the settings against the documentation and FAQ (Frequently Asked Questions) linked below. Using step up authentication like Device Compliance requires the integration with UEM and will be configured in a later step.

Login Preferences

Control the experience for users while logging in to the Intelligent Hub portal and manage the use of unique sign-in identifiers or domain drop downs. Set it up with the collected information based on the documentation.


Finally, use the branding information documented before to customize the look and feel of the tenant.

For console and sign-in screens, see the following:

For the Intelligent Hub portal check out the Hub branding guide:

Configure Resources that support multiple IdPs

For web applications or application sources that support multiple IdPs, you can now configure the integration by configuring based on the documentation. Consult with your application owner if you can use the same SP settings collected in Step 1 or if you need to create new SP metadata.

Entitle the test user group to the added resources.


With the general setup in place test the login for the test end user group. Can users sign in correctly to the tenant and have access to the portal and, if configured, resources?

Step 3: Set up trust between the old and new environment

Trust through SAML (Security Assertion Markup Language) Federation

To ease the migration, we will set up a federation between the new tenant and the existing on-premises environment which allows us to start resources after authenticating to the new tenant.

3rd Party IdP (identity provider) - old environment

Copy the IdP metadata URL from the cloud-hosted Access tenant by going to Resources > Web Apps > Settings > SAML Metadata menu and use it to configure a 3rd party IdP in the existing on-premises environment. NameID format should be a unique identifier like UPN (User Principal Name) and match against the same NameID value.

In the Users section use the configured directory and all network ranges. Finally, the authentication method the new tenant will return is passwordprotected. More details on the configurations of the 3rd party IdP can be found here.

After saving the configuration you can download the Service Provider (SP) metadata from the bottom of the IdP configuration.

Access policies - old environment

In the old environment, you now need to add the 3rd party IdP authentication method as a viable authentication option in the access policies. Configure an Any or Web Browser rule after the existing rules allowing user access with the IdP authentication method.

Application source – new tenant

With the SP metadata, configure the old environment as an Application Source inside the new cloud-hosted tenant. Pick one of the 3 optional 3rd party sources that are not yet in use and configure it with the SP metadata of the old environment and the matching nameID configuration.

Add applications

With the information from Step 1 on the application launch URLs you can now create applications from the application source with the Launch URL added as Target URL. This can include web applications and VDIs (Virtual Desktop Infrastructure). Entitle the test users for the application source app.

Test accessing resources

Again, let test users log in to the Intelligent Hub portal and access the newly configured resources.

Step 4: Migrate Users

After successful testing, synchronize the rest of the users.

Step 5: Migrate settings in Workspace ONE UEM (Unified Endpoint Management)

Integration with Workspace ONE UEM

The next step will have an impact on all users with enrolled devices and Intelligent Hub. We need to reconfigure the existing Access integration in UEM from pointing to the old environment to the new cloud-hosted tenant. Follow the documentation:

Also, check the Hub Services integration it needs to point to the same Access tenant as the service is co-hosted there. Follow the guidance listed:

Devices enrolled will need to reauthenticate against the new tenant, setting up Mobile SSO or certificate authentication can help to make the process transparent for the user.

Step 6: Migrate Web apps and VDIs (Virtual Desktop Infrastructure)

Web Apps

For Web applications that did not support multiple IdPs, we now need to work with the application owner and move the federation to the new tenant. For each app create a web application on the new tenant with the SP metadata collected in Step 1. Then provide the IdP metadata of the cloud-hosted tenant to the application owner and plan a switch of the IdP in the application during a maintenance window. Test the federation and if successful, entitle all required users on the app and remove the entitlement from the app source version of the application pointing to the on-premises tenant.

Go through all remaining applications in the same manner.

For the Access part of the web app configuration, you can potentially leverage the Workspace ONE Access Migration Tool Fling that allows for the bulk export and import of web app settings. You can download it on Tech Zone: Workspace ONE Access Migration Tool.

You will still need to configure the Service Provider side separately.

Virtual Apps Horizon/Citrix

Go through the setup of VDIs (Virtual Desktop Infrastructure) collections in Access and change the configuration on the Horizon CS (Connection Server) side.

Step 7: Decommission On-Premises Access

After all use cases are moved to the new tenant create a redirect to the new tenant in DNS (Domain Name System) and decommission the old tenant.

Summary and Additional Resources

This short guide provided an overview of the typical steps involved in moving Access tenants, be it from on-premises or an old cloud-hosted tenant to a new tenant. The steps required may vary and it is a good idea to involve PSO or partners to guide you through the process. 


The following updates were made to this guide:


Description of Changes

  • Guide was published.

About the Author

This document was written by:

  •  Sascha Warno, Staff Architect Identity & Security Solutions, EUC (End User Computing) Technical Marketing, VMware


Your feedback is valuable.

To comment on this paper, contact VMware End-User-Computing Technical Marketing at


Filter Tags

Workspace ONE Workspace ONE Access Document Operational Tutorial Intermediate Migrate