Beem LDAP Agent Deployment Guide

System Requirements ​

1. Hardware Requirements ​

• The resources required depend on the size of your directory (Total number of Users).

2. Software Requirements ​

• Operating System: Linux (CentOS 7+, Ubuntu 18.04+, Debian 10+), Windows Server, or macOS.
• Java Runtime Environment (JRE): Java 11 or higher (OpenJDK 11 recommended).

3. Network Requirements ​

• The agent operates in a Pull-based mode (outbound only), which simplifies firewall configuration. It does not require any inbound ports to be opened from the internet.

Installation ​

1. Directory Structure ​

• We recommend creating a dedicated directory for the agent (e.g., /opt/beem-ldap-agent).

/opt/beem-ldap-agent/
├── bw-ldap-agent.jar       # The main application JAR (Fat JAR)
├── conf/
│   └── ldapAgent.yml       # Logic configuration file
├── logs/                   # Application logs (auto-generated)
├── data/                   # application datas (auto-generated)
└── start.sh                # Startup script

2. Deployment Steps ​

1. Create Directory: mkdir -p /opt/beem-ldap-agent/conf
2. Copy Artifacts: Upload bw-ldap-agent.jar to the directory.
3. Prepare Config: Copy the template ldapAgent.yml to the conf directory.

Configuration ​

• The agent configuration consists of Local Settings (connectivity) and Remote Settings (sync rules, managed via Beem Admin Console).

Local Configuration (conf/ldapAgent.yml) ​

• Edit conf/ldapAgent.yml to configure the connection to Beem.

• Please follow the format and add the server urls, bindDN, bindPassword and baseDN as below.

agent_settings:
  # The Beem Server API Endpoint provided by your administrator
  server_url: https://open.beem.sa
  
  # OAuth2 Client Credentials
  client_id: YOUR_CLIENT_ID
  # Oauth2 Client Secret
  client_secret: YOUR_CLIENT_SECRET
  
  # Set to true to enable verbose logging for debugging
  debug: false
  
ldap_config:
  server_urls:
    # your ldap server 
    - ldaps://xxxx:xxx
  # ldap bind dn
  bind_dn: CN=x,OU=y,DC=z,DC=ad
  # ldap bind password
  bind_password: 'xxxx'
  # ldap search basedn 
  base_dn: DC=xxx,DC=ad

Running the Agent ​

Manual Start (Linux/macOS) ​

• Use the following command to start the agent in the background.

#!/bin/bash
# start.sh for Beem LDAP Agent

APP_HOME=$(pwd)
JAR_NAME="bw-ldap-agent.jar"

# 1. Check if JAR exists
if [ ! -f "$APP_HOME/$JAR_NAME" ]; then
    echo "ERROR: $JAR_NAME not found in $APP_HOME"
    exit 1
fi

# 2. Start the application
# Use 'nohup' to run in background.
# Redirect stdout and stderr to a log file or /dev/null as per guide, 
# but for error detection we might want to peek at logs or just rely on PID check.

echo "Starting $JAR_NAME..."
nohup java -jar "$JAR_NAME" > /dev/null 2>&1 &
PID=$!

# 3. Check if it actually started
# Wait a few seconds to see if the process crashes immediately
sleep 2

if ps -p $PID > /dev/null; then
    echo "$PID" > pid
    echo "SUCCESS: Agent started with PID $PID"
    exit 0
else
    echo "FAILURE: Agent failed to start (Process $PID died)."
    echo "Check logs/ for details."
    exit 1
fi

Verification & Troubleshooting ​

1. Verify Connectivity ​

• Check the logs in logs/app.log (or console output).
• Success: You should see messages like Heartbeat success or Next sync scheduled at....
• Failure: Look for Connection refused, Unknown host, or 401 Unauthorized.

2. Common Issues ​

1. LDAP Connection Failed:

• Verify the LDAP server IP and Port are reachable from the agent machine (telnet <ip> <port>).
• Check if SSL is required but not enabled in the remote config.

2. 401 Unauthorized:

• Check if client_id and client_secret are correct.
• Ensure the system time on the agent machine is synchronized (NTP).

3. No Data Synced:

• Check if the user_filter in the Remote Configuration (Beem Admin Console) matches your users.
• Check if the Base DN is correct.