miniOrange LDAP Gateway

The miniOrange LDAP Gateway is a lightweight bridge that connects your on-premise Active Directory or LDAP server to the miniOrange cloud identity platform. It is installed inside your intranet (typically in the DMZ) and communicates outbound to miniOrange — your LDAP server never needs a public IP.

The gateway supports two distinct use cases:

• User Sync : Syncs users and groups from your AD/LDAP directory to miniOrange cloud through the gateway. No changes are required in the miniOrange cloud console; sync is configured and scheduled entirely within the gateway.
• User Authentication : Authenticates users from miniOrange against your AD/LDAP through the gateway. This requires one additional configuration step in the miniOrange cloud console to point it at the gateway.

Both use cases share a common installation and configuration sequence. This guide walks through the common steps first, then branches into use-case-specific instructions.

Prerequisites

1. Installation & Configuration

1.1. Download and Install the Gateway

Download the installer that matches your operating system:

Installer (Latest Version: 1.6.0)	Supported OS	Download	SHA-256 Checksum
Windows Installer (.exe)	Windows Server 2008+	Download	0fa1d4735a4af56635bde978d0d8ff3ce0e4b24f7fe238615f1fdd743352d6f8
Linux DEB (.deb)	Ubuntu, Debian, Linux Mint	Download	485e2379c3fa37dd62b26b3c5e5d7f8211d07fa765e798c50746db0f37724cd8
Linux RPM (.rpm)	RHEL, Rocky Linux, AlmaLinux, CentOS, Fedora, openSUSE	Download	fa9517c91ad182a03922cb1ccfa5fa36366ae90fb944d732299b7a5040a329fd
ZIP (manual)	Windows & Linux — all distributions	Download	a9e8287c378a35929be6acac6fb6153399fd3f06467a95b80744fbef8e16179a

  

x

Work Email*

Name*

Usecase*

Download

By clicking Download, you agree to our Terms of Service

Follow the instructions for your chosen installation method.

• Windows Installer (.exe)
• Linux Installer (.deb / .rpm)
• ZIP (Manual Install)

Note: The Windows installer bundles OpenLogic JDK 17. If Java 17 is already installed on the system, the bundled JDK installation is skipped automatically.

• Run the downloaded .exe installer as Administrator.
• Follow the on-screen prompts to complete installation.
• The gateway is installed to: C:\Program Files\miniOrange LDAP Gateway
• A Windows service named miniOrange LDAP Gateway is registered and started automatically.
• To manage the service, open Services (services.msc) and locate miniOrange LDAP Gateway.

Note: The DEB and RPM installers bundles OpenLogic JDK 17. No system Java installation is required.

DEB Installer (.deb) is supported on Ubuntu, Debian, and Linux Mint.

Install the downloaded deb package using the following command:

              sudo apt install -y ./miniorange-ldap-gateway.deb
            

RPM Installer (.rpm) is supported on RHEL, Rocky Linux, AlmaLinux, CentOS, Fedora, and openSUSE. Install the downloaded rpm package using the following command:

              sudo dnf install -y ./miniorange-ldap-gateway.rpm
            

After installation, the installer sets up the following paths and files on your system:

• Install path: /opt/miniorangegateway/
• Log directory: /var/log/miniorangegateway/ (symlinked from /opt/miniorangegateway/logs/)
• JVM configuration: /etc/default/miniorangegateway
• Service file: /lib/systemd/system/miniorangegateway.service
• Backup directory: /var/backups/miniorangegateway/

The systemd service miniorangegateway is registered and started automatically on boot. Use these commands to manage it:

              sudo systemctl start miniorangegateway
                sudo systemctl stop miniorangegateway
                sudo systemctl restart miniorangegateway
                sudo systemctl status miniorangegateway
            

Use this method on any Windows or Linux system, including Linux distributions not covered by DEB/RPM.

IMPORTANT: The ZIP package does not bundle Java. You must install Java 17 before proceeding. Earlier versions are not supported.

Installing Java 17 (ZIP method only)

• Windows: Download and install OpenLogic JDK 17 from openlogic.com, then set the JAVA_HOME environment variable to the JDK directory (e.g. C:\Program Files\Java\jdk-17).
• Ubuntu/Debian: sudo apt-get install openjdk-17-jre
• RHEL/Fedora/CentOS: sudo yum install java-17-openjdk

Extracting and Configuring the Gateway

• Extract the ZIP archive. You will get a folder named miniorangegateway-<version> (e.g. miniorangegateway-1.5.0).
• Copy all files and directories from inside the extracted miniorangegateway-<version> folder to:
• Windows: C:\Program Files\miniOrange LDAP Gateway\
• Linux: /opt/miniorangegateway/

The gateway runs on port 8080 by default. To change the port, see Step 1.2 (Optional).

Setting Up the Gateway as a System Service (ZIP Method Only)

On Windows:

• Open Command Prompt as Administrator.
• Run the following command to register the gateway as a Windows service (update the path if you extracted to a different location):

                  sc create "miniOrangeGateway" binPath= "cmd.exe /c \"C:\Program Files\miniOrange LDAP Gateway\bin\catalina.bat start\"" start= auto DisplayName= "miniOrange LDAP Gateway"
                

• Start the service:

                  sc start miniOrangeGateway
                

• Verify the service is running:

                  sc query miniOrangeGateway
                

• To stop the service:

                  sc stop miniOrangeGateway
                

On Linux (systemd):

• Create a unit file:

                  sudo vi /etc/systemd/system/miniorangegateway.service
                

• Paste the following content. Update the JAVA_HOME path to match your Java installation location:

                  [Unit]
                    Description=miniOrange LDAP Gateway
                    After=syslog.target network.target

                    [Service]
                    Type=forking
                    Environment=JAVA_HOME=          # e.g. /usr/lib/jvm/jre
                    Environment=CATALINA_PID=/opt/miniorangegateway/temp/gateway.pid
                    Environment=CATALINA_HOME=/opt/miniorangegateway
                    Environment=CATALINA_BASE=/opt/miniorangegateway
                    Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC'
                    Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'
                    ExecStart=/opt/miniorangegateway/bin/startup.sh
                    ExecStop=/bin/kill -15 $MAINPID
                    User=miniorange
                    Group=miniorange
                    UMask=0007
                    RestartSec=10
                    Restart=always

                    [Install]
                    WantedBy=multi-user.target
                  
                

• Enable and start the service:

                  sudo systemctl daemon-reload 
                    sudo systemctl enable miniorangegateway 
                    sudo systemctl start miniorangegateway
                  
                

1.2. Configure Tomcat Port (Optional)

By default, the gateway runs on port 8080. To change it:

• Navigate to <gateway-directory>/conf/ and open server.xml.
• Locate the line: Connector port="8080" protocol="HTTP/1.1"



• Change 8080 to your desired port number.
• Save the file and restart the gateway service.

After the port change, access the gateway at: http://<server-ip>:<new-port>/miniorangegateway/

1.3. Start the Gateway

• Windows and Linux installer users (DEB/RPM): the gateway service starts automatically after installation. Use the service management commands from Step 1.1 to restart or check status.
• ZIP method users: use the commands from Zip (manual install) .
• Verify the gateway is running by opening the following URL in your browser:

            http://<server-ip>:8080/miniorangegateway/
          

Note: If you configured a custom port in Step 1.2, use that port instead of 8080.

1.4. Log into the Gateway

• Open http://<server-ip>:8080/miniorangegateway/ in your browser.



• Enter the credentials of your miniOrange cloud admin account (the same credentials you use at login.xecurify.com).
• After a successful login, the gateway fetches and stores your miniOrange API key and Customer ID. These are used by the gateway to make API calls to miniOrange (for user sync operations).
• You are redirected to the View LDAP Configurations dashboard.

1.5. Connect the Gateway to Your Directory

This step configures the connection between the gateway and your on-premise AD/LDAP server.

• In the gateway web UI, click the LDAP Management tab from the laft panel and select LDAP Connection.
• Click Add LDAP Connection.



• Fill in the configuration fields as described in the table below.






Field	Description	Example
Configuration Identifier	A unique name for this LDAP configuration.	MyCompany-AD
LDAP Server URL	Hostname and port of your LDAP server.	ldap://myldapserver.domain:389
Bind Account DN	The account used to connect to LDAP. Use UPN or DN format.	admin@domain.com or CN=admin,DC=domain,DC=com
Bind Account Password	Password for the Bind Account.	—
Search Bases	Distinguished name of the OU to search for users.	CN=Users,DC=domain,DC=com
Search Filter	LDAP filter to identify user objects. If using group-based filters, replace <group-dn> with the group DN.	(objectClass=user)
Domain Name	Semicolon-separated list of domain names.	company.com;subsidiary.com
First Name Attribute	LDAP attribute mapped to first name.	givenName
Last Name Attribute	LDAP attribute mapped to last name.	sn
Email Attribute	LDAP attribute mapped to email.	mail
Username Attribute	LDAP attribute mapped to username.	sAMAccountName
Phone Attribute	LDAP attribute mapped to phone number.	telephoneNumber
User Group Attribute	LDAP attribute for group membership.	memberOf
Search Bases for Groups	DN of the OU to search for groups.	CN=Groups,DC=domain,DC=com
Group Search Filter	LDAP filter to identify group objects.	(&(objectCategory=group)(!(cn=admin*)))
Group Name Attribute	LDAP attribute for the group name.	sAMAccountName
LDAP Attribute List	Semicolon-separated list of additional attributes to fetch.	cn;mail;givenName
IdP User Profile Fields Mapping	Maps LDAP attributes to miniOrange user profile fields.	[configure as needed]
Enable Configuration for Sync	Enables or disables this connection for scheduled sync.	Enable if using User Sync use case

• Click Save.

1.6. Test the Directory Connection

• In the gateway web UI, check for the LDAP Connections list.
• Locate your newly created configuration.
• Under the Action column click Select, then choose Test Attribute Mapping from the dropdown.



• Enter the Username and click Test.



• Verify that the test returns the expected user attributes from your directory.

Part 2. Choose Your Use Case

2.1 User Sync Setup

Use this section if your goal is to sync users and groups from your AD/LDAP directory into the miniOrange cloud. Sync is configured and triggered entirely within the gateway web UI — no additional steps are required in the miniOrange cloud console.

1. Configure Sync Settings

• In the gateway web UI, click LDAP Sync under the LDAP Management menu in the left panel. Configure the following fields:

Field	Description
Enable Group Sync	Enable to sync groups from your Active Directory to miniOrange.
Enable User Sync	Enable to sync user accounts from your Active Directory to miniOrange.
Enable User Group Membership Sync	Enable to sync group membership assignments. Note: if Enable Group Sync is disabled but this is enabled, all group assignments for users will be removed in miniOrange.
Enable Import Nested Group	Enable to import and sync nested groups from your Active Directory to miniOrange. Users who are members of child groups will inherit memberships from their parent groups during synchronization.
Exclude Groups in User Sync	When enabled, users under the selected groups will always remain members of those groups. No group de-assignment will occur for these groups during LDAP user sync.
Enable Delete User Sync	Enable to delete users from miniOrange when they are removed from your directory. Use with caution — configure the exclusion list before enabling.
Configure Exclusion List	Select specific users to exclude from deletion sync. Recommended to protect admin accounts.
Sync Enable/Disable Status	When enabled, user enable/disable status changes in Active Directory will be synchronized to miniOrange during user sync.
Sync Locked/Unlocked Status	When enabled, user account lock/unlock status changes in Active Directory will be synchronized to miniOrange during user sync.
Start Time (hh:mm)	Time of day for the first scheduled sync. Any time before the current server time triggers an immediate sync.
Sync Interval (in hrs)	How often the scheduled sync repeats after the first run.

2. Run or Schedule Sync

• After configuring the sync settings, click Save.
• Click the Enable LDAP Sync tab.



• To perform an immediate one-time sync, click Run One-Time Sync.
• To start the recurring scheduled sync, click Enable Scheduled Sync.
• To pause the scheduled sync at any time, click Disable Scheduled Sync.

Part 2.2: User Authentication Setup

Use this section if your goal is to allow miniOrange to authenticate users against your on-premise AD/LDAP through the gateway. This requires one additional configuration step in the miniOrange cloud console.

1. Configure Gateway URL in miniOrange Cloud

This step tells miniOrange where to find your gateway so it can forward authentication requests to your AD/LDAP server.

• Login to miniOrange dashboard from the Admin Console.
• From the left side menu, click on Identity Providers >> Add Identity Provider.



• Select AD LDAP as the identity provider type.
• On the Basic tab, select Store LDAP Configuration On Premise.
• In the LDAP Server URL field, set the URL prefix to http:// (or https:// if SSL is configured) and enter your gateway server's IP address or hostname in the Gateway URL field.
• Fill in the Display Name, Directory Type, and Domain Name fields as appropriate.



• Click Save.

2. Test the Cloud-to-AD Connection

• In the miniOrange Admin Console, go to Identity Providers.
• Locate the AD LDAP identity provider you just configured.
• Click three dots under the Actions column, then choose Test Connection and enter AD user credentials.



• A successful test confirms that miniOrange can reach your AD/LDAP server via the gateway.
• Again click three dots under the Actions column, then choose Test Attribute Mapping and enter username of AD user.
• Verify that the test returns the expected user attributes from your directory.

Optional Configuration

Setup LDAPS (Secure LDAP)

Configure this if your AD/LDAP server uses Secure LDAP (port 636) instead of standard LDAP (port 389).

Important: The gateway must be running with administrator/root privileges for this step.



• In the gateway web UI, click the LDAP Management tab from the laft panel and select Setup LDAPs.
• Fill in the following fields.

Field	Description	Example
Host	Hostname of your LDAP Domain Controller.	ldap.company.com
Port	Secure LDAP port.	636
Alias	Name used to store the certificate in the Java TrustStore.	myldap-cert
Password	Password for the Java TrustStore.	changeit (default)



• Click Fetch Certificate. Confirm you see a success message.



• Restart the gateway service.

Setup HTTPS for the Gateway Web UI

By default, the gateway web UI runs over HTTP. Configure HTTPS if your security requirements demand it. Before you begin, determine which applies to you:

• I have a CA-signed certificate → Follow the Tomcat SSL installation guide at https://www.thesslstore.com/knowledgebase/ssl-install/tomcat-ssl-installation/ and then skip the "Generate a Self-Signed Certificate" step below. Continue from "Configure the HTTPS Connector in server.xml".
• I don't have a CA-signed certificate → Follow all steps below starting with "Generate a Self-Signed Certificate".

Generate a Self-Signed Certificate (skip if you have a CA certificate)

• Open Command Prompt (Windows) or Terminal (Linux) as Administrator/root.
• Navigate to the <JAVA_HOME>/bin/ directory and create a certs/ subdirectory.
• Run the following command to generate a keystore:

            keytool -genkey -alias <ALIAS> -keyalg RSA -keystore <JAVA_HOME>/bin/certs/keystore.jks
          

Configure the HTTPS Connector in server.xml

• Navigate to the conf/ directory inside your gateway installation:
• Linux: /opt/miniorangegateway/conf/
• Windows: C:\Program Files\miniOrange LDAP Gateway\conf\
• Open server.xml and add the following connector element inside <Service name="Catalina">:

            <Connector
  port="443"
  protocol="org.apache.coyote.http11.Http11NioProtocol"
  SSLEnabled="true"
  maxThreads="150"
  scheme="https"
  secure="true">
  <SSLHostConfig hostName="_default_">
    <Protocols>
      TLSv1.2,TLSv1.3
    </Protocols>
    <Certificate
      certificateKeystoreFile="<JAVA_HOME>/bin/certs/keystore.jks"
      certificateKeystorePassword="<KEYSTORE_PASSWORD>"
      certificateKeyAlias="<ALIAS>"
      type="RSA"
    />
  </SSLHostConfig>
</Connector>
          




Assign a Hostname to the Server

• Edit the hosts file and add the following line:
• Windows: C:\Windows\System32\drivers\etc\hosts
• Linux: /etc/hosts

            127.0.0.1 <newhostname>
          

• In server.xml, find <Engine name="Catalina" defaultHost="localhost"> and replace localhost with <newhostname>.
• Find the <Host> element and replace name="localhost" with name="<IP Address or DNS>".
• Restart the gateway service.
• Access the gateway at: https://<newhostname>/miniorangegateway/

Important: After configuring HTTPS, remember to update the Gateway URL in the miniOrange cloud console (Part 2, Step 2.2) to use to use https:// instead of http://.

Upgrade Guide

Follow the instructions for your installation method.

Windows / Linux Installer Upgrade

The installer handles the upgrade automatically and preserves your configurations.

• Download the latest installer for your platform (see Step 1).
• Stop the gateway service.

            # Linux: sudo systemctl stop miniorangegateway
# Windows: stop the service via services.msc
          

• Run the new installer over the existing installation (do not uninstall first).
• Start the gateway service.

            # Linux: sudo systemctl start miniorangegateway
          

• The following files are automatically preserved during upgrade:
• application.properties — your gateway configuration is retained
• /etc/default/miniorangegateway (Linux) — your JVM settings are retained

Important: SSL configuration (server.xml) is NOT automatically restored after upgrade. The installer backs up your existing server.xml to /var/backups/miniorangegateway/server.xml (Linux) before replacing it. If you have SSL configured, re-apply your server.xml SSL settings manually after the upgrade.




ZIP Manual Upgrade

Choose the upgrade type based on what you need to update:

• Upgrade the gateway application only — use this when a new gateway version is released, but Tomcat does not need to be updated.
• Upgrade the entire installation — use this when both the gateway and Tomcat need to be updated.

Option A — Upgrade the Gateway Application Only

• Download the latest ZIP package (see Step 1).
• Stop the gateway service.
• Navigate to your gateway installation directory and take a full backup of the webapps/miniorangegateway/ folder.
• Extract the new ZIP and copy the webapps/miniorangegateway/ folder from it into your installation, replacing the existing one.
• Restore your backed-up application.properties to:
• Linux: /opt/miniorangegateway/webapps/miniorangegateway/WEB-INF/classes/application.properties
• Windows: C:\Program Files\miniOrange LDAP Gateway\webapps\miniorangegateway\WEB-INF\classes\application.properties
• Start the gateway service.

Option B — Upgrade the Entire Installation (Gateway + Tomcat)

• Download the latest ZIP package (see Step 1)
• Stop the gateway service.
• Take a backup of the following files before proceeding:
• application.properties (path as above)
• conf/server.xml — only if you have made changes to it (e.g. SSL configuration, custom port)
• Extract the new ZIP and copy all contents into your installation directory, replacing all existing files:
• Linux: /opt/miniorangegateway/
• Windows: C:\Program Files\miniOrange LDAP Gateway\
• Restore your backed-up application.properties to:
• Linux: /opt/miniorangegateway/webapps/miniorangegateway/WEB-INF/classes/application.properties
• Windows: C:\Program Files\miniOrange LDAP Gateway\webapps\miniorangegateway\WEB-INF\classes\application.properties
• If you backed up server.xml, re-apply your changes to the new conf/server.xml manually.
• Start the gateway service.

Frequently Asked Questions - v1.4.0

            Force update all users on every sync: send.force.updates=true  
# Default (only update on change): send.force.updates=false