Skip to content

Set Up H2R On-Prem Agent for Integration

Pre-Requisites

Linux

Supported Platform CPU RAM Disk Space
Debian
Fedora
Red Hat Enterprise Linux (RHEL)
Ubuntu		 2 Core CPU 4 GB 32 GB

Windows

Supported Version CPU RAM Disk Space
Server 2019/2022 2 Core CPU > 4 GB 32 GB
Windows 10/11 2 Core CPU > 4 GB 64 GB
  • To ensure uninterrupted processing of user records by Hire2Retire, we recommend configuring the service account password used by the on-premise agent with Never Expire password policy.
  • Outbound Port 443 (HTTPS) should be open on your firewall or network.
  • Ensure a valid SSL certificate is installed on your Active Directory server. If the SSL certificate is not present, follow this guide to create and install one.

How to install on Linux?

Using APT/YUM/etc. to install and verify OpenSSL and Docker

Before you start installing the software, ensure you have Docker and OpenSSL on your server.
To check whether docker is installed, open command line interface of your server and try running: 

docker info

If docker is installed, you should get an error free response. If not, you can follow below mentioned steps to install it.

Docker Installation Guide for Linux

Docker helps run the agent on your server in an isolated environment, to avoid conflicts.

  • Step 1: Update the package index
sudo apt-get update
  • Step 2: Install required packages
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common

For Red Hat-based distributions (e.g., CentOS, Fedora):

sudo yum install -y yum-utils device-mapper-persistent-data lvm2
  • Step 3: Add the Docker GPG key to the system
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
  • Step 4: Add the Docker repository to the system
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

For Red Hat-based distributions (e.g., CentOS, Fedora):

sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  • Step 5: Update the list of packages and then install Docker
sudo apt-get update
sudo apt-get install docker-ce

For Red Hat-based distributions (e.g., CentOS, Fedora):

sudo yum install docker-ce
  • Step 6: Start the Docker service
sudo systemctl start docker
  • Step 7: Verify Docker Installation
sudo docker run hello-world
  • Step 8: To be able to carry out Docker commands without using sudo, add your user to the docker group
sudo usermod -aG docker $USER

OpenSSL Setup Guide for Linux

OpenSSL ensures your data stays safe by encrypting and decrypting files, keeping your information private.

To verify that OpenSSL is installed on your system, open a terminal or command prompt and run:

openssl version

If OpenSSL is installed, you should see output showing the installed version. If not, you can follow below mentioned steps to install it.

Download OpenSSL

You can download the latest version of OpenSSL from the official website: OpenSSL Downloads. Ensure you download the appropriate version for your operating system.

Installation

  • Step 1: Update the package list
sudo apt-get update
  • Step 2: Install OpenSSL 
sudo apt-get install openssl

For Red Hat-based distributions (e.g., CentOS, Fedora):

sudo yum install openssl

Starting the Hire2Retire On-Prem Docker Agent

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

  2. After filling up the connection information for your OnPremise Active Directory, 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.

    Instructions to set up On-Prem Docker Agent

  3. 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.

  4. 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.

  5. To ensure uninterrupted processing of user records by Hire2Retire, we recommend configuring the service account password used by the on-premise agent with Never Expire password policy.

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

Example: 

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

'username' here refers to your AD Service Account/ Bind Account


To list all the available options that the run.sh script supports, run the following command:

sudo bash ./run.sh --help

bash command output

For '-p': If you have configured passphrase while generating rsa key pair, it will be REQUIRED here.

If the bash command is running successfully, the result of this will look like the following: bash command output

To check if the agent is up and running on your server, run: 

docker ps

If the agent is running, the result to above command must look like following:
docker container list

To verify the connection, follow the instructions.

How to install on Windows?

  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.

    Instructions to set up On-Prem Windows 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 priviliges 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 private key.
    • --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.

    verify button

    Figure 4. Verify Connection button

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

Configure workflow

Figure 5. Configure Workflow button

How to stop the running On-Premise agent

When the flow is paused or deleted, the 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