Active Directory Connection

Active Directory uses a Lightweight Directory Access Protocol (LDAP) based authorization. By linking your Active Directory account with Hire2Retire, you can authorize RoboMQ to perform operations to your Active Directory Domain Controller.

Hire2Retire product supports employee operations of onboarding, updating, termination, rehire and leave in Active Directory. Thus, the user account you use to establish the connection must satisfy one of the following criteria:

• Belong to the security group "Domain Admin".
• Set up delegate control of this user under the target Organization Units (OU).

Create a Connection

You can connect to your On Premise Active Directory using two methods

Figure 1. Connection types for Active Directory

1. P2P VPN
2. On-Premise Docker Agent

P2P VPN

Hire2Retire requires the following details to create a connection to your Active Directory.

• Connection Name - A user defined nomenclature for your connection. By default, the connect name is "Connection-Directory Service", you can change the name as per your preferences.
• Host - The host name is the IP address of your Active Directory Server.
• Port - The TCP/IP port on which the Active Directory server is listening. Hire2Retire will only establish the LDAP connection with your SSL port. (The default is 636)
• Base DN - It is a collection of objects that Hire2Retire will access within an Active Directory network. An object can be a single user, a group of users or a hardware component, such as a computer or printer. Each base DN holds a database containing object identity information. It should be given in the format "DC=example-domain,DC=com"
• Username - The username to access the Active Directory server. Please make sure it belongs to the security group "Domain Admin" and has delegated control to target Organization Units (OU).
• Password - The Password to access the Active Directory server.

Figure 2. Active Directory Connection Set Up Page

Figure 3. Active Directory Connection Set Up Page for Multi-Domain Controller

If you are configuring a connection with a multi-domain controller setup, you can provide host values for each domain controller in your AD along with their respective base DN and port. You can also provide comma separated list of IP/host addresses for each domain controller.
By checking the 'Use Global Catalog' checkbox, you can enable the Global Catalog (GC) for your Active Directory connection, which facilitates efficient searches for user and group information across multiple domains.

On-Premise Docker Agent

Your application, database, or identity server might be deployed within your data center without public access. Hire2Retire “On-Premise Docker Agent” provides a secure way to access the identity management server located behind your firewall without the need to open ports in the firewall or establish a VPN tunnel. On-Premise Docker Agent can be installed easily behind the firewall after which it can communicate with the workflow deployed.

Active Directory On-Premise Service Connection

Hire2Retire requires the following details to create a OnPremise Service Connection

• Connection Name - A user defined nomenclature for your connection. By default, the connection name is "Connection-OnPremise Service", you can change the name as per your preferences.
• Host - The host name is the IP address of your Active Directory Server.
• Port - The TCP/IP port on which the Active Directory server is listening. Hire2Retire will only establish the LDAP connection with the SSL port. (The default is 636)
• Base DN - It is a collection of objects that Hire2Retire will access within an Active Directory network. An object can be a single user, a group of users or a hardware component, such as a computer or printer. Each base DN holds a database containing object identity information. It should be given in the format "DC=example-domain,DC=com"
• Public key of RSA key pair - RSA public key which will be used to encrypt the config file. To know the detailed steps to generate RSA key pair.

Figure 4. Active Directory On-Premise Service Connection

Figure 5. Active Directory On-Premise Service Connection for Multi-Domain Controller

If you are configuring a connection with a multi-domain controller setup, you can provide host values for each domain controller in your AD along with their respective base DN and port. You can also provide comma separated list of IP/host addresses for each domain controller.
By checking the 'Use Global Catalog' checkbox, you can enable the Global Catalog (GC) for your Active Directory connection, which facilitates efficient searches for user and group information across multiple domains.

After filling in the credentials you need to clicks on the "link account" button. After account is successfully linked, follow the Instructions given below to setup Active Directory On-Prem Docker Agent.

Figure 6. Instructions to set up On-Prem Docker Agent

Instructions to set up On-Prem Docker Agent

1. Before you start installing the software, ensure you have Docker and OpenSSL on your server.
   Try running docker info on command line interface of your server, if docker is installed, you should get a error free response.
   If you don't have Docker and OpenSSL installed, don't worry! Follow these guides Docker, and OpenSSL for setting them up before we proceed with the installation. Docker helps run the agent on your server in an isolated environment, to avoid conflicts. OpenSSL ensures your data stays safe by encrypting and decrypting files, keeping your information private.
   

2. Start Docker on your server. This is necessary for the installation process.

3. Download the On-Premise installation package from the connection page as shown below, which contains the setup files needed to install and run the agent.

   

   Figure 7. Instructions to set up On-Prem Docker Agent

4. Unzip the installation package after it's downloaded. Inside, you'll find three files:

   • config.enc
   • run.sh
   • secrets.enc

   Before running any commands, make sure you're in the folder where you extracted the installation files.

5. Open command line interface with admin privileges on your server. For Windows Operation System it will be present as command-prompt and for MacOS and linux OS it will be present as terminal.

6. Run sudo bash ./run.sh [ path to private key ] [ -p passphrase ] [ -n number of onprem-agent instance ] [ --username username]
   Make sure to provide all the options to the command in the order they are mentioned.

   • sudo bash ./run.sh : Starts a new bash shell for current user with the security privilege of root user.
   • path to private key (REQUIRED) -- Path to user's private key. It should always be provided at first position.
   • -p (OPTIONAL) : Passphrase provides an additional layer of security by encrypting your RSA private key.
   • -n (OPTIONAL) : Number of onprem-agent replicas required. If not provided, number of replica by default is 1.
     If you re-run the script (run.sh) all the running onprem-agent instances will be stopped and deleted and the script will start with the new number of instances provided.
   • --username (REQUIRED) : Admin username to access the Active Directory server.

   • -h or --help : When provided it will display the help text for the script.

     Example:

     1. sudo bash ./run.sh /Users/JohnSnow/.ssh/id_rsa --username admin@example.com

     2. With passphrase :

        sudo bash ./run.sh /Users/JohnSnow/.ssh/id_rsa secret@16548 --username admin@example.com

     3. With number of docker containers :

        sudo bash ./run.sh /Users/JohnSnow/.ssh/id_rsa -n 1 --username admin@example.com

     4. With all the options :

        sudo bash ./run.sh /Users/JohnSnow/.ssh/id_rsa secret@16548 -n 2 --username admin@example.com

   
   Run docker ps on your server to check if the agent is up and running.
   Some useful docker commands:

   Command	Usage
   docker ps	list all the running containers
   docker ps --all	list all the containers, including stopped containers
   docker logs [ container name ]	It will fetch logs from a specified container
   docker rm [ container name ]	remove a container

7. After set up of installed package , click on the "Verify Connection" button.

   

   Figure 8. Verify Connection button

Once the On-Premise Docker Agent is up and running with connection verification, user can continue to configure the workflow by clicking on "Configure Workflow" button.

Figure 9. Configure Workflow button

Instructions to set up On-Prem Windows executable service

1. Download the On-Premise installation package from the connection page, as shown below, which contains the setup files needed to install and run the agent.

   

   Figure 10. Instructions to set up On-Prem executable service

2. Unzip the installation package after it's downloaded. Inside, you'll find five files:

   • config.enc
   • run.bat
   • secrets.enc
   • decrypt.bat
   • stop.bat

   Before running any commands, make sure you're in the folder where you extracted the installation files.

3. Open powershell terminal with admin privileges on your Windows server.

4. Run ./run.bat [ path to private key ] [ -p passphrase ] [ --username username]
   Make sure to provide all the options to the command in the order they are mentioned.

   • path to private key (REQUIRED) -- Path to user's private key. It should always be provided in the first position.
   • -p (OPTIONAL) : Passphrase provides an additional layer of security by encrypting your RSA
   • --username (REQUIRED) : Admin username to access the Active Directory server.

   • -h or --help : When provided, it will display the help text for the script.

     Example:

     1. ./run.bat \Users\JohnSnow\.ssh\id_rsa --username admin@example.com

     2. With passphrase :

        ./run.bat \Users\JohnSnow\.ssh\id_rsa -p secret@16548 --username admin@example.com

   
   Run 'Get-Service -Name "onprem*"' on your server to check if the agent is up and running.
   

5. After set up of installed package, click on the "Verify Connection" button.

   

   Figure 11. Verify Connection button

Once the On-Premise Agent is up and running with connection verification, user can continue to configure the workflow by clicking on "Configure Workflow" button.

Figure 12. Configure Workflow button

How to stop the running On-Premise agent

When the flow is paused or deleted, user can stop the agent by running the stop.bat script present in the same package. Run the below command in the powershell terminal opened in the downloaded on-prem package directory.

$ ./stop.bat

Troubleshooting On-Premise Agent

This section provides steps to troubleshoot common issues that may occur while running the On-Premise Agent.

Troubleshooting on Windows

To view the logs of the running On-Premise Agent service, follow the steps below:

Windows EXE-based setup

1. Open a PowerShell terminal with administrator access.
2. Run the following command to view the logs:

Get-Content C:\config\<connectionName>error.log -wait

Replace the <connectionName> with your connection name from the connection page.

1. You should now see the logs of the running service.

   

   Figure 13. logs of the running On-Premise agent

Docker-based Windows (legacy setup)

1. Open a Powershell Terminal.
2. Run the following command to view the logs of a specific container:

$ docker ps

Figure 14. Docker Command to list running container

$ docker logs -f <container_id_or_name>

Example: docker logs -f 733e33bfe48b

Troubleshooting on Linux

To view the logs of the running On-Premise Agent service, follow the steps below:

1. Open a terminal.
2. Run the below command to see the logs.

$ docker ps

Figure 15. Docker Command to list running container

$ docker logs -f <container_id_or_name>

Example: docker logs -f 733e33bfe48b

Common errors that may occur

1. Incorrect Password Entered

   • If the provided password or passphrase is incorrect, the logs will display an authentication failure similar to the example below:

   

   Figure 16. Incorrect Password Entered

   Possible Cause:

   • The AD Service Account or RSA private key passphrase entered is incorrect.

   Resolution:

   • Verify that the credentials entered during installation are correct.
   • Re-run the installation command with the correct password/passphrase.

2. Incorrect or Missing Passphrase for Private Key

   • If the RSA private key used during setup is encrypted with a passphrase and it is not provided, or if the passphrase entered is incorrect, the setup process will fail, and the logs will show decryption errors.

   
   

   Figure 17. Logs showing incorrect or missing passphrase error

   Possible Cause:

   • The -p flag was not included while running the setup command.
   • The passphrase entered for the RSA private key is incorrect.
   • The private key file being referenced does not match the public key uploaded to Hire2Retire.

   Resolution:

   • If a passphrase was configured when generating the RSA key pair, include it during setup using the -p flag.

   Example:

   sudo bash ./run.sh /Users/JohnSnow/.ssh/id_rsa -p mypassphrase --username admin@example.com

3. Access is Denied Error (Windows).

   • If you encounter an Access is denied error during installation or execution of the agent, it typically indicates that the service or command does not have permission to access the required files or directories.

   
   

   Figure 18. Logs showing directory permission issue

   Possible Cause:

   • The installation files were extracted to a protected directory (e.g., C:\Program Files, C:\Windows, or another restricted path).
   • SSH private keys were created or stored in a location inaccessible to the current user.
   • The command was run from a directory requiring elevated privileges.

   Resolution:

   • Create SSH keys in the default user folder
   • Extract the downloaded ZIP file into the user’s default folder
   • Run PowerShell or Command Prompt as Administrator before executing the setup command.
   • Ensure that the current user or service account has Read and Execute permissions on all files in the extracted directory.

   💡 Tip: Avoid running the installation from Downloads, Desktop, or shared folders, as permissions can vary by organization policy.

4. Missing or Invalid SSL Certificate

   • If the SSL certificate used for secure communication is missing, expired, or invalid, the agent will fail to connect securely over LDAPS.

   

   Figure 19. Logs showing directory permission issue
   Possible Cause:
   • The .pem certificate was not installed.
   • The certificate has expired.

   Resolution:

   • Verify that the correct certificate is installed on the server.
   • Ensure the certificate validity period has not expired.
   • Follow this guide to create and install one.

5. Permissions Are Too Wide or Open Error

   When the On-Prem Docker Agent package is copied to another location and the run.bat command is executed, you may encounter an error stating that permissions are too wide or open.

   This occurs when the On-Prem Agent folder or its files have incorrect access control permissions, preventing the agent from running securely.

   
   

   Figure 20. Logs showing "Permissions are too wide or open" error

   Possible Cause:

   • The On-Prem Agent folder or its subfiles do not have the correct user-level permissions.
   • The current user executing the script does not have ownership or inherited access rights to the folder.
   • The folder was copied from another system or drive where the permissions were not retained properly.

   Resolution:

   • Navigate to the folder where the On-Prem Agent package was extracted.
     Example:
   • Right-click the folder → Properties → Security → Advanced.
   • Ensure that the current Windows user (or the service account running the agent) has both Read and Write permissions on the folder and all files within it.
   • Enable inheritance so that these permissions propagate to all subfolders and files.
   • Apply the changes and re-run the setup command: .\run.bat <path_to_private_key> --username <service_account>

💡 Tip: Always extract the On-Prem Agent package inside your user’s directory (e.g., C:\Users\username) to ensure proper permission inheritance and avoid access-related errors.