API de provisionnement SCIM
- Lecture
- 4 minutes
- Catégorie
- Proton VPN for Business
Présentation
L’API de provisionnement SCIM (System for Cross-domain Identity Management) est un protocole standard permettant d’automatiser le provisionnement et la gestion des identités utilisateur dans les applications cloud. Proton prend en charge cette API, qui vous permet de créer, mettre à jour, supprimer et gérer des comptes d’utilisateur et des groupes. L’API est basée sur la spécification SCIM 2.0, qui fournit un schéma utilisateur commun et une interface API RESTful pour faciliter l’intégration.
Proton prend en charge les fournisseurs d’identité suivants :
- Okta (https://www.okta.com/(nouvelle fenêtre))
- Microsoft Entra ID
L’URL de base pour tous les appels du fournisseur d’identité est : https://scim.proton.me/{tenentId}/v2/(nouvelle fenêtre). Toutes les méthodes SCIM sont des branches de cette URL de base.
Authentification
Le jeton doit être inclus dans un en-tête d’autorisation avec le type Bearer lors de l’appel de l’une des méthodes SCIM. Ce jeton peut être généré et remplacé dans la section Single-sign-on > Provisionnement automatique SCIM. Cliquez sur le bouton “Générer un nouveau jeton” et copiez le jeton généré.
Par exemple :
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Utilisateurs
Attributs principaux
| id | Un identifiant unique pour une ressource SCIM, telle qu’un utilisateur, qui est défini par Proton. |
| userName (requis) | Un identifiant unique pour l’utilisateur. Ici, nous utilisons l’adresse e-mail comme userName. |
| active | Un booléen indiquant si l’utilisateur est actif. La valeur par défaut est true. |
Opérations
Récupérer une liste paginée de tous les utilisateurs
Requête
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Réponse
{
"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
}
]
}Créer un nouvel utilisateur
Requête
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Réponse
{
"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"
}
}
Récupérer un seul utilisateur
Requête
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Réponse
{
"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"
}Supprimer un utilisateur
Requête
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Groupes
Attributs principaux
| id | Un identifiant unique pour une ressource SCIM, telle qu’un utilisateur, qui est défini par Proton. |
| displayName | Nom du groupe. |
| members | Une liste des membres du groupe. |
Opérations
Obtenir la liste des groupes
Requête
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Réponse
{
"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"
}
}
]
}Récupérer les détails d’un groupe par son ID unique
Requête
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Réponse
{
"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"
}
}
Gestion des erreurs
Les réponses sont formatées selon la section 3.12 de la norme RFC-7644(nouvelle fenêtre), et sont fournies avec un code d’état HTTP indiquant la nature de l’erreur ainsi qu’un corps de réponse apportant plus de détails.
Réponse d’erreur
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Les erreurs les plus fréquentes
- 400 Bad Request : la requête était invalide ou ne peut pas être traitée autrement.
- 404 Not Found : la ressource demandée n’a pas pu être trouvée.
- 409 Conflict : la requête n’a pas pu être complétée en raison d’un conflit avec l’état actuel de la ressource cible.
uniqueness: une valeur d’attribut unique existe déjà dans le système.
- 500 Internal Server Error : une erreur est survenue côté serveur.