SCIM-provisioning-API
- Lezen
- 4 min
- Categorie
- Proton VPN for Business
Overzicht
De SCIM (System for Cross-domain Identity Management) Provisioning-API is een standaardprotocol voor het automatiseren van de provisioning en het beheer van gebruikersidentiteiten in cloudgebaseerde toepassingen. Proton ondersteunt deze API, waarmee u gebruikersaccounts en -groepen kunt aanmaken, updaten, verwijderen en beheren. De API is gebaseerd op de SCIM 2.0-specificatie, die een gemeenschappelijk gebruikersschema en een RESTful API-interface biedt voor een eenvoudige integratie.
Proton ondersteunt de volgende identiteitsproviders:
- Okta (https://www.okta.com/(nieuw venster))
- Microsoft Entra ID
De basis-URL voor alle oproepen vanaf de identiteitsprovider is: https://scim.proton.me/{tenentId}/v2/(nieuw venster). Alle SCIM-methoden zijn vertakkingen van deze basis-URL.
Verificatie
Het token moet worden opgenomen in een Authorization header met het type Bearer bij het aanroepen van een van de SCIM-methoden. Dit token kan worden gegenereerd en vervangen in de sectie Single sign-on > SCIM automatische provisioning. Klik op de knop “Nieuwe token genereren” en kopieer het gegenereerde token.
Bijvoorbeeld:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Gebruikers
Kernattributen
| id | Een unieke identificatie voor een SCIM-resource, zoals een gebruiker, die is gedefinieerd door Proton. |
| userName (vereist) | Een unieke identificatie voor de gebruiker. Hier gebruiken we het e-mailadres als userName. |
| actief | Een booleaanse waarde die aangeeft of de gebruiker actief is. De standaardwaarde is true. |
Bewerkingen
Een gepagineerde lijst met alle gebruikers ophalen
Aanvraag
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwoord
{
"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
}
]
}Een nieuwe gebruiker aanmaken
Aanvraag
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwoord
{
"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"
}
}
Een individuele gebruiker ophalen
Aanvraag
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwoord
{
"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"
}Een gebruiker verwijderen
Aanvraag
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Groepen
Kernattributen
| id | Een unieke identificatie voor een SCIM-resource, zoals een gebruiker, die is gedefinieerd door Proton. |
| displayName | Naam voor de groep. |
| members | Een lijst met groepsleden. |
Bewerkingen
Lijst met groepen ophalen
Aanvraag
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwoord
{
"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"
}
}
]
}De details van een groep ophalen op basis van de unieke ID
Aanvraag
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Antwoord
{
"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"
}
}
Foutenafhandeling
De antwoorden zijn opgemaakt volgens RFC-7644 sectie 3.12(nieuw venster) en worden geleverd met een HTTP-statuscode die de aard van de fout aangeeft en een antwoordtekst met meer details.
Foutantwoord
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
De meest voorkomende fouten
- 400 Bad Request: De aanvraag was ongeldig of kan niet op een andere manier worden verwerkt.
- 404 Not Found: De opgevraagde bron kon niet worden gevonden.
- 409 Conflict: De aanvraag kon niet worden voltooid vanwege een conflict met de huidige status van de doelbron.
uniqueness: Er bestaat al een unieke attribuutwaarde in het systeem.
- 500 Internal Server Error: Er is een fout opgetreden aan de serverzijde.