Joining Desktops to a Domain

Modified on Fri, 15 Dec 2023 at 10:00 AM

How the Domain Join feature works

Published by:  Leostream Support

Release Date:  November 22, 2020

Modified Date:  December 13, 2023

Summary:  The Connection Broker supports a feature to join a desktop to a domain.   With this feature, you can automatically have the desktop join a domain after it is created.   No hands needed!!


The Connection Broker “Domain Join” feature joins a new or existing desktop to a domain that is defined in the Connection Broker.   The Leostream Agent uses the information defined in the Connection Broker to initiate a domain join on the desktop.   

Use the following steps to define an environment where desktops can join a domain. 


  • Install the Leostream Agent on the desktop.     The Leostream Agent is available from the Leostream website on the Resources > Downloads page.   Installation documentation is available from the Leostream website on the Resources > Documentation page.
    • The desktop must be a member of a workgroup to join the domain.
  • Define an Authentication Server in the Connection Broker on the Setup > Authentication Servers page.  You need the domain, hostname or IP of your domain server and the credentials for an account that has privileges to join desktops to the domain.   
    • The account must be defined in the user@domain format.
  • On the Configuration > Pools page, create a pool with criteria that the desktop meets, or update an existing pool which the desktop belongs to.   Scroll down to the Domain Join section and select the “Join virtual machine to a domain”.

Desktops can belong to multiple pools but the desktop can only be a member of one pool which has the “Join virtual machine to a domain” option selected


The “domain join” is initiated when the Leostream Agent starts on the desktop.    The Connection Broker receives the Leostream Agent start and evaluates the “Join virtual machine to a domain” for the pool(s) that the desktop belongs to.  

These are the steps when the Connection Broker attempts to join a desktop to a domain

1. Leostream Agent starts

2. Leostream Agent sends notification to the Connection Broker that it started

3. Connection Broker receives notification from the Leostream Agent. The notification includes whether the desktop is already in a domain or not.

Process stops here If the desktop is already in a domain.  Update the desktop record with current domain and other information about the desktop.

4. Connection Broker evaluates desktop for pool membership(s). (Desktops can be in more than one Pool.)

5. Connection Broker checks if each pool has the “Join virtual machine to a domain” option selected

Process stops here if no pool requests domain join

6. The Connection Broker checks to make sure there are no conflicts, like two or more pools wanting to join different domains or OUs. 

Process stops here and log error if necessary.

7. Connection Broker sends the Domain name and Authentication Server’s credentials to the Leostream Agent, along with the request to join the domain.

8. Leostream Agent attempts to join the desktop to the domain

9. Desktop restarts, as required by Windows

10. Start again at step 1.

Possible Errors:

Several things could prevent the Connection Broker from successfully joining a desktop to a domain.   You can check the Connection Broker System > Log page to determine why a desktop did not join the domain.   The following is a list of common issues and how to resolve them.

  • The desktop is already a member of a domain.
    • Desktop attributes are listed on the Resources > Desktop – Edit page for the desktop.  The “Last Hostname” attribute includes a fully qualified name, including the domain name, for desktops in a domain.
  • The Connection Broker cannot contact the Leostream Agent.  
    • The Connection Broker contacts the Leostream Agent to request the domain join.   The request will fail if the Connection Broker cannot contact the Leostream Agent.   You can check Connection Broker communication to the Leostream Agent using the Status link on the Resources > Desktop page.
  • The Leostream Agent cannot contact the Connection Broker.
    • Before the ‘Domain Join’ processing begins, the Leostream Agent must contact the Connection Broker first and register.  The Leostream Agent only listens for events from Connection Brokers that it registered with.  You can check if the Connection Broker DNS name or address is defined on the Leostream Agent.   The ‘Test’ button will attempt to contact the Connection Broker and display its release if the test is successful.
  • The desktop belongs to more than one pool with the Domain Join feature enabled
    • Desktops can belong to one or more pools.   Each pool can have its own set of criteria for joining the domain and the OU where the desktop is added.     The Connection Broker does not attempt to join the desktop to a domain when there are 2 or more pools with conflicting options.
  • The Connection Broker’s definition for the “Login name or DN” is in the incorrect format.
    • Some authentication servers, such as Active Directory, require user@domain format for the desktop to join the domain.   The account defined in ‘Login name or DN’ field on the Setup > Authentication page must be in the correct format for the domain join.
  • The Connection Broker’s definition for the “Login name or DN” does not have the authority to join a desktop to the domain.
    • The account defined to the Authentication Server must have administrator privileges to join a domain.   You should test the domain join without the Connection Broker if you suspect that the account does not have the correct privileges to join the domain. 

© Copyright 2023 Leostream Corporation