---
title: "SCIM-API-Referenz"
description: "SCIM-2.0-Endpunktvertrag zur Bereitstellung von Benutzern und Gruppen in XID.Gruppen in XID."
locale: "de"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/de/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM-API-Referenz

## 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.

```shell
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. |

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

Source: https://xid.dev/de/scim/index.mdx