Skip to main content
Используйте учетные данные клиента OAuth, если вашей серверной интеграции требуются кратковременные токены доступа или если этого требует ваша политика безопасности. Каждый клиент принадлежит одной сервисной учетной записи и одной организации. OAuth не является обязательным: для частной серверной интеграции, которая может безопасно хранить и ротировать ключ, достаточно API-ключа с ограниченным набором областей доступа. Чтобы выбрать один из двух методов и понять, как используются сервисные учетные записи, см. раздел Аутентификация.
Доступ к OAuth должен быть включен для вашей организации. В ходе настройки вы получите региональную конечную точку токенов, издателя (issuer), аудиторию (audience) и метод аутентификации клиента. Если вам нужны эти параметры или у вас нет доступа к управлению клиентами, обратитесь в службу поддержки Living Security.
Предоставление учетных данных клиента (client credentials grant) представляет вашу сервисную учетную запись. Оно не выполняет вход пользователя и не предлагает клиенту авторизовать приложение. Делегированная авторизация через браузер — это отдельная возможность OAuth, и данные операции ее не предоставляют.

Перед началом работы

  • Создайте сервисную учетную запись, имеющую только те разрешения, которые нужны интеграции.
  • Используйте учетные данные управления с service_account:manage и каждым разрешением, которое вы хотите предоставить новому клиенту. Целевая учетная запись также должна иметь эти разрешения. Клиент не может расширить полномочия ни одной из учетных записей.
  • Выберите регион организации. Учетные данные API и токены доступа OAuth должны использоваться на соответствующем региональном хосте API.
  • Храните секрет клиента и токены в серверном хранилище секретов. Никогда не размещайте их в коде браузера, мобильных приложениях, системе управления версиями или журналах запросов.

Создание клиента

POST /v1/oauth_clients требует service_account_id, непустой список явно указанных scopes и Idempotency-Key. Подстановочные знаки не допускаются. Клиент поддерживает до 100 областей доступа при суммарной длине не более 4 096 символов. Каждая сервисная учетная запись может иметь не более 20 клиентов или незавершенных операций создания/очистки. Отзыв немедленно блокирует доступ к API. Клиент или неопределенное создание на стороне провайдера продолжают учитываться в лимите, пока не будет подтверждена удаленная очистка. Брошенное резервирование или создание, в отношении которого доказано, что оно завершилось сбоем до начала работы провайдера, может безопасно освободить свой слот. Его ключ повторной отправки по-прежнему относится к исходной попытке; прежде чем решать, создавать ли замену, восстановите подтверждение (receipt) этой попытки. Выберите один ключ повторной отправки для этой попытки создания и сохраните его до отправки запроса. Используйте от 1 до 255 видимых символов ASCII без пробелов. Используйте его повторно с той же учетной записью, теми же областями доступа, тем же субъектом управления, регионом и версией API после потери ответа. Ротация учетных данных управления в рамках той же сервисной учетной записи не создает новую идентичность повторной отправки. Установите пакет Python requests. Загрузите следующие значения среды с помощью вашей обычной системы управления секретами и конфигурацией:
Python
Пример выполняет один запрос и хранит результат в памяти. Перед запуском в рабочей среде добавьте в отмеченном месте операцию записи вашего менеджера секретов. Пример намеренно требует принятия решения после получения неопределенного результата, а не молча создает еще одного клиента. Сетевые исключения также требуют выполнения описанных ниже шагов восстановления. Ответы на создание и подтверждения используют 201 и содержат ресурс oauth_client с полями id, service_account_id, client_id, scopes, status, created_at и client_secret. Ответы помечаются как Cache-Control: no-store.
  • id идентифицирует ресурс платформы. Сохраните его для получения данных и отзыва.
  • client_id идентифицирует клиента при обмене токенов. Это не идентификатор ресурса платформы. Пока создание находится в ожидании, он может быть null.
  • client_secret возвращается только тому запросу, который завершает создание. Каждый повторный запрос на создание возвращает null, включая повтор после потери ответа об успешном выполнении. Получение данных никогда не возвращает секрет.

Восстановление после потерянного или прерванного ответа

Повторите тот же запрос на создание с сохраненным ключом повторной отправки, чтобы восстановить подтверждение ресурса. Подтверждение отражает текущее состояние, поэтому отозванный клиент остается отозванным. Эта операция не использует общий контракт воспроизведения кэшированного ответа в течение 24 часов и не возвращает заголовок Idempotent-Replayed. Информацию об идентификаторах запросов и восстановлении см. в разделе ошибки. Никогда не отправляйте секрет клиента или токен доступа в обращении в службу поддержки.

Проверка и отзыв

Используйте ваши учетные данные управления и id ресурса платформы: Отзыв блокирует последующие запросы к API от этого клиента, включая запросы с уже выданными токенами. Он не отменяет работу, уже принятую API. Удаленная очистка учетных данных может завершиться позже. Повторный отзыв безопасен и не требует ключа повторной отправки. Продолжайте использовать учетные данные управления, если отзываемый клиент сам является вызывающей стороной API.

Ротация без потери доступа

Создайте второго клиента с требуемым максимальным набором областей доступа. Сохраните его секрет, получите токен через вашу региональную конечную точку токенов и убедитесь, что интеграция работает с ним. Переключите интеграцию на замену, затем отзовите старый ресурс. Сохраните независимые учетные данные управления, чтобы иметь возможность восстановиться после неудачного развертывания. Токены доступа не могут предоставлять больше прав, чем области доступа клиента и текущие разрешения сервисной учетной записи. Удаление разрешений учетной записи или отзыв клиента имеют приоритет над оставшимся сроком действия токена. Не считайте кэшированный токен доказательством того, что авторизация все еще действительна. Получите новый токен доступа до истечения срока действия, повторно аутентифицировав клиента; данное предоставление не использует токены обновления.