Использование SCIM API Cato для пользовательских приложений SCIM

Эта статья описывает, как использовать SCIM API Cato для предоставления пользователей и групп пользователей с провайдером идентификации (IdP).

Для получения дополнительной информации о пользовательских SCIM-приложениях в арендаторе IdP смотрите Создание пользовательского SCIM-приложения для IdP.

Пользовательское SCIM-приложение Cato

Чтобы использовать пользовательское приложение SCIM для предоставления пользователей и групп пользователей в вашей учетной записи Cato, создайте приложение в Cato Management Application (CMA). Кроме того, вам необходимо сопоставить атрибуты SCIM Cato с атрибутами вашего IdP.

Создание пользовательского SCIM-приложения в CMA

Чтобы использовать API SCIM, сначала необходимо создать пользовательское SCIM приложение в CMA. Это приложение позволяет интегрировать ваш провайдер идентификации (IdP) с платформой Cato.

Чтобы создать пользовательское SCIM приложение в CMA:

1. В меню навигации выберите Доступ > Службы каталогов.

2. В разделе SCIM нажмите Новое.

3. Введите имя для приложения.

4. В разделе Провайдер, выберите Пользовательский.

5. Нажмите Создать токен и скопируйте значение; оно будет недоступно после сохранения, и потребуется создать новый токен. 

6. Нажмите Сохранить.

7. При вызове конечных точек SCIM API, описанных ниже, вам понадобятся следующие значения для аутентификации:

   • SCIM Base URL: используется в качестве базового пути для API запросов

   • Bearer Token: используется для аутентификации API запросов

Атрибуты SCIM от Cato

Это SCIM атрибуты для пользователей и групп пользователей от Cato, которые необходимо сопоставить с соответствующими атрибутами IdP.

Понимание SCIM API Cato

Аутентификация в SCIM API Cato

Клиенты аутентифицируются в SCIM API, используя аутентификацию с токеном типа bearer, как определено RFC 6750. Все запросы API должны включать следующие заголовки HTTP:

Authorization: Bearer <access_token>
Content-Type: application/json

Вы можете получить токен доступа из Cato Management Application.

Базовый путь для конечных точек SCIM

Все конечные точки SCIM API используют следующий базовый путь:

/scim/v2/{accountId}/{sourceId}

Параметры пути: 

• accountId (строка): Уникальный идентификатор вашего учетного аккаунта арендатора Cato

• sourceId (целое число): Идентификатор, назначенный Cato для уникального представления конкретной интеграции IdP

Эти параметры требуются во всех запросах, но опущены в путях отдельных конечных точек в этой статье для краткости.

Управление пользователями

Этот раздел описывает, как создавать, обновлять, удалять и извлекать сущности пользователей SCIM с использованием SCIM API Cato.

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

HTTP метод:POST /Users 

Обязательные поля: 

• userName (строка): Уникальное имя пользователя (например, адрес электронной почты)

• externalId (строка): Внешний идентификатор от IdP

• active (логическое): Должен быть true, чтобы активировать пользователя

Примечание:id возвращается службой SCIM и должен использоваться в последующих вызовах API. externalId необязателен и не может использоваться в путях API.

Ответ: 

• Статус: 201 Created

Ошибки: 

• 400 Bad Request: Неверная схема

• 401 Unauthorized 

• 409 Conflict: Дубликат userName или externalId

Обновление пользователя

PUT

HTTP метод:PUT /Users/{id} 

Обязательное поле: 

• id: Внутренний SCIM ID от Cato

Ответ: 

• Статус: 200 OK

Ошибки: 

• 401 Unauthorized 

• 404 Not Found 

• 409 Conflict: Дубликат userName или externalId

PATCH

HTTP метод:PATCH /Users/{id} 

Ответ: 

• Статус: 200 OK

Ошибки: 

• 400 Bad Request: Недопустимая схема или синтаксис патча

• 401 Unauthorized 

• 404 Not Found 

• 409 Conflict: Дублирующиеся идентификаторы

Удаление пользователя

HTTP метод:DELETE /Users/{id}

Ответ:

• Статус: 204 No Content

Это мягкое удаление. Пользователь остается в системе, но не возвращается в поиске.

Получение пользователя по ID

HTTP метод:GET /Users/{id}

Ответ:

• Статус: 200 OK

Ошибки:

• 401 Unauthorized

• 404 Not Found

Поиск пользователей

HTTP метод:GET /Users

Параметры запроса:

• filter: Запрос для фильтрации пользователей (например, userName eq "user@domain.com")

• count (опционально)

• startIndex (опционально)

Поддерживаемые фильтры:

• Поддерживается только eq

• Поддерживаемые атрибуты: userName, email, givenName, familyName

• Составные фильтры поддерживаются только в этом формате:

  filter=emails[type eq "work"] и email eq "bob@cato.com"

Ответ:

• Статус: 200 OK

Ошибки:

• 401 Unauthorized

Управление группами

Этот раздел объясняет, как использовать SCIM API для создания, обновления, удаления и получения сущностей группы в вашей среде Cato.

Создать группу

HTTP метод:POST /Groups

Ответ:

• Статус: 201 Created

Ошибки:

• 401 Unauthorized

• 409 Conflict: Дубликат displayName или ID объекта

Обновить группу

PUT

HTTP метод:PUT /Groups/{id}

Ответ:

• Статус: 200 OK

Ошибки:

• 401 Unauthorized

• 404 Not Found

• 409 Conflict

PATCH

HTTP метод:PATCH /Groups/{id}

Поддерживаемые пути Patch:

• displayName

• members

Ответ:

• Статус: 200 OK

Ошибки:

• 400 Bad Request: Недопустимая схема или синтаксис патча

• 401 Unauthorized

• 404 Not Found

• 409 Conflict

Удалить группу

HTTP метод:DELETE /Groups/{id}

Ответ:

• Статус: 204 No Content

Важно:

Это жесткое удаление. Группа удалена навсегда.

Получить группу по ID

HTTP метод:GET /Groups/{id}

Необязательные параметры запроса:

• excludeAttributes (например, members)

Ответ:

• Статус: 200 OK

Ошибки:

• 401 Unauthorized

• 404 Not Found

Поиск групп

HTTP метод:GET /Groups

Параметры запроса:

• filter: Поддерживается только displayName eq "Group Name"

• count (опционально)

• startIndex (опционально)

Комплексные фильтры или неподдерживаемые операторы возвращают все группы без фильтрации.

Ответ:

• Статус: 200 OK

Ошибки:

• 401 Unauthorized

Примечание

Поведение поля id при создании

• Поле id является необязательным в запросах на создание пользователей и групп.

• Если поле опущено, служба SCIM генерирует уникальный id.

• Всегда используйте возвращенное значение id в последующих вызовах API.

Важно:

Избегайте использования ID, сгенерированных клиентом, если это не требуется. SCIM id является авторитетным идентификатором.

Поведение при удалении

• Удаление пользователя через DELETE /Users/{id} выполняет мягкое удаление, устанавливая поле active в false. Пользователь доступен через GET /Users/{id} но исключен из результатов GET /Users.

• Удаление группы через DELETE /Groups/{id} выполняет жесткое удаление. Группа удалена навсегда.