Active Directory OU-based Controller discovery

This Delivery Controller discovery method is supported primarily for backward compatibility, and is valid only for Virtual Delivery Agents (VDAs) for Windows Desktop OS, not VDAs for Windows Server OS.

For information about other methods you can configure that enable VDAs to register with Controllers (including recommended methods), see VDA registration with Controllers.

Active Directory-based discovery requires that all computers in a Site are members of a domain, with mutual trusting relationships between the domain used by the Controller and the domain(s) used by desktops. If you use this method, you must configure the GUID of the OU in each desktop registry.

To perform an OU-based Controller discovery, run the Set-ADControllerDiscovery.ps1 PowerShell script on the Controller (each Controller contains this script in the folder $Env:ProgramFiles\Citrix\Broker\Service\Setup Scripts). To run the script, you must have CreateChild permissions on a parent OU, plus full administration rights.

When you create a Site, a corresponding Organizational Unit (OU) must be created in Active Directory if you want desktops to discover the Controllers in the Site through Active Directory. The OU can be created in any domain in the forest that contains your computers. As best practice, the OU should also contain the Controllers in the Site, but this is not enforced or required. A domain administrator with appropriate privileges can create the OU as an empty container, then delegate administrative authority over the OU to a Citrix administrator.

The script creates several essential objects. Only standard Active Directory objects are created and used. It is not necessary to extend the schema.

• A Controllers security group. The computer account of all Controllers in the Site must be a member of this security group. Desktops in a Site accept data from Controllers only if they are members of this security group.

  Ensure that all Controllers have the ‘Access this computer from the network’ privilege on all virtual desktops running the VDA. You can do this by giving the Controllers security group this privilege. If Controllers do not have this privilege, VDAs will not register.

• A Service Connection Point (SCP) object that contains information about the Site, such as the Site name. If you use the Active Directory Users and Computers administrative tool to inspect a Site OU, you might need to enable Advanced Features in the View menu to see SCP objects.

• A container called RegistrationServices, which is created in the Site OU. This contains one SCP object for each Controller in the Site. Each time the Controller starts, it validates the contents of its SCP and updates it, if necessary.

If multiple administrators are likely to add and remove Controllers after the initial installation, they need permissions to create and delete children on the RegistrationServices container, and Write properties on the Controllers security group. These permissions are granted automatically to the administrator who runs the Set-ADControllerDiscovery.ps1 script. The domain administrator or the original installing administrator can grant these permissions, and Citrix recommends setting up a security group to do this.

When you are using a Site OU:

• Information is written to Active Directory only when installing or uninstalling this software, or when a Controller starts and needs to update the information in its SCP (for example, because the Controller was renamed or because the communication port was changed). By default, the Set-ADControllerDiscovery.ps1 script sets up permissions on the objects in the Site OU appropriately, giving each Controller Write access to its SCP. The contents of the objects in the Site OU are used to establish trust between desktops and Controllers. Ensure that:
  • Only authorized administrators can add or remove computers from the Controllers security group, using the security group’s access control list (ACL).
  • Only authorized administrators and the respective Controller can change the information in the controller’s SCP.
• If your deployment uses replication, be aware of potential delays. See the Microsoft documentation for details. This is particularly important if you create the Site OU in a domain that has domain controllers in multiple Active Directory sites. Depending on the location of desktops, Controllers, and domain controllers, changes that are made to Active Directory when you are initially creating the Site OU, installing or uninstalling Controllers, or changing Controller names or communication ports might not be visible to desktops until that information is replicated to the appropriate domain controller. The symptoms of such replication delay include desktops that cannot establish contact with Controllers and are therefore not available for user connections.
• This software uses several standard computer object attributes in Active Directory to manage desktops. Depending on your deployment, the machine object’s fully qualified domain name, as stored in the desktop’s Active Directory record, can be included as part of the connection settings that are returned to the user to make a connection. Ensure that this information is consistent with information in your DNS environment.

To move a Controller to another Site using OU-based Controller discovery, follow the directions above for moving a Controller. After you remove the Controller from the old Site (step 2), run the PowerShell script Set-ADControllerDiscovery –sync. This script synchronizes the OU with the current set of Controllers. After joining the existing Site (step 3), run the same script on any Controller in the new Site.

Permissions required for OU-based discovery

To create a Site, the Citrix administrator who runs the script must have rights over the Site OU to create objects (SCP, container, and security group).

If the Site OU is not present, the administrator must have rights to create that as well. Citrix recommends that the AD domain administrator pre-create that OU and delegate rights to it to the Citrix Site administrator identity. Optionally, the script can also create the Site OU. To allow this, the administrator needs the “create OU” right on the new OU’s parent OU. However, as noted, Citrix does not recommend this.

Later, to add or remove a Controller from the Site, the Citrix administrator must have rights to add/remove a machine from the security group, and create/delete an SCP.

During normal operations, Controllers and VDAs need read rights to all objects in the OU and below. VDAs access the OU as their own machine identity; that machine identity needs at least read rights in the OU to be able to discover Controllers. A Controller also needs the rights to set properties on its own SCP object in the container.

Granting the Citrix administrator full rights to the child OUs will permit all these actions. However, if your deployment has stricter security requirements (such as restricting who can use the script for which action), you can use the Delegation of Control wizard to set specific rights. The following example procedure grants rights to create the Site.

1. Create an OU to contain the child objects (Service Connection Point (SCP), container, and security group).
2. Select the OU, then right-click and select Delegate Control.
3. In the Delegation of Control wizard, specify the domain user to delegate control to for the OU.
4. On the Tasks to Delegate page, select Create a custom task to delegate.
5. On the Active Directory Object type page, accept the default This folder, existing objects in this folder, and creation of new objects in this folder.
6. On the Permissions page, select the Write and Create All Child Objects check boxes.
7. Finish the wizard to confirm the privileges.