supportciam/cloud-iam-agent-ad repository overview

⁠Cloud-IAM Directory Connector — Agent

On-premise bridge that connects an internal Active Directory or LDAP directory to a cloud-hosted Keycloak (Cloud-IAM) without opening any inbound port on the customer firewall.

⁠How it works

Broker-1 ◄──WebSocket──┐
                       │
Broker-2 ◄──WebSocket──┼── Agent ──LDAP──► Active Directory / OpenLDAP
                       │
Broker-N ◄──WebSocket──┘

The agent opens one outbound WebSocket per configured broker (typically port 443) and executes LDAP operations (bind, search, sync) on behalf of the cloud-side Keycloak SPI. Each broker is a sidecar of a Keycloak node, so an HA Keycloak cluster of N nodes is paired with N broker connections from a single agent.

⁠Features

• Zero inbound ports — all traffic is initiated from the customer network
• Multi-broker support — parallel outbound WebSockets for HA Keycloak clusters
• Per-connection reconnection — exponential backoff, isolated per broker
• LDAPS / StartTLS — TLS-secured LDAP, optional trust of self-signed certs
• Encrypted credentials — AES-256-GCM end-to-end between broker and agent
• Observability — /actuator/health per-broker status, Prometheus metrics
• Active Directory & OpenLDAP — configurable filters and search bases

⁠Quick start

docker run -d \
  --name cloud-iam-agent \
  -e AGENT_ID=agent-acme-01 \
  -e BROKER_CONNECTIONS_0_URL=wss://acme.cloud-iam.com/connector/broker-1/v1/connect \
  -e BROKER_CONNECTIONS_0_AUTH_TOKEN=$AGENT_TOKEN_1 \
  -e BROKER_CONNECTIONS_1_URL=wss://acme.cloud-iam.com/connector/broker-2/v1/connect \
  -e BROKER_CONNECTIONS_1_AUTH_TOKEN=$AGENT_TOKEN_2 \
  -e AGENT_ENCRYPTION_SHARED_KEY=$SHARED_KEY \
  -e LDAP_HOST=ad.acme.local \
  -e LDAP_PORT=636 \
  -e LDAP_USE_LDAPS=true \
  -e LDAP_BIND_DN="CN=svc-cloudiam,OU=ServiceAccounts,DC=acme,DC=local" \
  -e LDAP_BIND_PASSWORD=$LDAP_PWD \
  -e LDAP_BASE_DN="DC=acme,DC=local" \
  -e LDAP_USER_FILTER='(&(objectClass=user)(sAMAccountName={0}))' \
  supportciam/cloud-iam-agent-ad:latest

⁠Configuration

⁠Broker connections (multi-broker)

⁠LDAP / Active Directory

⁠Agent identity

⁠Network requirements

The agent only needs outbound access:

• N WebSocket connections to the brokers (typically port 443)
• LDAP to the local directory (port 389 or 636)

No inbound ports need to be opened on the customer firewall.

⁠Health & metrics

• GET /actuator/health — aggregated status with per-broker details (UP if at least one broker is connected)
• GET /actuator/prometheus — Prometheus metrics:
  • agent.broker.reconnects{broker=...} — reconnection counter per broker
  • agent.ldap.auth.duration / agent.ldap.auth.success / agent.ldap.auth.failure

⁠License & support

© Cloud-IAM — https://www.cloud-iam.com⁠ Support: [email protected]⁠