Synit ADProxy

Konfiguration

Konfigurationsreferenz für Synit ADProxy: HTTPS, LDAPS, Tokens, Query-Policy, Redaction, Audit, Templates, Snapshots, Readiness und Betrieb.

Konfiguration

Diese Seite zeigt die wichtigsten Konfigurationsbereiche für eine produktive ADProxy-Integration in Enterprise Active Directory (AD). Die Beispiele nutzen Platzhalter und .example.test Domains. Secrets sollten immer über die vorhandenen Secret- und Deployment-Prozesse der Umgebung bereitgestellt werden.

Ziel der Konfiguration

Eine typische produktive Konfiguration trennt:

  • HTTP-Zugriff auf ADProxy
  • LDAPS-Zugriff auf Active Directory
  • read-only und read-write Tokens
  • Query-Scope und Attribut-Redaction
  • Audit-Ausgabe
  • optionale Templates für wiederkehrende Workflows
  • optionale Snapshot-Speicherung für bessere Wiederaufnahme und Nachvollziehbarkeit

Beispielkonfiguration

server {
  listen_addr   = "127.0.0.1:8765"
  read_timeout  = "30s"
  write_timeout = "30s"
  idle_timeout  = "60s"

  read_rate_limit_rps   = 50
  read_rate_limit_burst = 100

  tls {
    cert_file = "/etc/adproxy/tls/server.crt"
    key_file  = "/etc/adproxy/tls/server.key"
  }

  auth_token "workflow-reviewer" {
    secret = "<read-only-token>"
    access = "read-only"
  }

  auth_token "workflow-writer" {
    secret = "<read-write-token>"
    access = "read-write"
  }
}

directory {
  domain            = "example.test"
  bind_url          = "ldaps://dc1.example.test"
  bind_dn           = "CN=svc-adproxy,OU=Service Accounts,DC=example,DC=test"
  bind_password_ref = "env:AD_BIND_PASSWORD"
  hosts             = ["dc1.example.test"]
  timeout           = "30s"

  retry_attempts        = 3
  retry_initial_backoff = "200ms"
  retry_max_backoff     = "2s"

  tls {
    ca_file     = "/etc/adproxy/tls/ad-ca.pem"
    server_name = "dc1.example.test"
  }
}

schema {
  cache_path = "/var/lib/adproxy/schema_cache.json"
}

cache {
  validation_enabled = true
  ttl_min     = "5s"
  ttl_default = "30s"
  ttl_max     = "5m"
}

approval {
  require_for_all_writes       = true
  require_for_force_operations = true
  require_different_client_id  = true
}

query_policy {
  allowed_base_dns  = ["OU=Users,DC=example,DC=test"]
  allowed_attrs     = ["cn", "mail", "sAMAccountName", "memberOf"]
  denied_attrs      = ["unicodePwd", "ntSecurityDescriptor"]
  allow_raw_filters = false
}

redaction {
  force_allowed_attributes  = ["badPwdCount", "badPasswordTime"]
  force_redacted_attributes = ["customSecretAttribute"]
}

template_dir = "/etc/adproxy/templates"

audit {
  file_enabled = true
  file_path    = "/var/log/adproxy/audit-2006-01-02.jsonl"
}

snapshot {
  path     = "/var/lib/adproxy/snapshot"
  max_size = "256MiB"
}

readiness {
  durability_failure_mode = "fail_closed"
}

HTTP-Service und Authentifizierung

Der server-Block stellt die HTTP API bereit. Darüber laufen Plan/Apply, Query, Schema und Template-Endpunkte.

Bereich Zweck
listen_addr Bind-Adresse des HTTP-Service. Häufig lokal hinter Reverse Proxy oder Service Mesh.
tls HTTPS-Zertifikat für den HTTP-Service.
auth_token Statische Client-Zugänge mit read-only oder read-write.
read_rate_limit_* Rate Limit für HTTP-Lesezugriffe.

Unterstützte Auth-Formate:

Schema Beispiel
Bearer Token Authorization: Bearer <token>
Bearer mit Client-ID Authorization: Bearer workflow-writer:<secret>
Bearer Base64 Authorization: Bearer <base64(client_id:secret)>
Basic Auth Authorization: Basic <base64(client_id:secret)>

read-only Tokens dürfen Plan-only Requests, Query und Schemazugriffe ausführen. read-write Tokens werden für Apply oder kombinierte Mutation Requests benötigt.

Tokens werden nicht über ADProxy erzeugt, gespeichert oder aufgelistet. Legen Sie Tokens in Ihrem Secret- oder Deployment-System an und rendern Sie sie kontrolliert in die Laufzeitkonfiguration. Für dauerhafte Sperrung wird ein Token in der Konfiguration rotiert oder entfernt. Eine Live-Sperre per API ist nur pro laufendem Prozess gültig.

TLS und sicherer Modus

Der HTTP-Service nutzt den verschachtelten Block server.tls.

server {
  tls {
    cert_file = "/etc/adproxy/tls/server.crt"
    key_file  = "/etc/adproxy/tls/server.key"
  }
}

Wenn dev.insecure = false gesetzt ist, sollte die Konfiguration zusätzlich den Top-Level-Block tls enthalten:

dev {
  insecure = false
}

tls {
  cert_file      = "/etc/adproxy/tls/server.crt"
  key_file       = "/etc/adproxy/tls/server.key"
  client_ca_file = "/etc/adproxy/tls/ca.crt"
}

Wichtig: Client-Zertifikate ersetzen nicht die HTTP-Authentifizierung. Nutzen Sie weiterhin read-only und read-write Tokens.

Anbindung an Active Directory

Der directory-Block beschreibt die Verbindung zu Active Directory.

  • bind_url sollte LDAPS verwenden.
  • bind_dn sollte ein Servicekonto mit minimal nötigen Rechten sein.
  • bind_password_ref sollte auf ein Secret aus der Laufzeitumgebung verweisen.
  • hosts begrenzt die zulässigen Domain Controller.
  • directory.tls.ca_file bindet die interne CA für LDAPS ein.
  • directory.tls.server_name hilft, wenn der technische Hostname nicht exakt zum Zertifikat passt.

Retry-Einstellungen gelten für Lesezugriffe und Verbindungsfehler. Schreibende Operationen werden nach einem unklaren Netzwerkabbruch nicht blind wiederholt, weil der tatsächliche Active-Directory-Zustand geprüft werden muss.

Query-Policy und Redaction

Read-only Abfragen sollten bewusst begrenzt werden.

query_policy {
  allowed_base_dns  = ["OU=Users,DC=example,DC=test"]
  allowed_attrs     = ["cn", "mail", "sAMAccountName", "memberOf"]
  denied_attrs      = ["unicodePwd", "ntSecurityDescriptor"]
  allow_raw_filters = false
}

allowed_base_dns begrenzt Suchräume, allowed_attrs begrenzt Rückgabefelder, denied_attrs sperrt sensible Attribute, und allow_raw_filters = false verhindert freie LDAP-Filter auf dem Objekt-Endpunkt.

Redaction greift zusätzlich auf HTTP Query, Objekt-Endpunkte und MCP Tool Responses. Harte Secret-Attribute wie Passwortmaterial, LAPS, BitLocker, Fotos und Security Descriptors bleiben redigiert.

Cache und Debug

Der cache-Block reduziert wiederholte Objektlesezugriffe. Suchabfragen lesen Active Directory direkt und füllen den Objektcache. get_object kann aus dem Cache lesen.

cache {
  validation_enabled = true
  ttl_min     = "5s"
  ttl_default = "30s"
  ttl_max     = "5m"
}

Mit force_refresh: true kann ein einzelner Query-Request den Cache umgehen.

debug.enabled sollte in Produktion aus bleiben. Wenn Debug aktiv ist, können Query- und MCP-Antworten detailliertere LDAP-Fehler enthalten.

debug {
  enabled = false
  log_dir = "/var/log/adproxy/debug"
}

Templates

Templates sind für wiederkehrende Prozesse gedacht, zum Beispiel Onboarding, Offboarding oder Gruppenänderungen.

template_dir = "/etc/adproxy/templates"

Template-Endpunkte:

Endpoint Zweck
POST /api/v1/templates/{name}/render Template mit Variablen rendern, ohne Plan.
POST /api/v1/templates/{name}/plan Template rendern und Plan erzeugen.
POST /api/v1/templates/{name}/mutations Template rendern, planen und anwenden.

Templates sollten versioniert, fachlich freigegeben und frei von Secrets sein.

Audit und Journals

audit {
  file_enabled = true
  file_path    = "/var/log/adproxy/audit-2006-01-02.jsonl"
}

Die Audit-Datei ist JSONL-basiert. Das Datumsformat im Dateinamen kann für Rotation genutzt werden, zum Beispiel:

audit-2006-01-02.jsonl für tägliche Rotation, audit-2006-01-02-15.jsonl für stündliche Rotation, audit/2006/01/02.jsonl für Tagesverzeichnisse.

Audit-Ereignisse sollten mindestens Actor, Client, Plan, Ergebnis, Zeitfenster und Referenzen zum Upstream-Prozess enthalten.

Service-Logging und Syslog

Service-Logs können getrennt von Mutation-Audit geschrieben werden.

logging {
  stderr {
    enabled = true
    levels  = ["info", "warn", "error"]
  }

  file {
    enabled = true
    path    = "/var/log/adproxy/service-2006-01-02.log"
    levels  = ["warn", "error"]
  }

  syslog {
    enabled         = false
    server          = "tls://syslog.example.test:6514"
    facility        = "local0"
    app_name        = "adproxy-server"
    connect_timeout = "2s"
    write_timeout   = "500ms"
    ca_file         = "/etc/adproxy/syslog-ca.pem"
    server_name     = "syslog.example.test"
    levels          = ["error"]
  }
}

Syslog nutzt udp://, tcp:// oder tls://. Bei tls:// sollten CA-Datei und Servername sauber gesetzt werden. Audit-Syslog wird im audit.syslog Block konfiguriert und ist zusätzlich zur Datei möglich.

Snapshot und Wiederaufnahme

Wenn snapshot.path gesetzt ist, kann ADProxy Plan- und Aktionszustände persistieren. Das verbessert Wiederaufnahme und Nachvollziehbarkeit nach Prozessunterbrechungen.

Wichtige Eigenschaften:

  • Ein plan_id wird nur einmal angewendet; spätere Aufrufe geben das gespeicherte Endergebnis zurück.
  • Bei Unterbrechung kann ein Journal über POST /api/v1/mutations/{id}/resume wieder aufgenommen werden.
  • Generated Secrets werden nicht in Audit, Snapshot oder Mutation History gespeichert.
  • Ohne Snapshot-Speicher sind Journals nur im laufenden Prozess verfügbar.

Verwalteter Zustand

Wenn Ihre Workflows verwaltete Objekte nachverfolgen sollen, kann ein file-basierter Managed-State-Speicher genutzt werden.

managed_state {
  path            = "/var/lib/adproxy/managed_state.json"
  on_save_failure = "warn"
}

on_save_failure kann warn, reject oder retry sein. Für kritische Prozesse ist reject strenger, weil ein Apply abgebrochen wird, wenn der Zustand nicht gespeichert werden kann. Sichern Sie diese Datei gemeinsam mit Snapshots.

Readiness

readiness {
  durability_failure_mode = "fail_closed"
}

fail_closed meldet fehlende Dauerhaftigkeit als nicht bereit. degraded kann sinnvoll sein, wenn ein Load Balancer die Instanz weiter erreichbar halten soll, obwohl Snapshot- oder Journal-Dauerhaftigkeit eingeschränkt ist. Legen Sie diesen Wert bewusst mit Betrieb und Security fest.

Approval-Policy

approval {
  require_for_all_writes       = true
  require_for_force_operations = true
  require_different_client_id  = true
}

Diese Einstellung sorgt dafür, dass Plan und Apply klar getrennt werden können. In sensiblen Umgebungen sollte ein anderer Client den Plan anwenden als der Client, der ihn erzeugt hat.

Reihenfolge für den ersten produktionsnahen Aufbau

  • LDAPS-Verbindung und Zertifikatskette klären.
  • Read-only und read-write Tokens getrennt definieren.
  • Query-Policy auf Pilot-OU und benötigte Attribute begrenzen.
  • Audit-Ausgabe aktivieren und im Zielsystem prüfen.
  • Mit Plan-only Requests starten.
  • Erst danach Apply für einen kleinen, fachlich freigegebenen Workflow aktivieren.
  • Templates erst ergänzen, wenn der manuelle JSON-Workflow verstanden ist.

AD MCP

AD MCP wird getrennt vom ADProxy HTTP-Service betrieben. Der adproxy-server stellt keine MCP-Schnittstelle bereit. Nutzen Sie für MCP die eigene Synit AD MCP Konfiguration.

United in Diversity