API SCIM-подготовки
- Чтение
- 2 мин.
- Категория
- Proton VPN for Business
Обзор
API-интерфейс для подготовки учётных записей SCIM (System for Cross-domain Identity Management) — это стандартный протокол для автоматизации создания и управления личными данными пользователей в облачных приложениях. Proton поддерживает этот API, который позволяет вам создавать, обновлять, удалять и управлять аккаунтами пользователей и группами. API основан на спецификации SCIM 2.0, которая предоставляет общую схему пользователей и RESTful API-интерфейс для удобства интеграции.
Proton поддерживает следующие личные данные:
- Okta (https://www.okta.com/(новое окно))
- Microsoft Entra ID
Базовый URL для всех вызовов от провайдера личных данных — это: https://scim.proton.me/{tenentId}/v2/(новое окно). Все методы SCIM являются ветвями этого базового URL.
Аутентификация
Токен должен быть включен в заголовок Authorization с типом Bearer при вызове любого из методов SCIM. Этот токен можно сгенерировать и заменить в разделе Single-sign-on > SCIM automatic provisioning. Нажмите кнопку “Сгенерировать токен” и скопируйте созданный токен.
Например:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Пользователи
Основные атрибуты
| id | Уникальный идентификатор для ресурса SCIM, например пользователь, который определяется Proton. |
| имя пользователя (обязательно) | Уникальный идентификатор пользователя. Здесь мы используем электронное письмо как имя пользователя. |
| активен | Логическое значение, указывающее, активен ли пользователь. По умолчанию — true. |
Операции
Получить список всех пользователей с разбивкой на страницы
Запрос
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Ответ
{
"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
}
]
}Создать нового пользователя
Запрос
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Ответ
{
"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"
}
}
Получить одного пользователя
Запрос
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Ответ
{
"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"
}Удалить пользователя
Запрос
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Группы
Основные атрибуты
| id | Уникальный идентификатор для ресурса SCIM, например пользователь, который определяется Proton. |
| displayName | Имя для группы. |
| участники | Список участников группы. |
Операции
Получить список групп
Запрос
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Ответ
{
"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"
}
}
]
}Получить информацию о группе по её уникальному ID
Запрос
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Ответ
{
"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"
}
}
Обработка ошибок
Ответы отформатированы в соответствии с разделом 3.12 RFC-7644(новое окно), доставляются с кодом состояния HTTP, указывающим на характер ошибки, и содержат тело ответа, предоставляющее Подробнее.
Ответ с ошибкой
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Наиболее распространенные ошибки
- 400 Bad Request: Запрос был неверным или не может быть обработан.
- 404 Not Found: Запрошенный ресурс не найден.
- 409 Conflict: Запрос не может быть выполнен из-за конфликта с текущим состоянием целевого ресурса.
uniqueness: Уникальное Значение атрибута уже существует в системе.
- 500 Internal Server Error: Произошла ошибка на стороне сервера.