A Remote AD connects the cloud-based Octopus Management Console with a corporate on-premise Active Directory. The Remote AD contains a local Replica that represents the domain and a specified Base DN of the on-premise AD. The Replica is updated by means of a Remote AD Agent which is installed on a domain-joined on-premise Windows server or workstation.
Each Remote AD can work with only one Replica, but that Replica can be connected to multiple Agents.
 |
This document details the end-to-end process for creating and installing a Remote AD Agent. A Remote AD directory and a Replica are created automatically as part of the Agent installation process.
Prerequisites
The Octopus Remote AD Agent can be installed on the following operating systems:
- Windows Server 2016
- Windows Server 2019
- Windows Server 2022
- Windows 10
- Windows 11
Minimum hardware requirements for the target machine are a 4-core CPU and 8GB of RAM.
Before beginning the installation, verify that:
- You have obtained the installation file (e.g., octopus-remote_ad_agent-2.2.8.exe) from Secret Double Octopus
- User permissions are configured as described in Appendix A: Remote AD Permissions Configuration
A number of ports are required for normal operation of the Remote AD Agent. The ports that need to be open between the Remote AD Agent and the AD Server are listed in the table below.
| Remote AD Agent Port(s) | AD Server Port(s) | Service |
|---|---|---|
| 49152-65535 TCP | 464 TCP/UDP | Kerberos password change |
| 49152-65535 TCP/UDP | 49152-65535 TCP | RPC for LSA, SAM, NetLogon |
| 49152-65535 TCP | 389 TCP/UDP | LDAP |
| 49152-65535 TCP | 636 TCP | LDAP SSL |
An Agent and a Replica are prerequisites for adding a Remote AD directory to the Management Console. If you try to create a Remote AD Directory without first adding an Agent, the following popup opens:
 |
The best practice for adding your first Remote AD is to create an Agent and then install it on a domain-joined machine, as described in the following procedures.
To create a Remote AD Agent:
From the Octopus Management Console, open the Directories menu and select the Agents tab. Then, click Create Agent.
In the popup that opens, enter a name for the Agent and click Create.
The new Agent is displayed in the Agents tab. The orange connection status icon indicates that the Agent has not yet been installed in the on-premise environment.
Follow the steps below to install the Remote AD Agent. The Agent should be installed on a domain-joined on-premise Windows server or workstation.
IMPORTANT: To successfully use a Managed Service Account with the Octopus Remote AD Agent, you need to create the MSA and configure your Remote AD Server BEFORE installing the Agent. For details and instructions, refer to the document Configuring Managed Service Accounts for Use with the Remote AD Agent.
To install the Agent:
From the Agents tab, click the Download icon.
In the popup that opens, copy the Installation Code to a secure location. (You will need this later, during the installation process.
On a domain-joined Windows server or workstation, run the installation file as an Admin.
The Octopus Remote AD Agent installation wizard opens.
On the Welcome page, click Next.
On the License Agreement page, accept the terms and click Next.
On the Server Parameters page, configure the following settings:
Installation Code: Enter the code you copied in Step 1 above.
Management Console URL: Copy the setting from the Portal menu of the Octopus Management Console.
SSL/LDAPS: To support secured communication using port 636, select this checkbox.
Authentication Server URL: If you have a distributed environment, select the checkbox. Then, enter the Enterprise Base URL from the System Settings menu of the Management Console.
Use Proxy (optional): If your internet access requires a web proxy, select the checkbox. Then, enter the address of the Proxy Server in the following format: https://proxy.acme.com:1234
Click Next.
On the Logon Information page, omplete the settings according to the type of user account to be configured:
For a specific user account: Enter the credentials for the account. You can use the Super Admin credentials for the AD directory, or those of a user with Change Password privileges.It is recommended to use the credentials of the Domain Admin. If you use those of another user, verify that the user has all the required permissions. For details, refer to Appendix A: Remote AD Permissions Configuration.
Important: Enter the user name in the DOMAIN\Username format.
For a Managed Service Account: Select the Manage Service Account checkbox. (When the checkbox is selected, the Password field is disabled.)
Enter the user name using the syntax DOMAIN\<Service Account Name>$
In the following example, the name of the Managed Service Account is gMSAtest4.
Click Next.
On the Custom Setup page, review the settings and installation path. Then, click Next.
On the page that opens, click Install to begin the installation.
During the installation, you will be prompted to start the AD Agent registration process.
On the Management Console Admin Login page, enter the Super Admin login credentials for the Octopus Management Console, and click Login.
Alternatively, select the Login with Octopus Authenticator checkbox. Then, enter your username, click Login and authenticate using the Octopus Authenticator mobile app.
On the Agent Mode Selection page, choose either Serverless or Advanced Options:
Serverless (default): The Agent automatically connects to any available domain controller within the domain. The target domain is the one containing the installing machine. Serverless mode is recommended for most deployments.To install the Agent in Serverless mode, verify that the Serverless radio button is selected and click Next. Then continue to Step 13.
Advanced Options: These options enable you to target a specific domain (Domain mode) or to allow cross-domain searches (Forest mode). For more information about advanced options, refer to Configuring Advanced Agent Mode Selection.
On the Agent Settings page, specify the relevant OU or Domain. You can search according to name or DN.
Then, select the DN from which the Replica will begin the sync, and click Next.
On the Agent Details page, review the information and then click Register.
After the Agent is successfully registered, a confirmation message is displayed. Note that a Remote AD and Replica are created as part of the Agent registration process.
To exit the wizard, click Finish.
By default, the Remote AD Agent automatically connects to any available domain controller within the domain containing the installing machine. The advanced options on the Agent Mode Selection page enable you to target a specific domain (Domain mode) or to allow cross-domain searches (Forest mode).
Configuring Domain Mode
Installing the Agent in Domain mode allows you to change the default target domain to another domain of your choice. You can then specify DNs within the new domain from which the Replica will begin the sync.
Domain mode is recommended when you need to restrict operations to a particular domain, or if automatic discovery is not suitable for your environment.
To configure Agent Domain mode:
- On the Agent Mode Selection page, expand the Advanced Options and select Domain.
- Select the Enable manual editing checkbox.
The Target Domain field becomes editable.
- Enter the desired target domain, and then click Next.
- On the Agent Settings page, specify the relevant OU or Domain as explained in Step 13 of the procedure above.
Configuring Forest Mode
Installation in Forest mode allows the Remote AD Agent to operate across the entire Active Directory forest using Global Catalog servers. Forest mode is ideal for large multi-domain environments, as it enables cross-domain searches and management.
To configure Agent Forest mode:
- On the Agent Mode Selection page, expand the Advanced Options and select Forest.
Then, click Next.
- On the Agent Settings page, specify the relevant OU or Domain. You can search according to name or DN, across the entire domain topology.
Then, select the DN from which the Replica will begin the sync.
When your are finished configuring Agent Settings, click Next. On the Agent Details page, review the information and then click Register.
After the Agent is successfully registered, a confirmation message is displayed. Note that a Remote AD and Replica are created as part of the Agent registration process.
To exit the wizard, click Finish.
Viewing Remote AD Components in the Management Console
After successful installation of the Remote AD Agent, you can view the Remote AD directory and Replica that were automatically added to the Directories menu. For example:
 |
The Replica and its details are displayed in the Advanced tab.
 |
For complete information about managing the directory and its users, refer to the Octopus Management Console Admin Guide.
Before installing the remote AD agent, make sure the user is configured with the following permissions:
The user should have read, execute, list and write permissions to the c:\windows\temp folder. For more details about assigning these permissions, please click here
 |
The user should have both these permissions prior to the AD Agent installation.
These permissions are required for the installation process only and can be removed afterwards.
Follow these steps to enable the permissions:
Open Administrative Tools and select Local Security Policy.
Navigate to Local Policies > User Rights Assignment, and select Allow log on locally.
In the window that opens, add the new user created for the remote AD. Then, click OK.
Navigate to Local Policies > User Rights Assignment, and select Log on as a service. Then, add the new user created for the remote AD and click OK.
The user should have the appropriate search permissions (read properties, group memberships, etc.). These permissions are granted for each domain user by the default policy. For example:
 |
The user should have reset password permissions for the required scope (domain, OU, etc.). Follow these steps to configure the required parameters:
Open Active Directory Users and Computers. Then, right click on the domain name and select Delegate Control.
The Delegation of Control wizard opens.
On the User or Groups screen, add the required user.
On the Tasks to Delegate screen, select the Reset user passwords and force password change at next logon checkbox.
To close the wizard, click Finish.
The user should have read/write lockoutTime permission for the required scope (domain, OU, etc.). Follow these steps to configure the required parameters:
Open Active Directory Users and Computers. Then, right click on the domain name and select Delegate Control.
The Delegation of Control wizard opens.
On the User or Groups screen, add the required user.
On the Tasks to Delegate screen, select the Create a custom task to delegate radio button. Then, click Next.
Select the 2nd option, which is Only the following objects in the folder. Select User objects in the list, and click Next
On the Permissions screen, select the following checkboxes:
Property-specific
Read lockoutTime
Write lockoutTime
To close the wizard, click Finish.
Follow these steps to grant the user the required permissions for the Remote AD:
Open Active Directory Users and Computers and navigate to Users.
Right-click on the RemoteAD user and select Properties.
From the RemoteAD Properties dialog, select the Security tab. Then, at the bottom of the tab, click Advanced.
In the Advanced Security Settings for RemoteAD dialog, select the user (Principal) and click Add.
In the Permission Entry for RemoteAD dialog, select the following permissions:
List Content
Read permission
Reset password
Read lockoutTime
Write lockoutTime
To save your settings, click OK.
List / Read AD deleted objects container
Follow these steps to grant list and read permissions to the Active Directory deleted objects container. For further information, please refer to this article.
Log on using a user account that is a member of the Domain Admins group.
Click Start and navigate to All Programs >ADAM > ADAM Tools Command Prompt.
At the command prompt, enter a command similar to the example below.
When typing the command, use the name of the deleted objects container for your domain.
dsacls "CN=Deleted Objects,DC=Contoso,DC=com" /takeownership
Each domain in the forest has its own deleted objects container. The output displayed should be similar to that shown in the following example:
