How To Connect

Connect Zluri with Microsoft Active Directory

Prerequisites

• Admin Access to Zluri
• Access to Active Directory — server hostname/IP, admin Bind DN credentials, and Base DN
• Docker 20.10+ and Docker Compose v2 (or v1) installed on a server in your network
• .pem certificate for SSL/TLS (optional — recommended for LDAPS on port 636)
• Network connectivity — from the Docker host to your AD server (port 389 or 636) and outbound HTTPS to Zluri's servers

Use Cases Supported

• Optimised for single-directory or single-domain environments (not for forests).
• Runs on any OS — Linux, Windows, or macOS (via Docker).
• Supports both LDAP (port 389) and LDAPS (port 636) connections.
• The connector runs as a Docker container and persists across restarts. It does not depend on an active user session.

Part 1: Set Up the Connection in Zluri

Step 1 — Select Scopes

1. Open the Integrations Catalog in Zluri, search for "Microsoft Active Directory", and click + Connect.

2. Review the scopes for the integration. You can click the down-arrow button to the right of a scope to learn what it does.

   Default scopes (automatically added):

   • Read Groups (READ · Discovery)
   • Read Organizational Units (OUs) (READ · Discovery)
   • Read Users (READ · Discovery)

   Optional scopes (not added by default):

   • Scopes for Workflows — enables write-back actions like creating users, modifying group memberships, etc. Click View All to see all workflow scopes and click the + icon to add them.
   • All scopes — adds every available scope. Click View All to review.

3. Click Continue to proceed.

Note: If you need assistance, click the "Need help connecting this integration?" link for guided setup support.

Step 2 — Download Agent

1. Enter an Agent name (mandatory and unique — e.g., "Zluri Dev Test"). The info icon (ⓘ) next to the field label provides naming guidance.

2. Under Download (Version - 0.1.5), you'll see the description: "Creates a secure, outbound-only link to Active Directory. Easy to install, encrypted, no inbound firewall needed."

3. Click the Package button to download the connector package. This contains the Docker image archive (.tar.gz) and docker-compose.yml file needed for deployment.

4. Optionally, review the Installation guide and System requirements links for reference.

5. Click Continue to proceed to the next step.

Step 3 — Connect Agent

1. The Installation Token is displayed in the text field — a long JWT token. Click the copy icon (📋) to the right of the token field to copy it.

2. Note the message: "Token expires in 30 minutes". Keep the token somewhere safe — you'll need it when registering the agent in the connector's Web UI.

3. Below the token, you'll see the status indicator: "Agent not connected." This will update to "connected" once you complete all setup steps (Parts 2–5).

📘

Important: Do not close this page. You can return to it to check the connection status. If the token expires, navigate to Integrations > Microsoft Active Directory settings to generate a new one.

Part 2: Deploy the Connector (Docker)

Transfer the downloaded connector package to the server where you want to run the connector. Unzip it. You need the Docker image archive (.tar.gz) and the docker-compose.yml file.

Step 1 — Load the Docker Image

Navigate to the directory containing the downloaded files and open terminal in folder to load the image:

docker load < zluri-partner-ldap-connector-v1.0.0.tar.gz

You should see the output:

Loaded image: zluri-partner-ldap-connector-v1.0.0:latest

Step 2 — Start the Connector

Run Docker Compose to start the connector:

docker compose up -d

You'll see the container being created and started:

[+] Running 5/5
 ✔ Volume "..._connector-certs"   Created
 ✔ Volume "..._connector-logs"    Created
 ✔ Volume "..._connector-uploads" Created
 ✔ Volume "..._connector-data"    Created
 ✔ Container zluri-partner-ldap-connector-v1.0.0  Started

Verify the container is running:

docker ps

Part 3: Create Your Account & Register the Agent

Open a browser and navigate to:

https://<SERVER_IP>:<PORT>

Example: https://127.0.0.1:5001

Note: Your browser will show a certificate warning for self-signed certs — accept the exception to proceed. HTTPS is always on; a self-signed certificate is auto-generated on first boot.

Step 1 — Create Your Account

On first access, you'll see the "Create your account" page with the subtitle: "Get started with your Active Directory Integration."

Fill in the following fields:

Click Create Account to proceed.

Tip: If you already have an account, click the "Already have an account? Sign In" link at the bottom.

Step 2 — Register the Agent with Zluri

After signing in, you'll see the Dashboard with a yellow banner: "Agent registration required" — "Enter your Zluri API token below to register this agent. You won't be able to configure AD or Zluri instances until this is complete."

The dashboard shows:

• Connection Status: Not Registered
• Heartbeat: Inactive
• Polling Time: Unknown

To register:

1. In the Register Agent section, locate the Zluri API Token field.
2. Paste the Installation Token you copied from the Zluri UI in Part 1, Step 3.
3. You'll see a hint: "You can find this token in Overview > Integrations > Microsoft Active Directory."
4. Click Register Agent.

Once registration succeeds, you'll see a green "Agent registered successfully!" toast notification. The dashboard will update to show:

• Connection Status: Registered
• Heartbeat: Active (with interval shown, e.g., 60s)
• Polling Time: 1 min
• Agent Status badge in the top-right changes to Agent Active (green)

The Zluri API Token is now masked (e.g., z|ur1_a|_p1 ••••••••••••) for security.

Part 4: Add a Directory Connection

Now you need to connect the agent to your on-premises Active Directory server.

Step 1 — Navigate to Directory Connections

Click Directory Connections in the left sidebar. You'll see the "Setup Active Directory Connection" page prompting you to add your first connection.

Click + Add Directory Connection.

Step 2 — Enter Connection Settings

The "Add Active Directory Connection" form has three sections. Start with Connection Settings:

📘

Recommended Setup: Secure Port 636

Use Secure Port 636 with LDAPS and SSL/TLS certificates.

• Reason: Without LDAPS on 636, the "Add user to OU" workflow action will create a disabled user without a password.
• When using Port 636, the user is created with a password and an enabled account.

How to Find Your Bind DN

1. Open Active Directory Users and Computers (ADUC) on your AD server.
2. Enable View > Advanced Features.
3. Navigate to the user account you want to use as the service account.
4. Right-click the user > Properties > Attribute Editor tab.
5. Look for the distinguishedName attribute — this is your Bind DN.
   • Example: CN=Administrator,CN=Users,DC=example,DC=com

Step 3 — Configure Search Base & Access Control

Scroll down to the Search Base & Access Control section. This controls which parts of your AD are synced and with what permissions.

Access Mode Rules (explained at the top of the section):

• Read-Only (R): Blocks ALL write operations.
• Read-Write (RW): Allows sync and write actions.

Default Search Base

Include/Exclude Filters for Root Search Base

Click "Show & Manage Access Filter" to expand the filter panel. These regex-based filters control which users and groups are synced from the root search base:

OU-Specific Overrides

For granular control over specific OUs, click + Add OU Override to add rules that override the default search base settings for particular OUs. Each override lets you set a different baseDN, scope, access mode, and filters.

OU Container Overrides

If your AD stores objects in the built-in OU containers, you can define overrides for those containers. For example, the default CN=Users,CN=dc=zluri,dc=dev container with Subtree scope and Read-Write (R) access. Click + Add OU Container to add more.

Step 4 — Configure Attributes to Fetch

Scroll down further to the Attributes section. This controls which LDAP attributes the connector retrieves during sync.

User Attributes to Fetch — Shown as tags. The required/immutable attributes are pre-loaded (shown in blue tags). You can add additional attributes by typing in the input field and clicking + Add.

Default user attributes include: sn, sAMAccountName, userPrincipalName, userAccountControl, mail, givenName, proxyAddresses, cn, memberOf, whenChanged, etc.

Group Attributes to Fetch — Similarly shown as tags. Default group attributes include: cn, member, groupType, objectClass, distinguishedName, memberOf, etc.

Note: The connector always fetches a minimal, non-removable set of core attributes (dn, cn, objectClass, etc.) even if they're not listed here. You cannot accidentally remove required attributes.

Step 5 — Test & Save

At the bottom of the form, you'll see the Test & Save bar:

1. Click Test Connection to verify the agent can reach your AD server with the provided credentials and settings.
2. Once the test passes, click Test & Save to save the directory connection.

Step 6 — Directory Connection Saved

After saving, you're taken to the Directory Connections list view. Your new connection appears with:

A green "Directory Connection saved successfully!" toast confirms the save.

Part 5: Configure the Zluri Integration

With the AD connection established, you now need to create a Zluri Integration — this maps AD attributes to Zluri fields and sets the sync schedule.

Step 1 — Navigate to Zluri Integrations

Click Zluri Integrations in the left sidebar. You'll see the "Configure Your Zluri Instance" page with the message: "Map AD attributes to Zluri fields and set your sync schedule to keep data in sync."

Click + Add Zluri Instance.

Step 2 — Create the Integration

The "Zluri Integration & Mapping" form opens. Fill in the top section:

Step 3 — Configure User Attribute Mapping

Expand the User Attribute Mapping section (click the header). You'll see the message: "Map Zluri user fields to AD user attributes."

The mapping is displayed as two columns:

Each row has a ✕ button to remove the mapping. Click + Add Custom Mapping at the bottom to define additional field mappings.

A badge in the section header shows the count (e.g., "13 attributes available") indicating how many AD attributes are available for mapping.

You can toggle between ZLURI FIELDS and AD ATTRIBUTES (LDAP NAMES) tabs at the top of the mapping section.

Step 4 — Configure Group Attribute Mapping

Expand the Group Attribute Mapping section similarly. Map Zluri group fields to AD group attributes. The setup is analogous to user mapping.

Step 5 — Set Sync Schedule

In the Sync Settings section at the bottom of the form:

Step 6 — Save the Integration

Click Save to create the integration. You'll be taken to the Zluri Integration Configurations list view showing:

A green "Zluri integration saved successfully!" toast confirms the save.

Part 6: Verify the Connection in Zluri

Go back to the Zluri platform (the browser tab from Part 1). The Step 3 panel will now show:

• A green shield icon with a checkmark
• "Agent connected securely"
• "Sync started. Data will auto-sync every few hours. Check status in Integration settings."

All three steps show green checkmarks — Select Scopes ✅, Download Agent ✅, Connect Agent ✅.

Your Microsoft Active Directory is now fully connected to Zluri.

HTTPS / TLS Configuration

HTTPS is always on. The connector never starts without a valid certificate.

Self-Signed Certificate (Default)

On first start, if no certificate exists, the container automatically generates a self-signed certificate valid for 10 years. It is stored in the connector-certs Docker volume and persists across container restarts.

The SAN (Subject Alternative Name) of the generated cert includes:

• The bind IP you supplied ($HOST)
• 127.0.0.1
• DNS:localhost

Replace with a CA-Signed Certificate

To replace the auto-generated certificate with your own CA-signed certificate:

docker cp /path/to/your-cert.pem zluri-partner-ldap-connector-v1.0.0:/certs/cert.pem
docker cp /path/to/your-key.pem  zluri-partner-ldap-connector-v1.0.0:/certs/key.pem
docker restart zluri-partner-ldap-connector-v1.0.0

The container prints the loaded certificate's subject and expiry date on every start so you can confirm which cert is in use.

Persistent Data (Docker Volumes)

All volumes survive docker restart, docker stop/start, and even docker rm + docker run (as long as the named volumes are not explicitly removed).

Useful Management Commands

📘

While running these actions, make sure you're in the same directory folder where the agent is OR open the terminal at folder where the package is un-zipped.

# Stop the connector (keeps volumes)
docker compose down

# Stop and remove all data (WARNING: deletes all data)
docker compose down -v

# Restart
docker compose restart

# View logs
docker logs -f <container_id>

# Open a shell inside the container
docker exec -it <container_id> bash

# Check MySQL inside the container
docker exec -it <container_id> mysql -u root -p zluri_ldap_connector

Problems connecting? Feel free to submit a ticket or contact us directly at [email protected].