API di provisioning SCIM
- Lettura
- 4 minuti
- Categoria
- Proton VPN for Business
Panoramica
L’API di provisioning SCIM (System for Cross-domain Identity Management) è un protocollo standard per automatizzare il provisioning e la gestione delle identità degli utenti nelle applicazioni basate su cloud. Proton supporta questa API, che ti consente di creare, aggiornare, eliminare e gestire account e gruppi di utenti. L’API si basa sulla specifica SCIM 2.0, che fornisce uno schema utente comune e un’interfaccia API RESTful per facilitare l’integrazione.
Proton supporta i seguenti fornitori di identità:
- Okta (https://www.okta.com/(nuova finestra))
- Microsoft Entra ID
L’URL di base per tutte le chiamate dal fornitore di identità è: https://scim.proton.me/{tenentId}/v2/(nuova finestra). Tutti i metodi SCIM sono diramazioni di questo URL di base.
Autenticazione
Il token deve essere incluso in un’intestazione Authorization di tipo Bearer durante la chiamata a uno qualsiasi dei metodi SCIM. Questo token può essere generato e sostituito nella sezione Single-sign-on > Provisioning automatico SCIM. Clicca sul pulsante “Genera nuovo token” e copia il token generato.
Per esempio:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Utenti
Attributi principali
| id | Un identificatore univoco per una risorsa SCIM, come un utente, definito da Proton. |
| userName (richiesto) | Un identificatore univoco per l’utente. Qui utilizziamo l’email come userName. |
| active | Un booleano che indica se l’utente è attivo. Il valore predefinito è true. |
Operazioni
Recupera un elenco impaginato di tutti gli utenti
Richiesta
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Risposta
{
"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
}
]
}Crea un nuovo utente
Richiesta
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Risposta
{
"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"
}
}
Recupera un singolo utente
Richiesta
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Risposta
{
"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"
}Elimina un utente
Richiesta
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Gruppi
Attributi principali
| id | Un identificatore univoco per una risorsa SCIM, come un utente, definito da Proton. |
| displayName | Nome per il gruppo. |
| members | Un elenco dei membri del gruppo. |
Operazioni
Ottieni l’elenco dei gruppi
Richiesta
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Risposta
{
"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"
}
}
]
}Recupera i dettagli di un gruppo tramite il suo ID univoco
Richiesta
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Risposta
{
"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"
}
}
Gestione degli errori
Le risposte sono formattate in base alla sezione 3.12 della specifica RFC-7644(nuova finestra) e vengono fornite con un codice di stato HTTP che indica la natura dell’errore e un corpo della risposta che fornisce maggiori dettagli.
Risposta di errore
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Gli errori più comuni
- 400 Bad Request: la richiesta non è valida o non può essere altrimenti soddisfatta.
- 404 Not Found: la risorsa richiesta non è stata trovata.
- 409 Conflict: non è stato possibile completare la richiesta a causa di un conflitto con lo stato corrente della risorsa di destinazione.
uniqueness: un valore dell’attributo univoco esiste già nel sistema.
- 500 Internal Server Error: si è verificato un errore sul lato server.