Konfigurationsreferenz

Diese Referenz beschreibt alle aktuell vom HCL-Loader akzeptierten ADProxy-Konfigurationsblöcke. Unbekannte HCL-Felder sind keine Zukunftsoptionen, sondern Konfigurationsfehler.

Gültigkeitsbereich

directory, snapshot und audit sind in jeder HCL-Datei Pflicht, auch für den separaten adproxy-mcp Prozess. server ist optional und verwendet ohne Block die Standardadresse 127.0.0.1:8765.

adproxy-server und adproxy-mcp sind getrennte Prozesse:

• adproxy-server lehnt mcp.enabled = true bei serve und validate-config ab.
• adproxy-mcp setzt MCP beim Start selbst auf aktiv und verwendet den mcp-Block für Transport und Policies.
• Für HTTP und MCP werden daher getrennte gerenderte Konfigurationsdateien empfohlen. Gemeinsame Blöcke wie directory, schema, cache, query_policy, limits und redaction dürfen identisch sein.

Alle Zeitwerte verwenden Go-Durationswerte, etwa "30s", "200ms" oder "5m". snapshot.max_size akzeptiert Bytes oder die Endungen MiB, GiB, MB und GB.

Minimale gültige HTTP-Konfiguration

server {
  listen_addr = "127.0.0.1:8765"

  auth_token "reader" {
    secret_ref = "env:ADPROXY_API_READ_TOKEN"
    access     = "read-only"
  }

  auth_token "writer" {
    secret_ref = "env:ADPROXY_API_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"
}

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

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

directory.bind_password_ref, server.auth_token.<client_id>.secret_ref, mcp.auth_token_ref und mcp.query_cursor_secret_ref akzeptieren ausschließlich env:NAME und file:/absolute/or/relative/path. Bevorzugen Sie Referenzen; Literalwerte bleiben nur kompatibel.

HTTP-Service

Feld	Default / erlaubte Werte	Regel
server.listen_addr	127.0.0.1:8765	Muss host:port sein. Ohne server.tls ist nur Loopback zulässig.
server.auth_token	leer	Legacy Bearer-Secret ohne benannte Client-ID.
server.auth_token "<client_id>".secret	eine von secret/secret_ref	Literal Secret; nicht für eingecheckte HCL-Dateien.
server.auth_token "<client_id>".secret_ref	eine von secret/secret_ref	env:NAME oder file:PATH; beim Service-Start aufgelöst.
server.auth_token "<client_id>".access	read-write	read-only oder read-write.
server.read_timeout	30s	Positiver Go-Duration-Wert.
server.write_timeout	30s	Positiver Go-Duration-Wert.
server.idle_timeout	60s	Positiver Go-Duration-Wert.
server.read_rate_limit_rps	50	Mit Burst gemeinsam setzen; beide 0 deaktiviert das Read-Limit. Sonst beide positiv.
server.read_rate_limit_burst	100	Mit RPS gemeinsam setzen; beide 0 deaktiviert das Read-Limit. Sonst beide positiv.
server.tls.cert_file, key_file	leer	Sobald irgendein server.tls Feld gesetzt ist, sind Zertifikat und Key erforderlich.
server.tls.chain_file	leer	Optionale PEM-Datei mit Zwischenzertifikaten, die nach dem Serverzertifikat ausgeliefert werden.

Ein read-only Token darf Query, Schema und Plan-only aufrufen. Apply und kombinierte Plan-and-Apply Requests benötigen read-write. adproxy-server lehnt eine Konfiguration ohne HTTP-Token ab. /readyz bleibt unauthentifiziert.

TLS und entfernte Konfigurationsblöcke

Die früheren Blöcke dev und Top-Level-tls werden nicht mehr akzeptiert. server.allow_anonymous ist ebenfalls entfernt. Alte Dateien brechen beim Laden mit einem konkreten Migrationshinweis ab. HTTPS gehört ausschließlich in server.tls; Client-Zertifikat-Authentifizierung ist nicht implementiert.

Zertifikat, Key und optionale Chain werden beim Start geladen. Unlesbare oder ungültige Dateien sowie ein nicht passender Key verhindern den Listener-Start. Nach einer Zertifikatsrotation muss der Prozess neu gestartet werden.

Active Directory

Feld	Default / erlaubte Werte	Regel
directory.domain	erforderlich	AD-Domain.
directory.bind_url	erforderlich	Für Produktion ldaps://...; LDAP-Zertifikate werden standardmässig geprüft.
directory.bind_dn	erforderlich	Servicekonto mit minimal benötigten AD-Rechten.
directory.bind_password_ref	erforderlich	env:NAME oder file:PATH.
directory.hosts	leer	Zulässige Domain Controller für Routing, auch für target_dc.
directory.timeout	30s	Muss positiv sein.
directory.retry_attempts	3	Gesamtzahl der Leseversuche, einschliesslich des ersten. Muss positiv sein.
directory.retry_initial_backoff	200ms	Muss positiv sein.
directory.retry_max_backoff	2s	Muss mindestens retry_initial_backoff sein.
directory.tls.ca_file	leer	PEM-CA für eine private AD-CA.
directory.tls.server_name	leer	TLS-SNI/Hostname-Prüfung überschreiben, wenn Dial-Host und Zertifikatsname abweichen.
directory.tls.insecure_skip_verify	false	Deaktiviert die LDAPS-Zertifikatsprüfung explizit und erzeugt beim Start eine Warnung.

Mutierende LDAP-Operationen werden nach einem unklaren Netzwerkabbruch nicht blind wiederholt. Der nächste sichere Schritt ist Reconciliation, nicht ein automatisches Replay des Writes.

Schema, Cache und Read-Grenzen

Feld	Default / erlaubte Werte	Regel
schema.enabled	true	Lädt oder verwendet AD-Schema-Metadaten.
schema.required	true	Bei true blockiert ein fehlgeschlagener Schema-Load den Start; bei false läuft der Service ohne Schema weiter.
schema.cache_path	leer	Lokaler Pfad zum geladenen Schema-Cache.
cache.validation_enabled	true ohne cache Block	Validiert Cache-Freshness. In einem vorhandenen cache Block explizit setzen.
cache.ttl_min	5s	Muss positiv sein und darf nicht über ttl_max liegen.
cache.ttl_default	60s	Muss zwischen ttl_min und ttl_max liegen.
cache.ttl_max	15m	Muss mindestens ttl_min sein.

limits Feld	Default	Regel
query_page_size	500	Interne Query-Seitengrösse; positiv und höchstens query_max_page_size.
query_max_page_size	1000	Interne Obergrenze, mindestens query_page_size.
query_max_candidates	1000	Positiv; begrenzt gelesene Kandidaten.
query_max_returned	250	Positiv und höchstens query_max_candidates; MCP-Tool-Seiten bleiben darunter.
query_max_attributes	20	Positiv; für MCP angeforderte fields gilt effektiv min(Wert, 50).
query_max_response_bytes	1048576	Positiv; maximale Read-Antwortgrösse.
query_max_in_values	20	Positiv; Schutzlimit im gemeinsamen Query-Compiler.
query_max_sort_keys	3	Positiv; Schutzlimit im gemeinsamen Query-Compiler.
query_max_filter_depth	4	Positiv; Schutzlimit im gemeinsamen Query-Compiler.
mutation_max_steps	100	Positiv; maximale Anzahl geplanter Mutation-Schritte.
dependency_graph_max_nodes	500	Positiv; maximale Graphgrösse.
lazy_load_max_depth	2	Positiv; effektive maximale Lazy-Load-Tiefe.
ad_operation_timeout	30s	Positiv.
mutation_total_timeout	5m	Positiv und mindestens ad_operation_timeout.
preload_timeout	2m	Positiv.

POST /api/v1/query und die festen MCP Outcome-Tools bleiben öffentliche Verträge. Die übrigen Query-Compiler-Limits sind Schutzwerte, keine wieder eingeführte dynamische MCP-DSL.

Preload und Lazy Load

preload "users" {
  enabled     = true
  base_dn     = "OU=Users,DC=example,DC=test"
  ldap_filter = "(objectClass=user)"
  attributes  = ["cn", "mail", "sAMAccountName"]
  required    = true
  page_size   = 500
  max_objects = 10000
}

lazy_load {
  enabled      = false
  max_depth    = 2
  allowed_deps = ["manager"]
}

preload kann mehrfach vorkommen. name ist das Block-Label; enabled, base_dn, ldap_filter, attributes, required, page_size und max_objects sind die vollständigen Felder. Bei einem fehlgeschlagenen aktivierten required Preload wird die Instanz als nicht bereit gemeldet. Ohne page_size verwendet der Preload 1000; max_objects = 0 bedeutet kein zusätzlicher Objekt-Cap.

lazy_load.allowed_deps akzeptiert die Abhängigkeiten member, manager, memberOf und children. In HCL setzt ein positiver lazy_load.max_depth den Wert; die effektive Tiefe wird zusätzlich durch limits.lazy_load_max_depth begrenzt.

Mutation- und Workflow-Optionen

Feld	Default / erlaubte Werte	Regel
approval.require_for_all_writes	false	Require ein Approval-Objekt bei jedem Apply/Resume.
approval.require_for_force_operations	false	Require ein Approval nur für force-pflichtige Writes.
approval.require_different_client_id	false	Approval-Client muss vom Plan-Ersteller abweichen.
password_generation.policy_mode	best_effort	best_effort oder require_ad_policy.
password_generation.default_length	24	Positiv und höchstens max_length.
password_generation.max_length	128	Positiv und mindestens default_length.
password_generation.complexity_required	nicht gesetzt	true oder false; nicht gesetzt bedeutet an AD-Policy ausrichten.
managed_state.path	leer	Aktiviert den file-basierten Managed-State-Speicher.
managed_state.on_save_failure	warn bei Block	warn, reject oder retry.
rules_path	leer	Pfad zu zusätzlichen Planungs-/Business-Regeln.
template_dir	leer	Verzeichnis für .template.json JSONata-Templates. Ohne Wert liefern Template-Endpunkte 503.

approval gilt zusätzlich zur fachlichen Freigabe. force oder risk.force_approved ersetzt weder ein erforderliches Approval noch fehlende AD-Objekte oder ungültige Operationen.

Snapshot, Mutation-Audit und Service-Logging

Feld	Default / erlaubte Werte	Regel
snapshot.path	erforderlich im Block	Verzeichnis für JSONL WAL, Plan-Requests und Journals.
snapshot.max_size	erforderlich im HCL-Block	Muss positiv sein; zum Beispiel 256MiB.
audit.file_enabled	erforderlicher Bool im HCL-Block	Bei true ist audit.file_path erforderlich.
audit.file_path	leer	JSONL-Pfad; Go-Referenzzeit im Dateinamen rotiert Dateien, z. B. audit-2006-01-02.jsonl.
readiness.durability_failure_mode	fail_closed	fail_closed oder degraded.
debug.enabled	false	Aktiviert detailliertere Diagnoseausgaben; in Produktion deaktiviert lassen.
debug.log_dir	logs/debug	Verzeichnis für Debug-Ausgaben.
redaction.force_allowed_attributes	leer	Bewusst zusätzlich sichtbare operative Attribute.
redaction.force_redacted_attributes	leer	Zusätzliche, immer redigierte Attribute.

Ein Attribut darf nicht gleichzeitig in force_allowed_attributes und force_redacted_attributes stehen. Gleiches gilt für ein Attribut, das gleichzeitig in query_policy.allowed_attrs und query_policy.denied_attrs steht.

logging {
  stderr { enabled = true  levels = ["info", "warn", "error"] }
  stdout { enabled = false levels = ["info", "warn", "error"] }
  file {
    enabled = false
    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"]
  }
}

logging.stderr, logging.stdout, logging.file und logging.syslog akzeptieren nur debug, info, warn und error in levels; mindestens ein Level ist nötig. Ohne logging Block ist nur stderr aktiv. logging.file.path ist bei aktiviertem File-Sink erforderlich.

audit.syslog und mcp.audit.syslog verwenden dieselben Felder wie der Syslog-Sink, ausser levels. Gültige Server-Schemata sind udp://host:port, tcp://host:port und tls://host:port. ca_file und server_name sind nur mit tls:// erlaubt. Gültige RFC-5424 Facilities sind kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, ntp, audit, alert, clock sowie local0 bis local7.

Query-Policy

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 darf keine leeren Werte enthalten. allowed_attrs und denied_attrs werden ohne Beachtung der Gross-/Kleinschreibung verglichen und dürfen sich nicht überschneiden. allow_raw_filters gilt für GET /api/v1/objects; für Agenten ist false der sichere Standard.

MCP-spezifische Felder

Der mcp Block gehört in die Konfiguration für adproxy-mcp, nicht in eine mit adproxy-server verwendete Datei mit enabled = true.

Feld	Default / erlaubte Werte	Regel
mcp.enabled	false	adproxy-mcp setzt den Wert beim Start auf true; adproxy-server lehnt true ab.
mcp.transport	stdio	stdio, streamable-http oder both.
mcp.listen_addr	127.0.0.1:8768	Bei HTTP-Transport erforderlich. Ohne mcp.tls muss die Adresse Loopback sein.
mcp.tls.cert_file, key_file	leer	Für direktes HTTPS gemeinsam erforderlich; nur mit streamable-http oder both.
mcp.tls.chain_file	leer	Optionale PEM-Datei mit Zwischenzertifikaten.
mcp.allow_anonymous	false	Nur für HTTP-Transporte auf Loopback; darf nicht mit einem Auth-Token kombiniert werden.
mcp.auth_token	leer	Eine von auth_token/auth_token_ref; bei HTTP erforderlich, außer allow_anonymous = true.
mcp.auth_token_ref	leer	env:NAME oder file:PATH; für Container bevorzugt.
mcp.query_cursor_secret_ref	kein Default	Für jeden MCP-Transport erforderlich; aufgelöst mindestens 32 Byte.
mcp.query_cursor_ttl	15m	Zwischen 1s und 1h.
mcp.rate_limit_rps	10	Positiv.
mcp.rate_limit_burst	20	Positiv.
mcp.agent_tool_profile	standard	standard oder local.
mcp.agent_response_profile	standard	standard oder deduplicated-v1.
mcp.agent_default_page_size	Profil-Default	0 nutzt 100 (standard) oder 20 (local); sonst höchstens limits.query_max_returned.
mcp.enable_mutation_drafts	false	Draft-Tools sind nur im standard Profil sichtbar.
mcp.attribute_allow_list	leer	Zusätzliche sichtbare-Attributbegrenzung.
mcp.attribute_deny_list	leer	Zusätzliche Attributsperre.
mcp.max_recursive_depth	5	Nicht negativ; HCL-Werte sollten positiv gesetzt werden.
mcp.compact_profile "<klasse>".attributes	leer	Optionale kompakte Profilfelder; Label ist Objektklasse, * wird als generisches Profil behandelt; Attributliste darf nicht leer sein.
mcp.audit.enabled	false	Aktiviert MCP-Audit getrennt vom Mutation-Audit.
mcp.audit.file_enabled	false	Bei true ist file_path erforderlich.
mcp.audit.file_path	leer	JSONL-Ziel.
mcp.audit.audit_level	info	trace, debug, info, warning oder error.

Streamable MCP kann Plain HTTP ausschließlich am Loopback-Port bereitstellen. Für andere Bind-Adressen ist direktes mcp.tls erforderlich. Alternativ terminiert ein vertrauenswürdiger Reverse Proxy TLS vor dem Loopback-Listener. Anonyme Requests bleiben auch mit TLS auf Loopback beschränkt. CORS ist deaktiviert. Weitere Semantik, Tool-Profile und die vollständigen MCP-Auditfelder stehen unter Synit AD MCP Konfiguration.