---
title: "Workspot Client Connection Flow (In Review - Draft)"
slug: "workspotclientconnectionflow"
updated: 2026-05-04T11:10:08Z
published: 2026-05-04T11:10:08Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.workspot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/image(113).png)

**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**

| **Result** | **Interpretation** | **Routing Impact** |
| --- | --- | --- |
| URL reachable | User is **Internal** | Direct RDP (no Gateway) |
| URL unreachable | User is **External** | Route through Gateway |
| No URL configured | Location unknown | All users are treated as External |

**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.

![](https://cdn.us.document360.io/ad9153e1-c8de-4f56-94f2-b717a1fc3a68/Images/Documentation/image(114).png)

**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**

| **Pool Type** | **VM Reuse** | **Cached** | **Control Required** |
| --- | --- | --- | --- |
| Persistent VDI | Same VM | Yes | **No (if cached) |
| Non‑Persistent | Any VM | No | Yes |
| Cloud App Server | Load balanced | No | Yes |
| Cloud Application | Static | No | Yes |

** 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**

| **Symptom** | **Likely Area** | **Common Cause** |
| --- | --- | --- |
| Stuck at Company ID | SRE / Network | Wrong ID or unreachable SRE |
| Always interactive login | Token cache | Device not joined |
| Unexpected MFA | Conditional Access | Compliance or CA rule |
| 10–15s delay | Posture check | Windows Update scan |
| Connection blocked | Posture policy | blockAccessIfFail=true |
| All users use the Gateway | Location Detector | No beacon URL |
| Internal users slow | Location Detector | Beacon unreachable on LAN |
| No session in Control | Resource type | Cloud Application |

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