Provisionierung mit SCIM 2.0

Nach dieser Seite bindet ein Verzeichnisdienst die Konten einer Organisation an Szenera an: Eintritt legt ein Konto an, Austritt sperrt es, ein Gruppenwechsel setzt die Rolle. Sie erfahren, wie der Zugang aussieht, welche Endpunkte es gibt, was aufeinander abgebildet wird und was bei Konflikten passiert.

Der Zugang#

Die Schnittstelle liegt unter /scim/v2 und nicht unter /v1: Der Pfad gehört dem fremden Protokoll, und ein Verzeichnisdienst prüft seine eigenen Angaben gegen die Adresse, unter der er spricht.

Hat Ihre Umgebung einen Anmelde-Wirt, nennt das Portal als Basis-Adresse künftig https://auth.<ihre-domain>/scim/v2, und genau diese steht auch in meta.location der Antworten. Neue Einrichtungen tragen sie von Anfang an ein, eine bestehende an der Basis-Adresse der API bleibt bis auf Weiteres erreichbar.

Der Zugang entsteht im Portal unter Einstellungen › Organisation › Unternehmens-Anmeldung, Abschnitt Provisionierung (SCIM). Sein Wert erscheint dort ein einziges Mal. Er kommt auf keine andere Route der Plattform: Überall sonst wird er mit 403 abgewiesen, und umgekehrt erreicht kein API-Schlüssel /scim/v2.

Der Anmeldeweg ist Bedingung, nicht Empfehlung. Ein so angelegtes Konto bekommt kein Passwort und meldet sich über den Anbieter der Organisation an. Ohne aktiven Anbieter lässt sich kein Zugang ausstellen.

Die Endpunkte#

Ein Verzeichnisdienst beginnt mit der ersten Zeile:

curl -sS "$SZENERA_API/scim/v2/ServiceProviderConfig" \
  -H "Authorization: Bearer $SZENERA_SCIM_TOKEN"

Ein Konto anlegen — wiederholbar, dieselbe Adresse liefert dasselbe Konto:

curl -sS -X POST "$SZENERA_API/scim/v2/Users" \
  -H "Authorization: Bearer $SZENERA_SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "userName": "deniz.acar@demo.local",
        "externalId": "entra-8f3c1a20",
        "name": { "givenName": "Deniz", "familyName": "Acar" },
        "active": true
      }'

Ein Konto sperren — die Teiländerung ist der Regelweg:

curl -sS -X PATCH "$SZENERA_API/scim/v2/Users/usr_01KFB7QPW0TEAM000000000002" \
  -H "Authorization: Bearer $SZENERA_SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [{ "op": "replace", "path": "active", "value": false }]
      }'

Blättern und Filtern#

startIndex zählt ab eins, count ist auf 200 gedeckelt. Als Filter wird genau die Form attribut eq "wert" angenommen: userName eq und externalId eq auf Users, displayName eq auf Groups. Alles andere ist 400 mit scimType: "invalidFilter" — ein still ignorierter Filter lieferte sonst den ganzen Bestand.

curl -sS --get "$SZENERA_API/scim/v2/Users" \
  -H "Authorization: Bearer $SZENERA_SCIM_TOKEN" \
  --data-urlencode 'filter=userName eq "deniz.acar@demo.local"'

Die Abbildung#

Felder, die Szenera nicht führt (title, phoneNumbers, Erweiterungs-Schemas), werden still verworfen. Ihre Zuordnung im Verzeichnisdienst muss dafür nicht ausgedünnt werden.

Vier Eigenheiten, die eine Anbindung kennen muss:

• Gelöscht wird nie. An einem Konto hängen Protokoll-Einträge, hochgeladene Medien und angelegte Programme. Das endgültige Löschen bleibt ein bewusster Schritt eines Menschen im Portal.
• Ein Konto trägt genau eine Rolle, nie keine. Ein add weist die Rolle zu und ersetzt die bisherige; ein remove setzt auf die Basis-Rolle zurück; ein PUT ist beides zusammen, denn wer in der Liste fehlt, fällt zurück.
• Gruppen entstehen nicht über SCIM. Die Substanz einer Rolle sind ihre Rechte, und die trägt das Protokoll nicht mit. POST /Groups trifft deshalb eine bestehende Rolle über ihren displayName; ein unbekannter Name bekommt 400 mit scimType: "invalidValue". Legen Sie die Rollen zuerst im Portal an und benennen Sie die Gruppen im Verzeichnis genauso.
• Jede Änderung ist wiederholbar. Ein Verzeichnisdienst wiederholt nach jeder Zeitüberschreitung, auch wenn der erste Anlauf durchlief. Ein zweites POST /Users mit derselben Adresse liefert dasselbe Konto; ein PATCH active:false auf ein bereits gesperrtes Konto ist ein stiller Erfolg.

Jede Änderung schreibt einen Eintrag ins Prüfprotokoll der Organisation, als Urheber steht dort „SCIM“.

Fehler#

Unter /scim/v2 gilt das Fehlerformat des Protokolls, nicht das dieser API: Ein Verzeichnisdienst wertet scimType maschinell aus und entscheidet danach, ob er es erneut versucht, den Eintrag überspringt oder anhält.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "A user with this userName already exists in this organization"
}

status ist eine Zeichenkette, so schreibt es das Protokoll vor.

Weiterführendes#

• Anmeldung: Schlüssel und Sitzungen
• Basis-URL, /v1 und Stabilität
• Handbuch: Konten aus dem Personalverzeichnis (SCIM)