SCIM — автоматическая синхронизация пользователей и групп

SCIM 2.0 (RFC 7643, RFC 7644) — протокол для автоматического provisioning пользователей и групп из внешней системы (HR-система, корпоративный каталог, другой IdP) в directory SSO. Если ваши сотрудники или пользователи уже управляются в другой системе и вы не хотите заводить их в SSO вручную через /admin/users — это тот механизм, которым можно синхронизировать это автоматически.

---

Получение доступа

Токен для SCIM можно получить двумя способами — выбирайте в зависимости от того, нужен ли вам доступ ко всему directory платформы или только к пользователям и группам вашей организации.

Токен своей организации (обычный случай)

Если вы администратор организации или держите роль, дающую управление её пользователями, — вы можете выпустить SCIM-токен себе сами, в своей панели администратора, на странице /admin/scim-tokens. Такой токен видит и меняет только пользователей и группы вашей организации — операции с чужими данными для него не существуют (см. Область действия токена ниже).

Секрет показывается один раз сразу после создания — сохраните его сразу в свой секрет-менеджер, повторно он нигде не отображается. Отозвать токен, если он больше не нужен или скомпрометирован, можно там же, в любой момент, без обращения к администратору платформы.

---

Аутентификация

Authorization: Bearer <токен>

Код	Причина
401	Неверный, отозванный или отсутствующий токен
503	SCIM не настроен на этой платформе

---

Область действия токена

Если вы используете токен своей организации, все операции ниже автоматически ограничены ею — дополнительно ничего указывать не нужно:

Операция	Поведение
GET /Users, GET /Groups	Возвращает только пользователей/группы вашей организации
POST /Users	Созданный пользователь автоматически становится участником вашей организации
GET/PUT/PATCH конкретного пользователя/группы	404, если ресурс принадлежит другой организации — как будто его не существует
POST /Groups	Созданная группа привязывается к вашей организации
DELETE /Users/:id	Не удаляет и не блокирует аккаунт целиком. Только выводит пользователя из вашей организации — если у него был доступ за её пределами, он сохранится

Токен на весь directory (см. выше) не имеет этих ограничений — в частности, его DELETE /Users/:id деактивирует аккаунт полностью и завершает все сессии пользователя, а не только выводит его из организации.

---

Пользователи (/scim/v2/Users)

Список / поиск

GET /scim/v2/Users?filter=userName+eq+"user@example.com"&startIndex=1&count=50

Параметр	Описание
filter	userName eq "email"
startIndex	С какой записи (по умолчанию 1)
count	Сколько записей (по умолчанию 100)

Создать пользователя

POST /scim/v2/Users
Content-Type: application/json

{
	"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
	"userName": "ivan@example.com",
	"displayName": "Иван Иванов",
	"emails": [{ "value": "ivan@example.com", "primary": true }],
	"active": true
}

Пароль генерируется случайно и пользователю не сообщается — для первого входа он должен воспользоваться восстановлением пароля на стороне SSO. Ответ 201 — созданный пользователь, 409 — такой userName уже существует.

Обновить (PATCH)

PATCH /scim/v2/Users/:id
Content-Type: application/json

{
	"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
	"Operations": [
		{ "op": "replace", "value": { "active": false } },
		{ "op": "replace", "value": { "displayName": "Новое имя" } }
	]
}

Поддерживаемые поля — active (активация/приостановка), displayName, emails.

Деактивировать / вывести из организации

DELETE /scim/v2/Users/:id

Поведение зависит от того, каким токеном вы пользуетесь (см. Область действия токена): токен вашей организации выводит пользователя из неё, токен на весь directory — деактивирует аккаунт полностью и завершает все его сессии. Физического удаления записи не происходит ни в одном из случаев. Ответ 204.

---

Группы (/scim/v2/Groups)

Создать

POST /scim/v2/Groups
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "engineering",
  "members": [{ "value": "user1" }, { "value": "user2" }]
}

Управление участниками

PATCH /scim/v2/Groups/:id
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "add",    "path": "members", "value": [{ "value": "user3" }] },
    { "op": "remove", "path": "members", "value": [{ "value": "user1" }] }
  ]
}

---

Справочник ошибок

{
	"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
	"status": "404",
	"detail": "User not found"
}

Код	Причина
400	Отсутствует обязательное поле
401	Неверный токен
404	Ресурс не найден
409	Ресурс уже существует
503	SCIM не настроен на этой платформе

---

Быстрый старт

TOKEN="<секрет, показанный при создании токена на /admin/scim-tokens>"
BASE="<issuer вашего SSO>/scim/v2"

# Список пользователей
curl -H "Authorization: Bearer $TOKEN" "$BASE/Users"

# Создать пользователя
curl -X POST "$BASE/Users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"new@example.com","displayName":"Новый пользователь","active":true}'

# Деактивировать
curl -X DELETE "$BASE/Users/<id>" -H "Authorization: Bearer $TOKEN"