Skip to main content
Використовуйте облікові дані клієнта OAuth, коли вашій серверній інтеграції потрібні короткострокові маркери доступу або цього вимагає ваша політика безпеки. Кожен клієнт належить одному сервісному обліковому запису й одній організації. OAuth є необов’язковим: для приватної серверної інтеграції, яка може безпечно зберігати та змінювати ключ, достатньо ключа API з обмеженою областю доступу. Щоб вибрати між цими двома способами та зрозуміти, як до них належать сервісні облікові записи, див. Authentication.
Для вашої організації має бути ввімкнено доступ OAuth. Під час налаштування ви отримуєте регіональну кінцеву точку маркерів, емітента, аудиторію та метод автентифікації клієнта. Якщо вам потрібні ці параметри або ви не можете отримати доступ до керування клієнтами, зверніться до служби підтримки Living Security.
Надання облікових даних клієнта представляє ваш сервісний обліковий запис. Воно не виконує вхід користувача і не просить клієнта авторизувати застосунок. Делегована авторизація через браузер — це окрема можливість OAuth, і ці операції її не пропонують.

Перед початком

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

Створення клієнта

POST /v1/oauth_clients потребує service_account_id, непорожнього списку явно вказаних scopes та Idempotency-Key. Символи підстановки не приймаються. Клієнт підтримує до 100 областей доступу із сукупною довжиною не більше 4 096 символів. Кожен сервісний обліковий запис може мати не більше 20 клієнтів або незавершених операцій створення чи очищення. Відкликання негайно скасовує доступ до API. Клієнт або невизначене створення на стороні провайдера продовжують враховуватися в ліміті, доки не буде підтверджено віддалене очищення. Покинуте резервування або створення, яке, як доведено, завершилося помилкою до початку роботи провайдера, може безпечно звільнити свій слот. Його ключ повторення, як і раніше, належить до початкової спроби; перш ніж вирішувати, чи створювати заміну, відновіть цю квитанцію. Виберіть один ключ повторення для цієї спроби створення та збережіть його до надсилання запиту. Використовуйте від 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. Докладніше про ідентифікатори запитів і відновлення див. у розділі errors. Ніколи не надсилайте секрет клієнта чи маркер доступу із запитом до служби підтримки.

Перегляд і відкликання

Використовуйте свої облікові дані керування та id ресурсу платформи: Відкликання блокує подальші запити API для клієнта, зокрема запити з уже виданими маркерами. Воно не скасовує роботу, яку API вже прийняв. Віддалене очищення облікових даних може завершитися пізніше. Повторне відкликання безпечне й не потребує ключа повторення. Продовжуйте використовувати облікові дані керування, якщо клієнт, що відкликається, сам є викликачем API.

Заміна без втрати доступу

Створіть другого клієнта з потрібним верхнім обмеженням областей доступу. Збережіть його секрет, отримайте маркер за допомогою вашої регіональної кінцевої точки маркерів і переконайтеся, що інтеграція працює з ним. Перемкніть інтеграцію на заміну, після чого відкличте старий ресурс. Збережіть незалежні облікові дані керування, щоб мати змогу відновитися після невдалого розгортання. Маркери доступу не можуть надавати більше, ніж області доступу клієнта та поточні дозволи сервісного облікового запису. Вилучення дозволів облікового запису або відкликання клієнта мають пріоритет над часом, що залишився до завершення дії маркера. Не вважайте кешований маркер доказом того, що авторизація все ще дійсна. Отримайте новий маркер доступу до завершення терміну дії, повторно автентифікувавши клієнта; це надання не використовує маркери оновлення.