SCIM-Bereitstellungs-API
- Lesen
- 4 Min.
- Kategorie
- Proton VPN for Business
Übersicht
Die SCIM (System for Cross-domain Identity Management) Bereitstellungs-API ist ein Standardprotokoll zur Automatisierung der Bereitstellung und Verwaltung von Benutzeridentitäten in cloudbasierten Anwendungen. Proton unterstützt diese API, mit der du Benutzerkonten und -gruppen erstellen, aktualisieren, löschen und verwalten kannst. Die API basiert auf der SCIM 2.0-Spezifikation, die ein gemeinsames Benutzerschema und eine RESTful-API-Schnittstelle zur einfachen Integration bietet.
Proton unterstützt die folgenden Identitätsanbieter:
- Okta (https://www.okta.com/(neues Fenster))
- Microsoft Entra ID
Die Basis-URL für alle Aufrufe des Identitätsanbieters lautet: https://scim.proton.me/{tenentId}/v2/(neues Fenster). Alle SCIM-Methoden sind Verzweigungen dieser Basis-URL.
Authentifizierung
Das Token muss bei jedem Aufruf einer der SCIM-Methoden in einer Authorization-Kopfzeile vom Typ Bearer enthalten sein. Dieses Token kann im Bereich „Single-Sign-On > Automatische SCIM-Bereitstellung“ generiert und ersetzt werden. Klicke auf die Schaltfläche “Neues Token generieren” und kopiere das generierte Token.
Zum Beispiel:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Benutzer
Kernattribute
| id | Ein eindeutiger Bezeichner für eine SCIM-Ressource, wie z. B. einen Benutzer, der von Proton definiert wird. |
| userName (erforderlich) | Ein eindeutiger Bezeichner für den Benutzer. Hier verwenden wir die E-Mail-Adresse als userName. |
| active | Ein boolescher Wert, der angibt, ob der Benutzer aktiv ist. Der Standardwert ist true. |
Operationen
Eine paginierte Liste aller Benutzer abrufen
Anfrage
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwort
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"itemsPerPage": 1,
"startIndex": 1,
"Resources": [
{
"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true
}
]
}Neuen Benutzer erstellen
Anfrage
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwort
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true,
"meta": {
"resourceType": "User",
"created": "2024-07-25T04:39:27Z",
"lastModified": "2024-07-25T04:39:27Z",
"location": "https://scim.proton.me/{tenent-id}/v2/Users/avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"version": "1"
}
}
Einen einzelnen Benutzer abrufen
Anfrage
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwort
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true,
"meta": {
"resourceType": "User",
"created": "2024-07-24T06:22:20Z",
"lastModified": "2024-07-24T06:22:20Z",
"location": "https://scim.proton.me/{tenentId}/v2/Users/avveKyJZ_cCkUL1iBZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"version": "1"
},
"externalId": "00uganxwluxxxxxxxxxx"
}Einen Benutzer löschen
Anfrage
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Gruppen
Kernattribute
| id | Ein eindeutiger Bezeichner für eine SCIM-Ressource, wie z. B. einen Benutzer, der von Proton definiert wird. |
| displayName | Name für die Gruppe. |
| members | Eine Liste von Gruppenmitgliedern. |
Operationen
Liste der Gruppen abrufen
Anfrage
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwort
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 0,
"itemsPerPage": 100,
"startIndex": 1,
"Resources": [
{
"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
"displayName": "Admins",
"members": [
{
"value": "2819c223-7f76-453a-919d-413861904646",
"display": "John Doe"
}
],
"meta": {
"resourceType": "Group",
"created": "2024-07-25T05:10:22Z",
"lastModified": "2024-07-25T05:10:22Z",
"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
}
}
]
}Die Details einer Gruppe anhand ihrer eindeutigen ID abrufen
Anfrage
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwort
{
"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
"displayName": "Admins",
"members": [{ "value": "2819c223-7f76-453a-919d-xxxxxxxxxxxx", "display": "John Doe" }],
"meta": {
"resourceType": "Group",
"created": "2024-07-25T05:10:22Z",
"lastModified": "2024-07-25T05:10:22Z",
"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
}
}
Fehlerbehandlung
Die Antworten sind gemäß RFC-7644 Abschnitt 3.12(neues Fenster) formatiert und werden mit einem HTTP-Statuscode, der die Art des Fehlers angibt, und einem Antwort-Body geliefert, der weitere Details enthält.
Fehlerantwort
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Die häufigsten Fehler
- 400 Bad Request: Die Anfrage war ungültig oder kann anderweitig nicht verarbeitet werden.
- 404 Not Found: Die angeforderte Ressource konnte nicht gefunden werden.
- 409 Conflict: Die Anfrage konnte aufgrund eines Konflikts mit dem aktuellen Zustand der Zielressource nicht abgeschlossen werden.
uniqueness: Ein eindeutiger Attributwert existiert bereits im System.
- 500 Internal Server Error: Auf Serverseite ist ein Fehler aufgetreten.