SCIM-Benutzerbereitstellung
Administratoren automatisch aus Ihrem Identity Provider anlegen, aktualisieren und deaktivieren (SCIM 2.0).
Voraussetzungen
- Ein API-Schlüssel mit den erforderlichen Bereichen
- Ein aktiver PlanDocket-Account
SCIM aktivieren und Token erzeugen
Öffnen Sie im Admin-Bereich unter Einstellungen > SSO Ihren Identity Provider, aktivieren Sie die SCIM-Bereitstellung und erzeugen Sie ein Bearer-Token. Tragen Sie in Ihrem Identity Provider (z. B. Microsoft Entra ID, Okta) die SCIM-Basis-URL https://ihr-mandant.plandocket.com/scim/v2 und dieses Token ein. Jede Anfrage benötigt den Header "Authorization: Bearer <Token>"; Antworten haben den Content-Type application/scim+json. Bewahren Sie das Token sicher auf: Es gewährt Schreibzugriff auf Administrator-Konten.
Verbindung prüfen (Discovery)
Die Discovery-Endpunkte ServiceProviderConfig, Schemas und ResourceTypes beschreiben die unterstützten Funktionen: PATCH und Filter werden unterstützt (max. 100 Ergebnisse pro Seite, Paginierung über startIndex und count), Bulk, Sortierung, ETags und Passwortänderungen nicht.
curl -X GET "https://ihr-mandant.plandocket.com/scim/v2/ServiceProviderConfig" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Accept: application/scim+json"Benutzer anlegen
POST /scim/v2/Users legt einen Administrator an. userName (die E-Mail-Adresse) ist erforderlich; die E-Mail-Domain muss für den Identity Provider zugelassen sein. Ein bestehendes reines SSO-Konto mit derselben E-Mail-Adresse wird verknüpft statt doppelt angelegt; ein lokales Passwort-Konto oder ein bereits per SCIM bereitgestelltes Konto wird mit 409 (uniqueness) abgelehnt. Ist die maximale Anzahl an Administratoren Ihres Tarifs erreicht, antwortet sie mit 403.
curl -X POST "https://ihr-mandant.plandocket.com/scim/v2/Users" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"externalId": "00u1abcd",
"userName": "max.mustermann@acme.example",
"name": {"givenName": "Max", "familyName": "Mustermann"},
"emails": [{"value": "max.mustermann@acme.example", "primary": true}],
"active": true
}'Benutzer suchen
GET /scim/v2/Users unterstützt die Filter "userName" bzw. "emails.value" mit eq, co, sw oder ew sowie "externalId eq" und "id eq". Andere Filter werden mit 400 (invalidFilter) abgelehnt.
curl -G "https://ihr-mandant.plandocket.com/scim/v2/Users" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
--data-urlencode 'filter=userName eq "max.mustermann@acme.example"' \
--data-urlencode 'startIndex=1' \
--data-urlencode 'count=25'Benutzer ändern oder deaktivieren
PATCH /scim/v2/Users/{id} unterstützt die Operationen add, replace und remove; PUT ersetzt den Benutzer vollständig. Mit "active": false wird das Konto deaktiviert und laufende Anmeldungen enden. DELETE löscht das Konto nicht, sondern deaktiviert es, damit Protokolle und Zuordnungen erhalten bleiben; der SCIM-Benutzer ist danach nicht mehr abrufbar (404). Super-Admin-Konten sind geschützt und können per SCIM weder geändert noch deaktiviert werden.
curl -X PATCH "https://ihr-mandant.plandocket.com/scim/v2/Users/SCIM_USER_ID" \
-H "Authorization: Bearer YOUR_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}
]
}'Gruppen und Rollen
Gruppen werden über /scim/v2/Groups bereitgestellt (Filter: "displayName eq", "externalId eq", "id eq"). Ordnen Sie in den Einstellungen des SSO-Providers den Gruppen PlanDocket-Rollen zu: Mitglieder erhalten die Rolle der zugeordneten Gruppe, Benutzer ohne zugeordnete Gruppe die Standardrolle des Providers. Wird ein Benutzer aus allen zugeordneten Gruppen entfernt oder die Gruppe gelöscht, erhält er wieder die Standardrolle. Die Super-Admin-Rolle wird nie per SCIM vergeben.
curl -X POST "https://ihr-mandant.plandocket.com/scim/v2/Groups" \
-H "Authorization: Bearer YOUR_SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "PlanDocket Editors",
"members": [{"value": "SCIM_USER_ID"}]
}'