Workspot Client Connection Flow (In Review - Draft)

This document explains how the Workspot Client communicates with Workspot services from the first launch on a device through a successful desktop connection.

Overview

When a user launches the Workspot Client and connects to a desktop or application, the client follows a well‑defined communication sequence in the background. Understanding this end‑to‑end flow helps administrators and support teams troubleshoot Windows client connectivity issues better.

Note: Depending on the customer environment and enabled features, the flow may change.

• Identify where a connection issue occurs

• Explain login or connection delays

• Clearly articulate client behavior to security, network, or identity teams

• Differentiate client‑side delays vs platform issues

This document explains the flow in two parts:

• Part 1 — First Time Use (FTU): One‑time setup when the client is opened on a new device

• Part 2 — Desktop Launch: What happens each time a user launches a desktop or application
  

Part 1 — First Time Use (FTU)

The diagram below shows the end-to-end sequence covering First Time Use (FTU). FTU occurs once per device. After completion, the client skips FTU‑specific steps on future launches.

Phase 1: Client Startup & Configuration Read

When the Workspot Client starts, it reads its local configuration.

Service Registry Endpoint (SRE): The SRE identifies which Workspot environment the client should connect to. If not configured, the client by default points to Workspot US Production. At this stage, the client also checks for client updates and may prompt the user if a newer version is required.

Phase 2: Network & Internet Connectivity Check

Before any prompt appears to the user, the client verifies:

• Network connectivity

• Internet reachability

• Connection type (Wi‑Fi, Ethernet, Cellular)

If internet access is unavailable:

• The client displays a warning

• The user cannot proceed until connectivity is restored

These checks run in parallel with other startup tasks.

Phase 3: Location Detection (Background)

In parallel with the startup, the client determines the user’s network location.

How Location Detection Works

The client attempts to reach an internal-only URL configured in: Control → Setup → Configuration

Important Notes

• Only affects pools set to External Only

• Ignored if pool routing is set to Always or Never

• Without a URL configured, all users route through the Gateway, or as per pool settings

This check is silent and does not affect FTU completion; it only affects later connection routing.

Phase 4: Company Identifier & Org Lookup

The user enters their Company Identifier (unique Workspot org identifier).

Flow

1. User enters the identifier

2. Client sends it to the Service Registry Endpoint

3. Registry returns:

   • Org‑specific service endpoints (Control, PRS, Credential Service)

   • Authentication method (Entra ID, ADFS, SAML)

   • Authentication endpoint

4. Client caches these details locally

   If invalid, the error indicates org misconfiguration.

Phase 5: Identity Provider Authentication

Based on the configured IdP, the client initiates authentication.

Entra ID (Azure AD)

• Embedded browser opens Microsoft login endpoint

• Silent authentication attempted first

• Interactive login shown only if silent auth fails

• MFA enforced via Conditional Access

Silent Auth Behavior

• Entra‑joined / Hybrid‑joined Windows: Usually silent (PRT)

• Unmanaged or personal devices: Interactive login

Conditional Access is evaluated every time a token is issued or renewed.

Active Directory / ADFS

• Domain‑joined Windows: Kerberos (fully silent)

• Control requires DC connectivity at auth time via the Enterprise connector (EC)
  Client > Control > EC > DC » (Auth Success/ Failure) » EC > Control > Client

SAML Identity Provider

• User redirected to external IdP (Okta, Ping, OneLogin, etc.)

• User authenticates with IdP policies

• SAML assertion validated by Workspot Control

Phase 6: Workspot Activation (Device Registration)

After successful authentication:

Control:

• Validates user identity (UPN)

• Registers the device

• Issues a device registration token

• Returns user entitlements (desktops, apps)

• Pushes security and client policies

If the Workspot client is not used for more than 60 days, the device record is automatically removed from Control, and the client is required to re-register the device.

FTU completes at this phase

Phase 7: First Heartbeat & UI Ready

Immediately after FTU:

• Client sends a heartbeat to Control

• Desktop tiles appear but are temporarily locked

  • To check any client hash change (policy, configuration, entitlements, etc.).

• Once the heartbeat is acknowledged or after 5 seconds:

  • Tiles become clickable

  • Icons are downloaded

  • VDI plugins (Teams, Zoom, Webex) are validated and updated silently

Part 2: Desktop Launch (Every Session)

This flow runs every time a user launches a desktop or app.

Phase 8: Desktop Tile Click

Clicking a tile does not immediately start RDP.

• If a Security Posture Policy (selected feature) exists:

  • Connection is paused

  • Posture checks must be completed

• If no posture policy: skipped

Phase 9: Security Posture Check (Client-Side)

Client evaluates posture requirements configured per pool.

Common Checks

• Antivirus enabled

• Firewall enabled

• OS build level

• Windows Update status

Each check has a blockAccessIfFail setting:

• false → Warning only

• true → Connection blocked

Results are logged in Control Audit Logs.

Performance Note

Windows Update scans can take 10–15 seconds on a cold cache. This is the most common cause of slow first connections

Phase 10: VM Assignment

After posture success, Control returns:

• Target VM details

• Pool type

• Routing path (direct or Gateway)

• SSO credentials

Pool Behavior Summary

** Not required for connection after first login. However, control is required to connect to the SRE & PRS service.

Phase 11: RDP Configuration Assembly

RDP parameters are built from:

• Security Policy (admin enforced)

• User Preferences

⚠️ Security Policy always overrides user settings.

Phase 12: Gateway Token (If Needed)

If routing via Gateway:

• Client silently acquires a Gateway token

• Uses cached auth token where possible

• Authorizes forwarding through the Gateway

Skipped if routing is Never or the user is Internal.

Phase 13: PRS Resume Call

Client calls the Pause‑Resume Service (selected feature):

• Signals intent to connect

• Ensures the persistent VM is active

• Client polls every 5 seconds to check if the VM comes to the ready state in the Control

Phase 14: RDP Session Established

Connection paths:

• External: Client → Gateway → VM

• Internal: Client → VM (direct)

Once the RDP session negotiates successfully:

• Display initializes

• VDI plugins load

• Desktop or app appears

Phase 15: Connection Logged

A Successful Connection event is logged, including:

• VM details

• Pool and policy applied

• Routing path

• Redirection settings

• Timing metrics per phase

Troubleshooting Quick Reference

Understanding each phase makes troubleshooting faster, more accurate, and easier to explain to customers and internal teams.