Drupal SCIM Server API-Endpunkte
Übersicht
Dieses Dokument beschreibt die SCIM-Endpunkte, die für die Bereitstellung und Deaktivierung von SCIM-Benutzern erforderlich sind. SCIM ist ein Industriestandardprotokoll, mit dem sich die CRUD-Operationen für Benutzer automatisieren lassen. Mithilfe des Moduls kann die Drupal-Website als SCIM-Server fungieren. Das bedeutet, dass alle Änderungen, die am Identitätsanbieter (d. h. am SCIM-Client) vorgenommen werden, mit der Drupal-Website synchronisiert werden.
SCIM-Übersicht
- Protokollversion: SCIM 2.0
- Basispfad: base_url/scim
- Unterstützte Ressourcen: Benutzer, Gruppen
- Datei Format: JSON
Authentifizierung & Header
- Zulassung: Inhaber-Token
- Content-Type: Anwendung / Json
- Akzeptieren: Anwendung / Json
Unterstützte API-Operationen
Folgende API-Operationen werden unterstützt
Benutzerendpunkte
- Benutzer deaktivieren
- Benutzer abrufen
- Benutzerliste
- Benutzeraktualisierung (PATCH)
- Benutzer aktualisieren (PUT)
- Benutzer erstellen (POST)
Gruppenendpunkte
- Gruppen auflisten
- Gruppierung nach ID
- Erstellen Sie eine Gruppe
- Gruppe aktualisieren [Attribute von Nichtmitgliedern]
- Update-Gruppe [Mitglieder]
- Gruppe löschen
Benutzerendpunkte
1. Benutzer deaktivieren (PATCH)
- Fehler:
- Beispielanfrage:
- Beispielantwort - 204 Kein Inhalt.
Um einen Benutzer in Drupal zu deaktivieren oder zu löschen, müssen Sie die entsprechenden Einstellungen im Modul aktivieren. Diese Optionen finden Sie auf der Konfigurationsseite des Moduls.
PATCH /Users/{user-id}| Fehler | Anforderungen | HTTP-Status-Code |
|---|---|---|
| Validierungsausnahme | Entweder ist das Modul nicht aktiviert oder es wird der falsche Lizenzschlüssel verwendet. | 400 |
| Unautorisierte Ausnahme | Der Autorisierungsheader ist ungültig oder fehlt. | 401 |
| ResourceNotFoundException | Der angegebene Benutzer existiert nicht. | 404 |
PATCH /Users/{user-id} HTTP/1.1 Content-Type: application/json Authorization: Bearer { "Operationen": [ { "op": "Ersetzen", "path": "aktiv", "value": false } ] }
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "4", "userName": "username", "active": , "emails": [{ "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" }], "meta": { "resourceType": "User" } }
2. Benutzer anhand seiner ID suchen
- Fehler:
- Beispielanfrage:
- Beispielantwort:
- 404 Nicht gefunden.
- 200 OK gefunden.
Um einen bereits vorhandenen Benutzer abzurufen, senden Sie eine GET-Anfrage an /Users unter Verwendung seiner Benutzer-ID.
GET /Users/{user-id}| Fehler | Anforderungen | HTTP-Status-Code |
|---|---|---|
| Validierungsausnahme | Entweder ist das Modul nicht aktiviert oder es wird der falsche Lizenzschlüssel verwendet. | 400 |
| Unautorisierte Ausnahme | Der Autorisierungsheader ist ungültig oder fehlt. | 401 |
| ResourceNotFoundException | Der angegebene Benutzer existiert nicht. | 404 |
GET /Users/{user-id} HTTP/1.1 Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Benutzer nicht gefunden", "status": 404 }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "4", "userName": "username", "active": 1, "emails": [ { "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" } ], "meta": { "resourceType": "User" } }
3. Benutzerliste
- Fehler:
- Abfrageparameter:
- Beispielanfrage:
- Beispielantwort:
- Beispielanfrage:
- Beispielantwort:
- Wenn der Benutzer mit dem angegebenen Benutzernamen nicht gefunden wird, senden wir ein leeres Schema, das anzeigt, dass kein Benutzer gefunden wurde.
- Beispielanfrage:
- Beispielantwort:
- Wenn der Benutzer die E-Mail vorlegt.
- Falls der Benutzer anhand der E-Mail-Adresse nicht gefunden werden kann, sendet das Modul ein leeres Schema, um anzuzeigen, dass der Benutzer nicht gefunden wurde.
Dieser Endpunkt ermöglicht es Ihnen, bestimmte Benutzer aus der bestehenden Benutzerliste zu filtern und abzurufen. Durch eine GET-Anfrage an den Endpunkt `/Users` und das Hinzufügen von Filterparametern können Sie die Ergebnisse anhand von Attributen wie Benutzername und E-Mail-Adresse eingrenzen. Der Endpunkt unterstützt gefilterte Suchen, kann jedoch maximal 50 Benutzerdatensätze pro Anfrage zurückgeben.
| Fehler | Anforderungen | HTTP-Status-Code |
|---|---|---|
| Validierungsausnahme | Entweder ist das Modul nicht aktiviert oder es wird der falsche Lizenzschlüssel verwendet. | 400 |
| Unautorisierte Ausnahme | Der Autorisierungsheader ist ungültig oder fehlt. | 401 |
| ResourceNotFoundException | Der angegebene Benutzer existiert nicht. | 404 |
GET /Benutzer
3.1 StartIndex und Anzahl
Es erlaubt die Angabe von startIndex und count als Abfrageparameter. Dabei ist startIndex die Start-ID und count die maximale Anzahl der Ergebnisse, die die Abfrage zurückgeben kann.
GET /Users?startIndex=1&count=50 Autorisierung: Bearer
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 2, "startIndex": 1, "itemsPerPage": 2, "Resources": [ { "id": "1", "externalId": "1", "meta": { "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "example1@example.com", "displayName": "example1@example.com", "emails": { "value": "example1@example.com", "type": "work", "primary": true }, "active": true, "name": { "familyName": "", "givenName": "" }, "groups": [ "authenticated,administrator" ], "department": "" }, { "id": "13", "externalId": "13", "meta": { "resourceType": "User" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "example2", "displayName": "example2", "emails": { "value": "example2@example.com", "type": "work", "primary": true }, "active": true, "name": { "familyName": "", "givenName": "" }, "groups": [ "authenticated,administrator" ], "department": "" }, ] }
3.2 Suche nach einem Benutzer anhand seines Benutzernamens
GET /Users?filter=userName eq "admin"
Benutzer nicht gefunden - 200 OK.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }
Benutzer gefunden - 200 OK.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 10, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "Benutzer-ID", "username": "admin", "emails": [ { "value": "email@gmail.com", "primary": true, "type": "work" } ] } ] }
3.3 Suche nach dem Benutzer anhand seiner E-Mail-Adresse
GET /Users?filter=emails[type eq "work"].value eq "email@gmail.com" Authorization: Bearer
Benutzer gefunden - 200 OK.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "startIndex": 1, "itemsPerPage": 10, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "uid des Benutzers", "username": "Benutzername", "emails": [ { "value": "email@gmail.com", "primary": true, "type": "work" } ] } ] }
Benutzer nicht gefunden - 200 OK.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "startIndex": 1, "itemsPerPage": 0, "Resources": [] }
4. Benutzeraktualisierung (PATCH)
Wird der Benutzer in der GET-Anfrage gefunden, wird eine PATCH- oder PUT-Anfrage gesendet, um den Benutzer zu aktualisieren. Andernfalls wird eine POST-Anfrage gesendet, um den Benutzer anzulegen. Sie können bestimmte Felder eines Benutzers aktualisieren, indem Sie eine PATCH- Anfrage an den Endpunkt `/Users` senden . Geben Sie im Anfragetext das zu ändernde Attribut und dessen aktualisierten Wert an.
PATCH /Users/{user-id}- Fehler:
- Beispielanfrage:
- Beispielantwort: 200 OK.
| Fehler | Anforderungen | HTTP-Status-Code |
|---|---|---|
| Validierungsausnahme | Entweder ist das Modul nicht aktiviert oder es wird der falsche Lizenzschlüssel verwendet. | 400 |
| Unautorisierte Ausnahme | Der Autorisierungsheader ist ungültig oder fehlt. | 401 |
| ResourceNotFoundException | Der angegebene Benutzer existiert nicht. | 404 |
PATCH/Users/{{user-id}} HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "Replace", "path": "emails[type eq \"work\"].value", "value": "email@gmail.com" }, { "op": "Replace", "path": "name.familyName", "value": "familyname" } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "Benutzer-ID", "userName": "Benutzername", "active": 1, "emails": [ { "primary": true, "value": "email@gmail.com", "type": "work", "display": "email@gmail.com" } ], "meta": { "resourceType": "User" } }
5. Benutzer aktualisieren (PUT)
Sie können einen Benutzer aktualisieren, indem Sie eine PUT-Anfrage an den Endpunkt /Users senden . Diese Anfrage ersetzt das gesamte Benutzerobjekt, daher müssen alle erforderlichen Benutzerattribute im Anfragetext angegeben werden.
PUT /Users/{{user-id}}- Fehler:
- Beispielanfrage:
- Beispielantwort: 200 ok.
| Fehler | Anforderungen | HTTP-Status-Code |
|---|---|---|
| Validierungsausnahme | Entweder ist das Modul nicht aktiviert oder es wird der falsche Lizenzschlüssel verwendet. | 400 |
| Unautorisierte Ausnahme | Der Autorisierungsheader ist ungültig oder fehlt. | 401 |
| ResourceNotFoundException | Der angegebene Benutzer existiert nicht. | 404 |
PUT /Users/{{user-id}} HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "97", "userName": "exmple", "active": 1, "emails": [ { "primary": true, "value": "exmple@example.com", "type": "work", "display": "exmple@example.com" } ], "meta": { "resourceType": "User" }, "name": { "givenName": "givenName", "familyName": "familyName", "middleName": "sdf", "honorificPrefix": "sdf" }, "displayName": "givenName familyName", "nickName": "df", "addresses": [ { "primary": true, "locality": "fdd" } ], "locale": "en-US", "externalId": "9rqltOOLI95d7", "Gruppen": [] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "97", "userName": "example", "active": 1, "emails": [ { "primary": true, "value": "example@example.com", "type": "work", "display": "example@example.com" } ], "meta": { "resourceType": "User" } }
6. Benutzer erstellen (POST)
Verwenden Sie eine POST-Anfrage an den Endpunkt `/Users` , um einen neuen Benutzer zu erstellen. Stellen Sie sicher, dass alle erforderlichen Felder im Anfragetext enthalten sind. Eine erfolgreiche Anfrage liefert den Statuscode 201 Created und die Benutzerdetails zurück.
POST /Users
- Fehler:
- Beispielanfrage:
- Beispielantwort: 201 erstellt.
| Fehler | Anforderungen | HTTP-Status-Code |
|---|---|---|
| Validierungsausnahme | Entweder ist das Modul nicht aktiviert oder es wird der falsche Lizenzschlüssel verwendet. | 400 |
| Unautorisierte Ausnahme | Der Autorisierungsheader ist ungültig oder fehlt. | 401 |
| Konfliktausnahme | Dieser Benutzer existiert bereits. | 409 |
POST /Users HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"], "externalId": "abc", "userName": "example", "active": true, "emails": [{ "primary": true, "type": "work", "value": "example@example.com" }], "meta": { "resourceType": "User" }, "name": { "formatted": "first name last name", "familyName": "last name", "givenName": "first name" } }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "externalId": "abc", "userName": "example", "active": true, "emails": [ { "primary": true, "type": "work", "value": "example@example.com" } ], "meta": { "resourceType": "User" }, "name": { "formatted": "first name last name", "familyName": "last name", "givenName": "first name" }, "id": "98" }
Gruppenendpunkte
1. Gruppen auflisten
Der Endpunkt „/Groups“ unterstützt GET-Anfragen zum Abrufen einer Liste der auf dem SCIM-Server verfügbaren Gruppen. Diese Operation liefert lediglich die grundlegenden Gruppeninformationen, wie Gruppen-ID und Anzeigename. Die Mitgliederliste ist immer leer, da der Endpunkt keine Details zur Gruppenmitgliedschaft in die Antwort aufnimmt.
- Beispielanfrage:
- Beispielantwort – 200 OK
- Unterstützter Filter:
- Beispielanfrage:
- Beispielantwort: 200 ok.
GET /Groups HTTP/1.1 Authorization: Bearer
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 4, "Resources": [ { "id": "anonymous", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "anonymous" }, { "id": "authenticated", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "authenticated" }, { "id": "administrator", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "administrator" }, { "id": "editor_admin", "meta": { "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "editor_admin" } ], "startIndex": 1, "itemsPerPage": 4 }
GET /Groups?filter=displayName eq "administrator"
GET /scim/Groups?filter=displayName eq "administrator" HTTP/1.1 Authorization: Bearer
Wenn eine Gruppe mit dem angegebenen Anzeigenamen gefunden wird.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 0, "Resources": [], "startIndex": 1, "itemsPerPage": 20 }
2. Gruppe nach ID durchsuchen
/Groups/{id} ruft die Gruppenressource ab, die der angegebenen Gruppen-ID zugeordnet ist. Die Antwort enthält ausschließlich die Metadaten der Gruppe. Details zur Gruppenmitgliedschaft sind nicht enthalten.
- Beispielanfrage:
- Beispielantwort:
GET /Groups/administrator HTTP/1.1 Authorization: Bearer
Gefunden - 200 OK.
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "id": "administrator", "meta": { "resourceType": "Group" }, "displayName": "Administrator" }
Nicht gefunden - 404.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "detail": "Gruppenadministrator nicht gefunden", "status": 404 }
3. Eine Gruppe erstellen
Verwenden Sie eine POST- Anfrage an /Groups , um eine neue Gruppe zu erstellen. Sie müssen einen Gruppennamen (displayName) angeben. Obwohl Sie Mitglieder im Anfragetext angeben können, liefert die Antwort immer eine leere Mitgliederliste.
- Fehler:
- Beispielanfrage:
- Anfrage ohne Angabe einer Mitgliederliste.
- Anfrage mit Mitgliederliste.
- Antwort: 201 erstellt.
| Fehler | Anforderungen | HTTP-Status-Code |
|---|---|---|
| Validierungsausnahme | Entweder ist das Modul nicht aktiviert oder es wird der falsche Lizenzschlüssel verwendet. | 400 |
| Unautorisierte Ausnahme | Der Autorisierungsheader ist ungültig oder fehlt. | 401 |
| OperationNotSupportedException | Gruppenänderungen sind nicht zulässig. | 501 |
POST /Groups HTTP/1.1 Authorization: Bearer { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "externalId": "enternal-id", "displayName": "group2", "meta": { "resourceType": "Group" } }
POST /Groups HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "group1", "members": [ { "value": "3", "display": "admin@gmail.com" }, { "value": "2", "display": "admin2@gmail.com" } ] }
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "externalId": "enternal-id", "displayName": "group2", "meta": { "resourceType": "Group" }, "members": [], "id": "group2" }
4. Gruppe aktualisieren [Attribute von Nichtmitgliedern]
Sie können die grundlegenden Details einer Gruppe, wie z. B. den Anzeigenamen, mithilfe einer PATCH-Anfrage an /Groups/{group-id} aktualisieren . Diese Anfrage aktualisiert nur die von Ihnen angegebenen Attribute und ändert nicht die Gruppenmitglieder. Eine erfolgreiche Aktualisierung gibt den Statuscode 204 No Content zurück.
- Beispielanfrage:
- Beispielantwort - 204 Kein Inhalt.
PATCH /Groups/group1 HTTP/1.1 Authorization: Bearer{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "Replace", "path": "displayName", "value": "updated group1" }] }
5. Gruppe aktualisieren [Mitglieder]
Der Endpunkt `/Groups/{id}` unterstützt das Hinzufügen und Entfernen von Mitgliedern über eine PATCH-Anfrage. Der Anfragetext muss die Liste der hinzuzufügenden Benutzer-IDs enthalten. Diese Aktion aktualisiert ausschließlich die Gruppenmitglieder und gibt bei Erfolg den Statuscode 204 (Kein Inhalt) zurück.
- Beispielanfrage:
- Füge ein Mitglied zur Gruppe hinzu.
- Das Mitglied wird aus der Gruppe entfernt.
- Beispielantwort - 204 Kein Inhalt.
PATCH /Groups/updated group1 HTTP/1.1 Content-Type: application/json Authorization: Bearer { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "Add", "path": "members", "value": [{ "$ref": null, "value": "97" }] }] }
PATCH /Groups/updated group1 HTTP/1.1 Authorization: Bearer { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "Remove", "path": "members", "value": [{ "$ref": null, "value": "97" }] }] }
6. Gruppe löschen
Der Endpunkt `/Groups/{id}` unterstützt das Löschen einer Gruppe mittels einer DELETE- Anfrage. Dadurch wird die Gruppe vom SCIM-Server entfernt. Bei erfolgreicher Löschung wird die Antwort ` 204 No Content` zurückgegeben , was bedeutet, dass die Gruppe gelöscht wurde. Es wird kein Antworttext übermittelt.
- Beispielanfrage:
- Beispielantwort - 204 Kein Inhalt.
LÖSCHEN /Groups/updated group1 HTTP/1.1 Authorization: Bearer
Falls die Konfiguration nicht erfolgreich war, kontaktieren Sie uns bitte unter drupalsupport@xecurify.com. Senden Sie uns bitte einen Screenshot des Fehlerfensters. Wir helfen Ihnen gerne bei der Problemlösung und unterstützen Sie bei der Einrichtung.
