SCIM-API-Referenz

SCIM-2.0-Endpunktvertrag zur Bereitstellung von Benutzern und Gruppen in XID.Gruppen in XID.

Basis-URL

XID stellt organisationsbezogene SCIM-2.0-APIs unter /scim/v2/organizations/{organization_id} bereit. Benutzer- und Gruppenressourcen werden über die Organisations-ID im Pfad adressiert.

Konfigurieren Sie Ihren Identitätsanbieter mit der Basis-URL https://xid.dev/scim/v2/organizations/{organization_id} und das Verzeichnis-Token, das beim Erstellen oder Rotieren des Verzeichnisses einmalig angezeigt wird.

curl https://xid.dev/scim/v2/organizations/{organization_id}/Users \
  -H 'Authorization: Bearer scim_xxx' \
  -H 'Content-Type: application/scim+json'

Authentifizierung

SCIM-Aufrufe verwenden ein Verzeichnis-Bearer-Token, das über die Management-API erstellt wurde. XID speichert nur einen Hash des Tokens und gibt das Klartext-Token nur einmal beim Erstellen oder Rotieren zurück.

Kopfbereich	Wert	Hinweise
`Authorization`	`Bearer scim_xxx`	Erforderlich für organisationsbezogene Benutzer- und Gruppenendpunkte.
`Content-Type`	`application/scim+json`	Erforderlich für POST-, PUT- und PATCH-Anfragen.
`Accept`	`application/scim+json`	Für alle SCIM-Clients empfohlen.

Endpunkte

Endpunkt	Methoden	Verwenden
`/scim/v2/ServiceProviderConfig`	`GET`	ServiceProviderConfig-Antwort für die SCIM-Client-Erkennung.
`/scim/v2/Schemas`	`GET`	Schema-Metadaten für Benutzer und Gruppen.
`/scim/v2/ResourceTypes`	`GET`	Unterstützte SCIM-Ressourcentypen.
`/scim/v2/organizations/{organization_id}/Users`	`GET, POST`	Verzeichnisbenutzer erstellen und auflisten.
`/scim/v2/organizations/{organization_id}/Users/{id}`	`GET, PUT, PATCH, DELETE`	Einen Verzeichnisbenutzer lesen, ersetzen, teilweise aktualisieren oder deprovisionieren.
`/scim/v2/organizations/{organization_id}/Groups`	`GET, POST`	Verzeichnisgruppen erstellen und auflisten.
`/scim/v2/organizations/{organization_id}/Groups/{id}`	`GET, PUT, PATCH, DELETE`	Eine Verzeichnisgruppe lesen, ersetzen, teilweise aktualisieren oder entfernen.

Benutzerressource

Benutzerressourcen verwenden userName als externe Kennung. E-Mail-Werte, Profilnamensfelder, aktiver Status und Enterprise-Erweiterungsfelder bleiben im SCIM-Rohprofil erhalten.

SCIM-Feld	XID-Verhalten
`id`	Stabile XID-Verzeichnisbenutzer-ID.
`userName`	Erforderlich. Muss innerhalb des Verzeichnisses eindeutig sein.
`active`	`false` hebt die Benutzerbereitstellung auf und widerruft aktive Sitzungen.
`emails`	Die primäre E-Mail wird für Zuordnung und Kontoverknüpfung verwendet.
`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`	Wird für Enterprise-Attribute wie Abteilung gespeichert und zurückgegeben.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "alice@example.com",
  "active": true,
  "name": { "givenName": "Alice", "familyName": "Lee" },
  "emails": [{ "value": "alice@example.com", "primary": true }]
}

Gruppenressource

Gruppenressourcen verwenden displayName als eindeutigen Verzeichnisgruppennamen. Mitglieder referenzieren SCIM-Benutzer-IDs und werden idempotent synchronisiert.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    { "value": "dir_user_123", "display": "alice@example.com" }
  ]
}

Filtern, Sortieren und Paginierung

XID unterstützt SCIM-Filtergrammatik mit and, or, not und Vergleichsoperatoren (eq, ne, co, sw, ew, gt, ge, lt, le, pr). Nicht unterstützte Ausdrücke liefern invalidFilter. Listen nutzen SCIM-Paginierung ab 1 mit startIndex, count, totalResults sowie optional sortBy und sortOrder.

Abfrage	Unterstützung
`filter=userName eq "alice@example.com"`	Einen Benutzer nach userName finden.
`filter=displayName eq "Engineering"`	Eine Gruppe nach displayName finden.
`filter=userName sw "alice" and active eq true`	Logische und Vergleichsoperatoren kombinieren.
`sortBy=userName&sortOrder=ascending`	Benutzer- oder Gruppenlisten sortieren.
`startIndex=1&count=100`	Bis zu 100 Ressourcen ab dem ersten Ergebnis zurückgeben.
`attributes=userName,emails.value`	Nur schemas, id und die angeforderten SCIM-Attribute zurückgeben.
`excludedAttributes=emails,meta`	Die Standardressource ohne die ausgeschlossenen SCIM-Attribute zurückgeben.

Massenvorgänge

POST /scim/v2/organizations/{organization_id}/Bulk akzeptiert eine BulkRequest mit bis zu 100 Operationen und 1 MiB Nutzlast. Antworten liefern pro Operation den HTTP-Status in einer BulkResponse, auch wenn einzelne Operationen fehlschlagen.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "user1",
      "data": { "userName": "alice@example.com", "active": true }
    }
  ]
}

ETag and If-Match

Resource-GET-Antworten enthalten ETag: W/"<meta.version>" aus meta.version. PUT und PATCH erfordern einen If-Match-Header zur aktuellen Version; fehlend → 428, Abweichung → 412.

PATCH-Operationen

PATCH-Anfragen verwenden urn:ietf:params:scim:api:messages:2.0:PatchOp. XID unterstützt add, replace und remove für beschreibbare Profilfelder und Gruppenmitgliedschaften.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

Fehlerantworten

SCIM-Fehler geben application/scim+json mit SCIM-Error-Schema, HTTP-Status, Detail und optionalem scimType zurück.

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

ServiceProviderConfig-Fähigkeiten

ServiceProviderConfig bewirbt sort.supported=true, bulk.supported=true und etag.supported=true.
XID stellt eingehende SCIM Service Provider-Endpunkte für externe IdPs bereit. SCIM-Push-Clients für nachgelagerte SaaS-Dienste verfügen über lokale Evidenz mit simuliertem SaaS, doch Produktionsunterstützung erfordert weiterhin einen echten SaaS-Administrator-L4.

Deprovisioning-Verhalten

Bei der Verzeichnis-Token-Rotation bleibt das vorherige Token für ein kurzes Kulanzfenster gültig.
active=false und DELETE /Users/{id} die Benutzerbereitstellung aufheben und aktive Sitzungen widerrufen.
Aktualisierungen von Gruppenmitgliedschaften sind idempotent. Unbekannte Mitglieder können aufgelöst werden, nachdem der Benutzer vom Identitätsanbieter eingetroffen ist.