> ## 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 Orka VMs or bare metal Macs to Citrix Cloud for MacStadium VDI: Machine Catalogs, enrollment tokens, VDA install, Delivery Groups, and Rendezvous.

<Warning>
  Complete these steps in order. Machines must 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)
* One of the following, depending on your deployment:
  * **Orka VM:** at least one 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. You also need `sshpass` installed on your Ansible runner, required by the VDA playbooks.
  * **Bare metal Mac:** a provisioned host with SSH or Screen Sharing access. See [VDI on bare metal Mac](/remote-desktop-vdi/overview/bare-metal-mac-vdi).

***

## 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, and bare metal Mac hosts aren't power managed by Citrix either.
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 and bare metal hosts 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.

If you're on Orka VM, store the token in your Ansible Vault:

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

If you're on bare metal Mac, there's no Ansible Vault. Store the token in your password manager instead.

***

## Step 3: Install Citrix VDA

<Warning>
  Machines must be reachable over the network before you install VDA. Orka VMs on NAT networking can't be reached directly by Citrix Cloud or end users, and you can't change the network mode after a VM is deployed.
</Warning>

<Tabs>
  <Tab title="Orka VM">
    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.
  </Tab>

  <Tab title="Bare metal Mac">
    Bare metal Macs have no Orka Engine, no management UI, and no Ansible playbooks. Install the Citrix VDA directly on the host.

    1. In Citrix Cloud Console, go to **Web Studio** > **Utilities** and download the Citrix VDA for macOS `.dmg`.
    2. Copy the `.dmg` to the host over SSH or Screen Sharing.
    3. Set the hostname to match your naming convention before installing. The VDA registers using the hostname at install time.
    4. Run the installer on the host and grant the TCC (Privacy & Security) permissions it requests. See [Citrix's VDA for macOS installation guide](https://docs.citrix.com/en-us/mac-vda/install) for the exact prompts; they vary by macOS version.
    5. Reboot the host. Wait for the reboot to complete before continuing to Step 4.

    There's no golden image step for bare metal. Each host is installed and registered individually.
  </Tab>
</Tabs>

***

## Step 4: Register the VDA

<Tabs>
  <Tab title="Orka VM">
    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>"
    ```
  </Tab>

  <Tab title="Bare metal Mac">
    The Citrix VDA installer prompts for your Citrix Cloud customer ID and enrollment token during setup. Enter them there to register the host.

    See [Citrix's VDA for macOS installation guide](https://docs.citrix.com/en-us/mac-vda/install) if you need to re-register a host after installation; the reconfiguration steps vary by VDA release.
  </Tab>
</Tabs>

***

## Step 5: Verify registration

After registration, the machine 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 machine appears with **Registration state: Registered** and **Power state: On**.

If it doesn't appear, check the VDA logs:

```
/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 through 5 for all machines 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 machines 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.

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:** machines need outbound access to `*.*.nssvc.net` on TCP/UDP 443. No inbound ports are required.

***

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

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

On Orka VM, check the service status through Ansible:

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

Restart it with:

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

On bare metal Mac, run the same `launchctl` commands directly on the host over SSH; there's no Ansible layer in between.

### Rendezvous connections failing

* Confirm outbound access to `*.*.nssvc.net:443` from the machine.
* 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 (Orka VM) or password manager (bare metal Mac), and re-register.
* **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.


## Related topics

- [Apple Business Manager and MDM with MacStadium](/remote-desktop-vdi/configuration/apple-business-manager-and-mobile-device-management-with-macstadium.md)
- [Validation and testing](/remote-desktop-vdi/operations/validation-and-testing.md)
- [Getting started: MSDC-hosted](/remote-desktop-vdi/getting-started/msdc-hosted.md)
- [Self-hosted MacStadium VDI deployment guide](/remote-desktop-vdi/getting-started/self-hosted.md)
- [Bulk VM lifecycle management](/remote-desktop-vdi/operations/bulk-vm-lifecycle.md)