API und Templates

ADProxy kann über HTTP JSON, JSON-RPC, Webhook-Flows und JSONata-Templates in Enterprise Active Directory (AD) integriert werden. Alle schreibenden Pfade nutzen denselben Plan/Apply-Kern.

Ausführliche Payload-Beispiele stehen zusätzlich unter Synit ADProxy Beispiele.

Wichtige HTTP-Endpunkte im Überblick

Methode	Pfad	Zweck
POST	/api/v1/mutations/plan	Änderung planen, ohne zu schreiben
POST	/api/v1/mutations/apply	freigegebenen Plan anwenden
POST	/api/v1/mutations	Plan und Apply in einem Request
GET	/api/v1/mutations	Mutation Journals und laufende Pläne listen
GET	/api/v1/mutations/{id}	Ergebnis oder Journal abrufen
POST	/api/v1/mutations/{id}/resume	unterbrochene Mutation aus Journal wieder aufnehmen
POST	/api/v1/query	read-only Active-Directory-Abfrage
GET	/api/v1/objects	Objekte per Base DN und Filter suchen
GET	/api/v1/objects/{dn}	einzelnes Objekt per DN lesen
GET	/api/v1/schema	API-Schema abrufen
POST	/api/v1/templates/{name}/render	Template nur rendern
POST	/api/v1/templates/{name}/plan	Template rendern und planen
POST	/api/v1/templates/{name}/mutations	Template rendern, planen und anwenden
POST	/api/v1/rpc	JSON-RPC 2.0 für Plan, Apply und Plan-and-Apply
GET	/api/v1/schema/classes/{name}	Active-Directory-Klassenmetadaten abrufen
GET	/api/v1/schema/attributes/{name}	Attributmetadaten abrufen
POST	/api/v1/admin/tokens/revoke	Client-ID bis zum Neustart live sperren
GET	/readyz	Readiness für Load Balancer und Betrieb prüfen

Authentifizierung

Die HTTP API unterstützt getrennte read-only und read-write Clients.

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 Clients dürfen GET Requests, POST /api/v1/query und POST /api/v1/mutations/plan nutzen. Apply und kombinierte Mutation Requests benötigen einen read-write Client.

Idempotenz

Für kombinierte Plan-and-Apply-Requests kann ein Idempotency-Key gesetzt werden:

curl -sS -X POST https://adproxy.example.test/api/v1/mutations \
  -H "Authorization: Bearer <write-token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-jane-2026-07-02" \
  -d '{ "mutation_id": "onboard-jane", "operations": [] }'

Wiederholte Requests mit gleichem Key und gleichem Body liefern dasselbe Ergebnis zurück. Gleicher Key mit anderem Body wird abgelehnt. Das schützt vor doppelten Workflow- oder Netzwerk-Retries.

Detailgrad der Antworten

Mutation Requests können response_detail setzen:

Wert	Einsatz
summary	kompakte Antwort für einfache Integrationen
standard	normale Plan-/Apply-Details
verbose	erweiterte Details für Review, Diagnose und Pilotphasen

Für fachliche Freigabe und erste Integrationen ist standard oder verbose sinnvoll. Für stabile Automationen kann summary reichen.

Unterstützte Operationen

Häufige Operationen:

create_user create_group modify_attributes set_password unlock enable_account disable_account add_group_member remove_group_member move_object rename_object delete_object set_manager set_primary_group update_account_settings lookup_object

Ein Request muss genau einen Stil nutzen: entweder operations, oder genau eine Desired-State-Liste wie desired_users, desired_groups oder desired_objects. Mischen wird abgelehnt.

Zentrale Request-Felder

Feld	Zweck
mutation_id	optionales Caller-Label für Nachvollziehbarkeit
actor	Mensch oder Service, der den Vorgang auslöst
source	Quellsystem, zum Beispiel service-desk, iam-workflow oder mcp-draft
target_dc	optionaler Domain Controller für deterministische Planung
force	Freigabe für force-pflichtige Operationen
approval	Approval-Metadaten, wenn die Policy das verlangt
show_secret_outputs	generierte Secrets in der Apply-Antwort anzeigen
response_detail	Antworttiefe: summary, standard oder verbose
operations	explizite Operationen
desired_users	gewünschter Benutzer-Zielzustand
desired_groups	gewünschter Gruppen-Zielzustand
desired_objects	gewünschter Objekt-Zielzustand

Beispiel: User Onboarding

{
  "mutation_id": "onboard-jane",
  "actor": "alice@example.test",
  "source": "iam-workflow",
  "operations": [
    {
      "id": "create_jane",
      "operation_type": "create_user",
      "target": {
        "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
      },
      "object_class": "user",
      "attributes": {
        "cn": "Jane Doe",
        "givenName": "Jane",
        "sn": "Doe",
        "displayName": "Jane Doe",
        "sAMAccountName": "jdoe",
        "userPrincipalName": "jdoe@example.test",
        "mail": "jane.doe@example.test"
      }
    },
    {
      "id": "add_jane_to_group",
      "operation_type": "add_group_member",
      "target": {
        "dn": "CN=Engineering Users,OU=Groups,DC=example,DC=test"
      },
      "object_class": "group",
      "member_dn": "CN=Jane Doe,OU=Users,DC=example,DC=test",
      "depends_on": ["create_jane"]
    }
  ]
}

Beispiel: Account-Einstellungen

{
  "mutation_id": "jane-account-settings",
  "actor": "alice@example.test",
  "force": true,
  "operations": [
    {
      "id": "disable_user",
      "operation_type": "disable_account",
      "target": {
        "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
      },
      "object_class": "user"
    },
    {
      "id": "move_to_disabled_ou",
      "operation_type": "move_object",
      "target": {
        "dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
      },
      "object_class": "user",
      "new_parent": "OU=Disabled Users,DC=example,DC=test",
      "depends_on": ["disable_user"]
    }
  ]
}

Templates

Templates sind JSON-Dateien, die mit Variablen gerendert werden. Sie sind geeignet für wiederkehrende Abläufe wie Onboarding, Offboarding oder Gruppenänderungen.

Beispiel user_onboarding.template.json:

{
  "name": "user_onboarding",
  "payload": {
    "mutation_id": "{{ $mutation_id }}",
    "actor": "{{ $actor }}",
    "operations": [
      {
        "id": "create_user",
        "operation_type": "create_user",
        "object_class": "user",
        "target": {
          "dn": "CN={{ $display_name }},{{ $ou_dn }}"
        },
        "attributes": {
          "cn": "{{ $display_name }}",
          "givenName": "{{ $given_name }}",
          "sn": "{{ $surname }}",
          "sAMAccountName": "{{ $user_name }}",
          "mail": "{{ $user_name }}@example.test",
          "department": "{{ $department }}"
        }
      }
    ]
  }
}

Rendern:

curl -sS -X POST https://adproxy.example.test/api/v1/templates/user_onboarding/render \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mutation_id": "onboard-jane",
    "actor": "alice@example.test",
    "display_name": "Jane Doe",
    "given_name": "Jane",
    "surname": "Doe",
    "user_name": "jdoe",
    "department": "Engineering",
    "ou_dn": "OU=Users,DC=example,DC=test"
  }'

Planen:

curl -sS -X POST https://adproxy.example.test/api/v1/templates/user_onboarding/plan \
  -H "Authorization: Bearer <read-or-write-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mutation_id": "onboard-jane",
    "actor": "alice@example.test",
    "display_name": "Jane Doe",
    "given_name": "Jane",
    "surname": "Doe",
    "user_name": "jdoe",
    "department": "Engineering",
    "ou_dn": "OU=Users,DC=example,DC=test"
  }'

Render, Plan und Apply in einem Schritt:

curl -sS -X POST https://adproxy.example.test/api/v1/templates/user_onboarding/mutations \
  -H "Authorization: Bearer <write-token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-jane-template-2026-07-01" \
  -d '{
    "mutation_id": "onboard-jane",
    "actor": "alice@example.test",
    "display_name": "Jane Doe",
    "given_name": "Jane",
    "surname": "Doe",
    "user_name": "jdoe",
    "department": "Engineering",
    "ou_dn": "OU=Users,DC=example,DC=test"
  }'

Regeln für Templates

Keine Secrets in Templates speichern. Von Active Directory generierte Attribute wie objectGUID, objectSid, whenChanged, uSNChanged oder memberOf nicht schreiben. Passwortmaterial nur über abgestimmte sichere Wege behandeln. Offboarding konservativ halten: zuerst deaktivieren, dann bekannte Gruppen entfernen, danach verschieben. Templates versionieren und fachlich freigeben.

JSON-RPC

JSON-RPC nutzt denselben Plan/Apply-Kern wie die HTTP Endpunkte.

Methode	Zweck
mutation.plan	Plan erzeugen
mutation.apply	freigegebenen Plan anwenden
mutation.plan_and_apply	planen und direkt anwenden

Beispiel:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mutation.plan",
  "params": {
    "actor": "alice@example.test",
    "operations": [
      {
        "id": "add_member",
        "operation_type": "add_group_member",
        "target": {
          "dn": "CN=Engineering Users,OU=Groups,DC=example,DC=test"
        },
        "object_class": "group",
        "member_dn": "CN=Jane Doe,OU=Users,DC=example,DC=test"
      }
    ]
  }
}

Schema-Diagnose

Schema-Endpunkte helfen Integrationen und Agenten, gültige Requests zu bauen.

curl -sS -u "<client-id>:<secret>" https://adproxy.example.test/api/v1/schema

curl -sS -u "<client-id>:<secret>" https://adproxy.example.test/api/v1/schema/classes/user

curl -sS -u "<client-id>:<secret>" https://adproxy.example.test/api/v1/schema/attributes/sAMAccountName