Planning your DSaaS Migration : API

Jun 29, 2022 11 min read
Planning your DSaaS Migration : API

Planning your Workspace one UEM and Workspace One Access migration from On-Premise to DSaaS can be challenging, especially if your Workspace One UEM API URL is not public and only accessible from your internal(s) server(s).

One of the advantages of migrating to a Workspace One UEM DSaaS tenant is that you can choose the API URL that you want to use.
During the migration process you will keep your Device Services URL (mandatory to keep your devices enrolled in Workspace One UEM) and you can also use a custom URL for the API services.
Using a custom URL for API gives the possibility to prepare the migration and make sure that the switch between your On Premises environnement and the SaaS environnement is done smoothly.

I would like to share my experience about this and provide an overview of the steps that you need to complete in order to achive the public API URL publication before your DSaaS migration.

There are multiple services that use REST API in Workspace One:

  • Workspace One Core components (Console Serveur, Device Service Serveur)
  • Airwatch Cloud Connector
  • Unified Access Gateway with the following Workspace One UEM Edge services
    • Secure email gateway
    • Proxy Tunnel
    • Per App VPN
    • Content Gateway
  • Workspace One Access

In Workspace One UEM your API servers can be installed on separate servers. This is recommended when you are using more that 50,000 devices.
In addition, a dedicated API server can be setup to be reachable only from your internal network.

This is an ideal solution if you want to control access on your API infrastructure but it can be challenging if the day comes when you have to migrate to a SaaS environment.

In order to offer the most seemless experience to your users during your SaaS migration, it is important that your API servers are accessible from Internet. This way you do not need to add any other reconfiguration steps during your DSaaS migration and you can take your time preparing for the change.

The good thing is that we can prepare the migration and setup a public facing API before switching to the Dedicated SaaS environment following a few steps:

  1. Make your API URL public
  2. Test your public API URL
  3. Test public API URL connection from UEM core components: Airwatch Cloud Connector, Devices Services server, Console Server
  4. Test public API URL connection from Unified Access Gateway Edge Services
  5. Test public API URL connection from Workspace One Access
  6. Migrate from internal API URL to public API URL

Step 1 - Make your API public

Public DNS name:

The first step before migrating to SaaS is to create a public DNS name for your new public API.

This public DNS name will be used on your new Dedicated SaaS tenant.
Your internal Workspace One servers (ACC, Devices Services Server, Console Server, UAG, Workspace One Access) will be able to continue communicating with the API server as soon as you proceed to the DNS redirection on the new Workspace One UEM SaaS tenant during the migration steps.

DNS configuration

The public API URL must be reachable from the Workspace One UEM servers and Workspace One Access server, the API name resolution must be configured on the DNS servers of your organization.

If you have multiple DNS servers (DMZ, internal Network) you need to setup the DNS resolution for each of your DNS in order for the components to resolve the public DNS name of the API on the public IP adress.

Public SSL certificate

The second element that you need is a public SSL certificate from a third party provider with a common name matching your public DNS name.You can find a list of the best SSL services to buy in 2022 here

The public DNS and SSL certificate public exposure for your API server can be achieved using a reverse proxy on the front of your API servers.
It is a good idea to choose a reverse proxy that also offers a load balancing feature, that way you can expose your public API on Internet and use the load balancing feature to balance the network traffic across different servers on your network.

There are multiple advantages to setting up a reverse proxy for the API:

  • You do not need to change any configuration on your internal API servers.
  • The API service will still be available internally for your Workspace One components before the migration.
  • You can take your time switching the service from an internal API to an external API and avoid changing everything at once during the migration.
  • You stay in control and you can come back to your previous configuration using internal API if anything goes wrong during your tests.

When your public DNS API is available and the reverse proxy has been setup to forward requests to your API servers, you can define your API migration strategy.

Some examples of API migration architecture solutions can be find below:

Step 2 - Test your public API

When the DNS is public (you can check the DNS propagation on https://dnschecker.org/) and when your reverse proxy is configured to redirect the traffic to your API servers, you can test the access to your public API by trying to access the API web page from a browser on a computer connected outside your company network using:

https://your-public-api-URL/api/help/

If you can access the api help page without SSL error, then you have completed the first step of your API migration.

Step 3 - Test public API URL connection on Devices Services server, Console Server and Airwatch Cloud Connector

Workspace ONE UEM - Devices Services server

Device Services are the components of Workspace ONE UEM that actively communicate with devices. Workspace ONE UEM relies on this component to process:

  • Device enrollment
  • Application provisioning
  • Delivering device commands and receiving device data

Device Services also hosts the Self-Service Portal, that users access (through a Web browser) to monitor and manage their devices in Workspace ONE UEM.

Workspace ONE UEM - Console

Administrators use the Workspace ONE UEM Console through a Web browser to secure, configure, monitor, and manage their corporate device fleet.

Workspace ONE UEM - Airwatch Cloud Connector

Airwatch Cloud Connector is a key component in Workspace One UEM.
It gives organizations the ability to integrate Workspace One UEM with their back-end enterprise systems:

  • Directory integration
    • Sync directory users accounts and groups
    • Sync directory admin accounts and groups
    • Perform authentication against directory
  • Certificate authority integration
  • SMTP integration
  • Exchange PowerShell integration
  • Syslog integration

In addition to the communication with your backends and in order ACC to run properly with Workspace One UEM, it needs 2 things:

  • Airwatch Cloud Messaging communication
  • REST API communication

Verify the connection to the public API from Console, Devices Services server and Airwatch Cloud Connector servers:

Before changing the REST API configuration in Workspace One UEM you need to verify that your Workspace One UEM servers (Console, Devices Services server and Airwatch Cloud Connectors servers) can communicate with your public API server.

From your Console, Devices Services server and Airwatch Cloud Connectors servers check the communication with the public API URL using:
telnet your-public-api-URL 443

If you need to go through an outbound proxy, you can check the communication using curl command (curl is inclued per default on windows server 2019, if you are using a previous version you will need to install curl on the server)

Once you have validated that your Console, Devices Services server and Airwatch Cloud Connectors servers can access to the public API URL you can test the other servers before migrating the API.

Step 4 - Test public API URL connection from Unified Access Gateway Edge Services

Unified Access Gateway Edge services working with Workspace One UEM are:

  • Secure email gateway
  • Proxy Tunnel (with VMware Web application)
  • VMware Tunnel (with VMWare Tunnel application)
  • Content Gateway

Before migrating we want to make sure that the UAGs can communicate with the public API URL

If you do not use an outbound proxy:
Connect on SSH to each of your UAG as root user:
telnet the public API URL
curl -v telnet://your-public-api-URL:443

If you use a outbound proxy:
Connect on SSH to each of your UAG as root user and check if the UAG can access the public API URL:

Once you have validated that your UAG servers can access the public API URL you can continue with the next step.

Step 5 - Test public API URL connection from Workspace One Access

Workspace One Access will use REST API calls for device compliance check and Intelligent Hub service so we need to confirm that the Workspace One Access can communicate with the public API URL.

Into Workspace One Access you can verify the API URL that your are using in Workspace ONE Access service Identity & Access Management > Setup > Workspace ONE UEM page

API-Access-URL

If you do not use an outbound proxy:
To verify the connection to the public API, connect on SSH to each of your Workspace One Access node as root user or from the vSphere Client, log in to the Workspace ONE Access virtual appliance as the root user.

Test the public API URL using telnet:
curl -v telnet://your-public-api-URL:443
If the connection is successfull then you can access your public API.

If you use an outbound proxy:
To verify the connection to the public API, connect to each of your Workspace One Access nodes as root user on SSH or from the vSphere Client, log in to the Workspace ONE Access virtual appliance as the root user.

  • If your proxy needs a user account:
    Test the public API URL using telnet:
    curl -x http://proxy_server:proxy_port --proxy-user username:password -L https://your-public-api-URL

  • If your proxy does not need a user account:
    Test the public API URL using telnet:
    curl -x http://proxy_server:proxy_port -L https://your-public-api-URL

If the connection is successfull it means that you can access your public API.

How to verify outbound proxy configuration in Workspace One Access
You can also verify the outbound proxy configuration in Workspace One Access depending of the Workspace One Access version that you are using:

Workspace One Access before version 20.10 (SUSE Linux 11 SP4 based):

The proxy setting configuration in Workspace One Access before version 20.10 uses YaST utility

From the vSphere Client, log in to the Workspace ONE Access virtual appliance as the root user.
To run the YaST utility, enter YaST on the command line.
Select Network Services in the left pane, then select Proxy.
Verify the proxy server URLs in the HTTP Proxy URL and HTTPS Proxy URL text boxes.

Yast

Workspace One Access from version 20.10 (VMware Photon 3.0 based):

From Workspace ONE Access 20.10, the underlying operating system moved from SUSE Linux 11 SP4 to VMware Photon 3.0 and the outbound proxy configuration can be setup in the Workspace One Access Web UI admin page.

You can also verify the proxy configuration directly into each of the Workspace ONE Access appliance logged as the root user in: /etc/sysconfig/proxy

Step 6 - Migrate from internal API URL to public API URL

Once you have completed all the test connections you can do the switch and migrate from internal API URL to public API URL.

1 - Deactivate Device compliance check in Workspace One Access

First you need to temporarily deactivate the device compliance check in Workspace One Access before changing API URL in Workspace One UEM.

If you are using a device compliance check, Workspace One Access will make a call API to Workspace One UEM when a device is performing an authentication in Workspace One Access (Mobile SSO / Certificate).

So during the API URL change this setting needs to be deactivated otherwise the devices will not be able to perfom the authentication.

Log as an administrator in Workspace One Access and go to Identity and Access: Management / Setup / VMware Workspace One UEM and disable "Compliance Check" then save.

Compliance-check-1

2 - Change the API REST in Workspace One UEM Console

Log into Workspace One UEM web console, go to System / Advanced / Site URLs and change REST API URL with your new public API URL "https://your-public-api-URL" then save.

3 - Reinstall Airwatch Cloud Connector

Since you have changed the API URL, you need to reinstall all your Airwatch Cloud Connectors in order to update the new API URL on the connectors.
Log into Workspace One UEM web console, go to System / Enterprise Integration / Cloud Connector and "Download AirWatch Cloud Connector Installer". Run the installer on each Airwatch Cloud Connector server in order to update the service with the new API URL.
Validate the ACC is working fine after the change using one or more of the following test: test enrollement with user directory account, directory authentication (though Self service portal for example), internal PKI certificate request, email SMTP.

4 - Change the API URL on the Unified Access gateway Edge service

Log into the each of your Unified Access Gateway admin interface using https://My_UAG_IP:9443/admin/index.html

Under Configure Manually, click Select:

Uag-admin

Next to Edge Service Settings, click Show:
Edge-service

Change the API Server URL for each UEM egde service that you are using on each Unified Access Gateway server:

General Settings > Edge Service Settings >

  • Tunnel Settings
    
  • Secure Email Gateway Settings
    
  • Content Gateway Settings
    

Save the change, the edge service will automatically restart, the UAG will try to import the configuration from your UEM console though an REST API call using the new public API URL.
You can check if the edge status service switches to green after a few minutes in General Settings > Edge Service Settings.
When the service is green your UAG is back online.

5 - Change the API URL on Workspace One Access

Log as an administrator in Workspace One Access and go to Identity and Access Management / Setup / VMware Workspace One UEM.

Change the Workspace ONE UEM API URL with your new public API URL "https://your-public-api-URL" then save.

You can verify that Workspace One Access is correctly using the new API URL by opening the Hub service in Workspace One Access, go to catalog > Hub configuration > Launch

Hub

When you open the Hub setting, Workspace One Access will make an API call to Workspace One UEM, if the Hub settings are available this confirms that Workspace One Access is able to use the new configuration.

If you are using device compliance check you can now re-enable the compliance check in Workspace One Access:

Log as an administrator in Workspace One Access and go to Identity and Access Management / Setup / VMware Workspace One UEM and enable "Compliance Check" then save.

Conclusion

Migrating to a DSaaS environment can be very challenging for large organizations. Preparing the migration prior to the switch in DSaaS in order to limit the amount of changes that have to be done at the same time during the migration is really important and allows you to limit the risks.

When API service is reachable from outside of your internal network and you have validated that all key components are able to resolve the public URL and are working fine, the only action that you need to focus on during the migration is to perfom the DNS redirection to the DSaaS Tenant.

This simplifies the process and increases the chance to obtain a seemless migration for end users.

Great! Next, complete checkout for full access to Mobinergy Blog.
Welcome back! You've successfully signed in.
You've successfully subscribed to Mobinergy Blog.
Success! Your account is fully activated, you now have access to all content.
Success! Your billing info has been updated.
Your billing was not updated.