Synit ADProxy

Plan/Apply

So plant, prüft, genehmigt und verifiziert Synit ADProxy Änderungen in Enterprise Active Directory, inklusive Outcomes, Rejections, Grenzen und Konflikten.

Plan/Apply

ADProxy behandelt Änderungen in Enterprise Active Directory (AD) als geprüften Workflow. Ein Client beschreibt gewünschte Änderungen. ADProxy prüft sie, erstellt einen Plan und wendet diesen Plan erst nach Freigabe an.

Warum AD-Änderungen in zwei Schritten laufen

Viele Active-Directory-Änderungen sind mehrstufig: Benutzer anlegen, Passwort setzen, Account aktivieren, Gruppen ergänzen, Manager setzen. Wenn ein Schritt fehlschlägt, muss klar sein, was bereits passiert ist und was noch offen ist.

Der Plan-Schritt beantwortet vorab:

  • welche Objekte betroffen sind
  • welche Reihenfolge nötig ist
  • welche Schritte riskant sind
  • welche Abhängigkeiten bestehen
  • welche Validierungen fehlschlagen
  • welche Rollback- oder Cleanup-Hinweise existieren

Plan erzeugen

curl -sS -X POST https://adproxy.example.test/api/v1/mutations/plan \
  -H "Authorization: Bearer <read-or-write-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mutation_id": "group-access-jane",
    "actor": "alice@example.test",
    "source": "service-desk",
    "operations": [
      {
        "id": "add_jane_to_engineering",
        "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"
      }
    ]
  }'

Der Plan gibt unter anderem plan_id, Status, Aktionen, Warnungen, Risiken und mögliche Fehler zurück.

Plan anwenden

curl -sS -X POST https://adproxy.example.test/api/v1/mutations/apply \
  -H "Authorization: Bearer <write-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "<plan-id-aus-plan-response>",
    "actor": "alice@example.test"
  }'

Bei sensiblen Operationen kann zusätzlich eine explizite Freigabe nötig sein:

{
  "plan_id": "<plan-id>",
  "actor": "alice@example.test",
  "force": true
}

Outcomes richtig einordnen

Typische Outcomes:

  • applied: Änderung wurde angewendet und verifiziert.
  • rejected: Plan wurde abgelehnt; es wurde nichts geschrieben.
  • uncertain: Ergebnis ist nicht sicher genug belegt; manuelle Prüfung nötig.

Plan-Antwort lesen

Ein Plan enthält je nach response_detail unter anderem:

  • plan_id: stabile Referenz auf den geplanten Aktionsgraphen
  • status: zum Beispiel accepted oder rejected
  • summary: kurze Beschreibung und Anzahl geplanter Aktionen
  • plan.actions[]: geordnete Aktionen mit Operation, Ziel und Abhängigkeiten
  • warnings: Hinweise, die vor Apply bewertet werden sollten
  • errors: strukturierte Ablehnungsgründe
  • validation_stages: Prüfschritte, die im Planlauf durchgeführt wurden

Für menschliche Reviews ist response_detail: "verbose" im Pilotbetrieb hilfreich. Für stabile Automationen reicht später oft standard.

Apply-Antwort lesen

Apply prüft zuerst den Planbezug und führt dann die freigegebenen Aktionsgruppen aus. Die Antwort kann enthalten:

  • angewendete Aktionen
  • übersprungene oder bereits erfüllte No-ops
  • Verifikationsergebnisse
  • Rollback-Ergebnisse
  • manual_cleanup Hinweise
  • uncertain_sub_status, wenn ein Zustand manuell geprüft werden sollte

Ein abgeschlossenes Kommando ist nicht automatisch gleichbedeutend mit erreichtem Zielzustand. Deshalb ist Verify ein eigener Teil des Workflows.

Warum abgelehnte Pläne hilfreich sind

Ein abgelehnter Plan ist kein Fehler im Betrieb. Er verhindert, dass eine unklare oder unsichere Änderung geschrieben wird.

Häufige Gründe:

  • Zielobjekt fehlt.
  • Mitglied oder Gruppe existiert nicht.
  • Operation wird für diese Objektklasse nicht unterstützt.
  • Request versucht read-only oder systemverwaltete Attribute zu schreiben.
  • Freigabe oder Gate für riskante Operation fehlt.
  • Anfrage überschreitet konfigurierte Grenzen.

Technische Grenzen ehrlich einordnen

  • ADProxy ist transaction-like, aber keine ACID-Transaktion.
  • Active Directory bietet für diese Fälle keine native Multi-Operation-Transaktion.

Rollback ist best-effort. Externe Active-Directory-Writers können außerhalb von ADProxy Änderungen durchführen. Bei unklarem Zustand liefert ADProxy Reconciliation- und Cleanup-Hinweise. Generated Secrets werden nur im Apply-Ergebnis ausgegeben, wenn das explizit angefordert wurde.

Garantien

ADProxy gibt Integrationen klare technische Eigenschaften:

  • Ein plan_id kann nur einmal angewendet werden; spätere Aufrufe liefern das gespeicherte Endergebnis oder einen In-flight-Hinweis.
  • Identische Plan-Requests erzeugen einen deterministischen Plan-Hash für den geplanten Aktionsgraphen.
  • Innerhalb eines laufenden Prozesses werden überlappende Ressourcen serialisiert.
  • Bei Snapshot-Speicherung können unterbrochene Mutationen über POST /api/v1/mutations/{id}/resume wieder aufgenommen werden.
  • Generated Secrets erscheinen nur in der Apply-Antwort, wenn show_secret_outputs: true gesetzt ist.
  • Generated Secrets werden nicht in Audit, Snapshot oder Mutation History geschrieben.

Isolation und Konflikte

ADProxy reduziert typische Race Conditions, ersetzt aber keine globale Active-Directory-Transaktion.

Modify-Operationen prüfen den Live-Zustand unmittelbar vor dem Schreiben. Wenn LDAP Assertion Controls verfügbar sind, wird uSNChanged genutzt, um Lost Updates bei Modify zu erkennen. Delete, Move und Rename prüfen ebenfalls live, haben aber ein kleineres verbleibendes Race Window. Andere Tools, andere ADProxy-Prozesse oder direkte PowerShell-/MMC-Änderungen werden nicht global blockiert.

Wenn ein Konflikt erkannt wird, ist er retryable: Zustand neu lesen, neu planen und erst nach Review erneut anwenden.

United in Diversity