API de aprovisionamiento SCIM
- Lectura
- 4 minutos
- Categoría
- Proton VPN for Business
Descripción general
La API de aprovisionamiento SCIM (System for Cross-domain Identity Management) es un protocolo estándar para automatizar el aprovisionamiento y la gestión de identidades de usuario en aplicaciones basadas en la nube. Proton ofrece soporte para esta API, la cual le permite crear, actualizar, eliminar y gestionar cuentas de usuario y grupos. La API se basa en la especificación SCIM 2.0, que proporciona un esquema de usuario común y una interfaz de API RESTful para facilitar la integración.
Proton admite los siguientes proveedores de identidad:
- Okta (https://www.okta.com/(nueva ventana))
- Microsoft Entra ID
La URL base para todas las llamadas del proveedor de identidad es: https://scim.proton.me/{tenentId}/v2/(nueva ventana). Todos los métodos SCIM son ramas de esta URL base.
Autenticación
El token debe incluirse en un encabezado Authorization con un tipo de Bearer al llamar a cualquiera de los métodos SCIM. Este token puede ser generado y reemplazado en la sección Single-sign-on > SCIM automatic provisioning. Haga clic en el botón “Generar nuevo token” y copie el token generado.
Por ejemplo:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Usuarios
Atributos principales
| id | Un identificador único para un recurso SCIM, como un usuario, que es definido por Proton. |
| nombre de usuario (requerido) | Un identificador único para el usuario. Aquí usamos el correo electrónico como Nombre de usuario. |
| activa | Un booleano que indica si el Usuario está Activa. El valor por defecto es true. |
Operaciones
Recuperar una lista paginada de Todos los usuarios
Solicitud
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respuesta
{
"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
}
]
}Crear un nuevo usuario
Solicitud
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respuesta
{
"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"
}
}
Recuperar un solo Usuario
Solicitud
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respuesta
{
"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"
}Eliminar un usuario
Solicitud
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Grupos
Atributos principales
| id | Un identificador único para un recurso SCIM, como un usuario, que es definido por Proton. |
| displayName | Nombre para el grupo. |
| miembros | Una Lista de miembros del grupo. |
Operaciones
Obtener Lista de Grupos
Solicitud
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respuesta
{
"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"
}
}
]
}Recuperar los detalles de un grupo mediante su ID único
Solicitud
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respuesta
{
"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"
}
}
Manejo de error
Las respuestas están formateadas siguiendo RFC-7644 sección 3.12(nueva ventana), las cuales se entregan con un código de Estado HTTP que indica la naturaleza del error y un cuerpo de respuesta que proporciona más detalles.
Respuesta de error
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Los errores Más comunes
- 400 Solicitud Incorrecta: La solicitud no era válida o no puede ser procesada de otra manera.
- 404 No Encontrado: No se pudo encontrar el recurso solicitado.
- 409 Conflicto: No se pudo completar la solicitud debido a un conflicto con el estado actual del recurso de destino.
uniqueness: Un Valor de atributo único ya existe en el Sistema.
- 500 error interno del servidor: Ocurrió un error en el lado del servidor.