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

# Citrix DaaS configuration

> Connect your Orka VMs to Citrix Cloud. Covers Machine Catalogs, enrollment tokens, VDA installation, Delivery Groups, and Rendezvous.

<Warning>
  Complete these steps in order. VMs must be deployed with bridged networking, have Citrix VDA installed, and be registered in a Machine Catalog before you assign users to a Delivery Group. Doing these out of order prevents sessions from launching.
</Warning>

## Before you begin

You need:

* An active Citrix DaaS subscription (Standard tier or above)
* Admin access to [Citrix Cloud Console](https://citrix.cloud.com)
* Your Citrix Cloud customer ID (visible in the Cloud Console)
* At least one Orka VM deployed with bridged networking (`network_interface=en0`). See [Getting Started: MSDC-Hosted](/remote-desktop-vdi/getting-started/msdc-hosted) or [Getting Started: Self-Hosted](/remote-desktop-vdi/getting-started/self-hosted) if you haven't done this yet.
* `sshpass` installed on your Ansible runner (required by the VDA playbooks)

***

## Step 1: Create a Machine Catalog

Machine Catalogs are logical groupings of VMs in Citrix. Because Apple's licensing requirements mean Citrix treats each Mac as a physical device, use the Remote PC Access catalog type.

1. In **Citrix Cloud Console**, go to **Web Studio** → **Machine Catalogs**.
2. Click **Create Machine Catalog**.
3. Select **Remote PC Access**.
4. Under machine power management, select **Machines that are not power managed**. Orka manages the VM lifecycle.
5. Set the session type to **Single-session**.
6. For user assignment, choose based on your use case:
   * **Random (pooled):** users get any available desktop (non-persistent)
   * **Static (dedicated):** users get the same desktop each session (persistent)
7. For non-domain-joined Macs, select **No, do not add to Active Directory**.
8. Name the catalog using a pattern that reflects the OS version, hardware profile, and purpose. For example: `Orka-macOS-Sequoia-Standard-Engineering`.
9. Skip adding machines for now. VMs register automatically using the enrollment token after VDA is installed.

***

## Step 2: Generate an enrollment token

The enrollment token authenticates VDA registration and associates each VM with your Machine Catalog.

1. In **Web Studio**, go to **Machine Catalogs** and select the catalog you just created.
2. Click **Enable Enrollment Token**.
3. Give the token a descriptive name (for example, `Orka-Finance-2026-Q2`).
4. Set an expiration that covers your deployment window.
5. Copy the token immediately. It's shown only once. If you lose it, generate a new one.

Store the token in your Ansible Vault:

```yaml theme={null}
vault_citrix_enrollment_token: "your-token-here"
vault_citrix_customer_id: "YOUR_CUSTOMER_ID"
```

***

## Step 3: Install Citrix VDA

<Warning>
  VMs must be running with bridged networking before you install VDA. VMs on NAT networking can't be reached directly by Citrix Cloud or end users. You can't change the network mode after a VM is deployed.
</Warning>

We recommend hosting the Citrix VDA `.dmg` in an S3 bucket with a presigned URL. The playbook downloads it directly to the VM.

From the management UI, run the **VDI | Install Citrix VDA** template. Or run from the CLI:

```bash theme={null}
ansible-playbook -i inventory install_citrix_vda.yml -e "vm_name=<vm_name>" -e "vm_username=<admin_username>" -e "vm_password=<admin_password>" -e "citrix_installer_url=<citrix_dmg_url>" -e "hostname_suffix=<domain_suffix>"
```

| Variable               | Description                                                                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `vm_name`              | Exact name of the running VM. Also used as the VM hostname.                                                                            |
| `citrix_installer_url` | Download URL for the Citrix VDA `.dmg`.                                                                                                |
| `hostname_suffix`      | Domain suffix appended to `vm_name` to form the full hostname (for example, `corp.example.com`). Leave blank to use the VM name alone. |

The playbook installs .NET runtime prerequisites, sets the VM hostname, downloads and installs the VDA package, grants required TCC permissions, and reboots the VM. Wait for the reboot to complete before continuing to Step 4.

### Building VDA into a golden image

For fleet deployments, build VDA into your golden image instead of installing it per VM. Add your VDA install script to the `/scripts` directory and run `create_image.yml`. VMs deployed from that image have VDA pre-installed and only need to be registered.

See [Image management](/remote-desktop-vdi/configuration/image-management) for the full build workflow.

***

## Step 4: Register the VDA

After the VM reboots, register it with Citrix Cloud using the enrollment token.

From the management UI, run the **VDI | Register Citrix VDA** template. Or run from the CLI:

```bash theme={null}
ansible-playbook -i inventory register_citrix_vda.yml -e "vm_name=<vm_name>" -e "vm_username=<admin_username>" -e "vm_password=<admin_password>" -e "enrollment_token=<enrollment_token>"
```

***

## Step 5: Verify registration

After registration, the VM should appear in your Machine Catalog within a few minutes.

1. In **Web Studio**, go to **Machine Catalogs** and select your catalog.
2. Confirm the VM appears with **Registration state: Registered** and **Power state: On**.

If the VM doesn't appear, check the VDA logs on the VM:

```
/Library/Application Support/Citrix/VDA/Logs/
```

***

## Step 6: Configure a Delivery Group

Delivery Groups control which users can access which machines and define session policies.

<Note>
  Complete Steps 3-5 for all VMs before assigning users. Users assigned to a Delivery Group with no registered machines can't launch sessions.
</Note>

1. In **Web Studio**, go to **Delivery Groups** and click **Create Delivery Group**.
2. Select the Machine Catalog from Step 1 and specify how many machines to include.
3. Name the group descriptively, for example: `Finance-macOS-VDI`.
4. Set the display name users see in Citrix Workspace.
5. Select **Published Desktop** as the delivery type.
6. Configure session policies: timeout, idle behavior, and reconnection rules.
7. Once your VMs show as Registered in Step 5, add the users or groups who should have access.

**Authentication options:**

* Active Directory users or groups (domain-joined environments)
* Azure AD, Okta, or other SAML providers
* Individual user accounts

**Multiple Delivery Groups from one catalog:**

You can create multiple groups from the same catalog to manage access granularly. For example, a standard group and a power-user group with different session policies, both drawing from the same pool of Mac hosts.

***

## Rendezvous protocol

Rendezvous enables HDX connections from non-domain-joined VDAs to Citrix Cloud without an on-premises StoreFront or NetScaler Gateway. The VDA opens an outbound WebSocket connection to Citrix Gateway Service, so no inbound ports are required on the VM.

Rendezvous is enabled by default in Citrix DaaS environments with non-domain-joined machines. To verify or configure it:

1. In **Web Studio**, go to **Configuration** → **Policies**.
2. Edit or create a policy for your Delivery Group.
3. Under **ICA/HDX settings**, confirm:
   * **Rendezvous Protocol:** enabled
   * **HDX Adaptive Transport:** Preferred
   * **WebSocket connections:** allowed

**Network requirement:** VMs need outbound access to `*.*.nssvc.net` on TCP/UDP 443. No inbound ports are required on the VM.

***

## SSO authentication

By default, users authenticate through Citrix Workspace and then see a macOS
login screen. With SSO enabled on the VDA, Workspace credentials pass through
to macOS automatically and the user lands directly in their desktop.

A few things to know before enabling it:

* Username and password only. FAS, smart cards, and passwordless providers
  are not supported.
* The macOS account credentials must match the user's Workspace credentials
  exactly.
* SSO conflicts with Jamf Pro/Connect and other tools that customize the macOS
  login process. If your VMs are managed that way, SSO won't work.
* The **Allow users not in Active Directory to use this delivery group**
  checkbox must be unchecked on the Delivery Group.

For setup steps, see [SSO Authentication](https://docs.citrix.com/en-us/mac-vda/configure/authentication/non-sso-authentication.html)
in the Citrix VDA for macOS documentation.

***

## Troubleshooting

### VM doesn't appear in the Machine Catalog

* Check that the enrollment token hasn't expired and was copied without truncation.
* Confirm outbound HTTPS (TCP 443) is allowed from the VM to `*.xendesktop.net` and `*.*.nssvc.net`.
* Confirm the token is associated with the correct Machine Catalog.
* Check VDA logs at `/Library/Application Support/Citrix/VDA/Logs/`.

### VDA service not running

Check the service status:

```bash theme={null}
ansible -i inventory all -m shell -a "sudo launchctl list | grep citrix"
```

Restart the service:

```bash theme={null}
ansible -i inventory all -m shell -a "sudo launchctl kickstart -k system/com.citrix.vda"
```

### Rendezvous connections failing

* Confirm outbound access to `*.*.nssvc.net:443` from the VM.
* Check whether an HTTP proxy is blocking WebSocket traffic.
* Review VDA logs for Rendezvous registration errors.
* Verify the Citrix Workspace app version is 2402 or later on client machines.

### Token errors

* **Expired token:** generate a new token in Web Studio, update your Vault, and re-run `register_citrix_vda.yml`.
* **Wrong Machine Catalog:** verify the token is associated with the correct catalog in Web Studio.
* **Customer ID mismatch:** confirm the customer ID matches your Citrix Cloud tenant.