Использование 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

Чтобы использовать SCIM API, сначала необходимо создать пользовательское приложение 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.

Атрибут пользователя Cato

Описание

userName

Имя пользователя для аутентификации

user.firstName

Имя пользователя

user.lastName

Фамилия пользователя

user.email

Адрес электронной почты

user.displayName

Отображаемое имя пользователя

phoneNumbers[type eq "work"].value

Рабочий номер телефона пользователя (включая префикс)

externalId

ID для пользователя (используется в событиях)

Атрибут группы пользователей Cato

Описание

активен

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

displayName

Имя группы пользователей

участники

Пользователи, принадлежащие к группе пользователей

externalId

ID для группы пользователей (используется в событиях)

Понимание 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} выполняет жесткое удаление. Группа удалена навсегда.

Была ли эта статья полезной?

Пользователи, считающие этот материал полезным: 0 из 0

0 комментариев