Дозволи API-ключів визначають, що може зламати ключ, який витік. В інструменті для посилань безпечний стандарт - це ключ, прив'язаний до одного робочого простору, обмежений найнижчою роллю, достатньою для завдання, збережений як хеш із pepper, обмежений власним лімітом частоти і налаштований на завершення дії. Ключ, який лише створює посилання, не має торкатися webhook, учасників або білінгу, і він ніколи не повинен відкривати адміністративну кінцеву точку. Це і є найменші привілеї, і більша їх частина зводиться до рішень, які ви ухвалюєте за тридцять секунд створення ключа.
За останній рік я бачив багато налаштувань автоматизації, і схема повторюється: хтось у п'ятницю після обіду вставляє свій всесильний ключ у n8n, усе працює, і про це більше ніхто не думає, доки ця людина не піде з команди або експорт робочого процесу не опиниться на спільному диску. Далі в статті розбираємо, як області дії та ролі API-ключів працюють у продукті для коротких посилань, що насправді може кожна роль і як передати ключ інструменту автоматизації, не віддаючи йому весь робочий простір.
Ця стаття доповнює наш ширший чекліст безпеки скорочувача URL, де описані сканування, підписування webhook і журнали аудиту для всієї платформи. Тут ми наближаємо камеру саме до ключа.
Що означають дозволи API-ключів в інструменті посилань
API інструмента посилань працює не лише з посиланнями. Той самий токен, який створює go.example.com/spring-sale, залежно від дозволів може читати аналітику кліків, додати власний домен, запросити учасника або зареєструвати webhook, що надсилає кожну подію на зовнішній сервер. Останнє мене найбільше насторожує. Webhook - це постійний потік даних, який той, хто його створив, може спрямувати на будь-який сервер, і ваша команда може не помітити цього тижнями.
Тому дозволи мають три осі. Де працює ключ (який обліковий запис або робочий простір)? Що він може там робити (читати, записувати, адмініструвати)? І як довго та як швидко? Визначення найменших привілеїв від NIST зводиться до надання лише того доступу, який потрібен завданню, і всі три осі є частиною цього підходу. Ключ із правами тільки для читання, який ніколи не завершує дію і не має ліміту частоти, все одно має надмірні привілеї в часі.
API-ключі з прив'язкою до робочого простору: один ключ, один робочий простір
В Elido кожен ключ створюється всередині робочого простору і залишається там. Викличте з ним кінцеві точки будь-якого іншого робочого простору - і отримаєте 404, ту саму відповідь, що й для робочого простору, якого не існує, тож ключ навіть не може підтвердити, що інші робочі простори є.
Це важливіше, ніж здається. Агенції та більші команди часто належать до п'яти або десяти робочих просторів. Якби особистий ключ успадковував усе, до чого має доступ його автор, один токен, що витік з одного клієнтського проєкту, відкрив би всіх клієнтів. API-ключі з областю дії в межах робочого простору звужують радіус ураження до одного робочого простору.
Ключ також обмежений роллю, вибраною під час створення, і ніколи не перевищує поточну роль свого автора. Ефективний доступ - це нижча з цих двох ролей. Понизьте адміністратора, який створив ключ, до editor. Ключ опуститься разом із ним. Користувацькі дозволи, прив'язані до цього учасника, теж відкидаються, коли роль ключа є нижчою, бо вони описують людину, а не ключ.
Рольові API-ключі: що може кожна роль
Ключі Elido використовують ті самі чотири ролі, що й люди: viewer, editor, admin і owner. Ви вибираєте одну під час створення ключа; якщо пропустити вибір, ключ за замовчуванням отримує editor, що покриває типове завдання автоматизації зі створення посилань і читання аналітики без адміністративного доступу.
Ось як це виглядає на практиці для речей, яких інтеграції зазвичай торкаються.
| Роль | Посилання і кампанії | Аналітика | Webhook | Домени, учасники, ключі |
|---|---|---|---|---|
| viewer | Тільки читання | Читання, запуск CSV-експортів | Перегляд кінцевих точок | Перегляд доменів і учасників |
| editor | Створення, редагування, видалення, масове створення | Читання, запуск CSV-експортів | Перегляд кінцевих точок | Перегляд доменів і учасників |
| admin | Усе, що може editor | Плюс експорти даних, заплановані звіти | Створення, зміна, повтор | Керування доменами, учасниками, ключами |
| owner | Усе | Усе | Усе | Усе |
Панелі звітності, яка переносить кількість кліків в інструмент BI, потрібен viewer. Завданню Google Sheets, яке створює кампанійні посилання, потрібен editor. Майже жодній щоденній автоматизації не потрібен admin, а ключ owner я сприймав би як тривожний сигнал: owner існує для людей, які керують робочим простором, і я не можу пригадати жодного завдання автоматизації, якому він був би потрібен.
Варто знати про два обмеження. Лише ролі admin і owner можуть створювати, переглядати або відкликати ключі, тож ключ viewer або editor не може сам створити собі ключ із ширшими правами. І жоден ключ будь-якої ролі не дістається до API адміністратора платформи. Цей API повністю відхиляє автентифікацію API-ключем із 403 і повідомленням "admin access requires an interactive session". Ключ призначений для інтеграції робочого простору, і тільки це він відкриває.
Чому керування webhook потребує ключа admin
Саме це часто дивує людей. Читати список кінцевих точок webhook дозволено будь-якому учаснику, включно з ключами viewer. Але створення кінцевої точки, зміна адреси, на яку вона вказує, або повтор доставки потребують дозволу workspace.edit, який мають лише admin і owner.
Причина - проблема постійного потоку даних, про яку йшлося вище. Editor може створити тисячу посилань, і ви це помітите. Editor, який міг би додати всеохопний webhook на власний сервер, відтоді тихо отримував би кожну подію посилання. Тому зміни webhook залишаються в руках тих самих людей, які можуть змінювати налаштування робочого простору.
На практиці налаштуйте webhook один раз вручну як admin у панелі керування. Потім дайте автоматизації, яка їх споживає, ключ editor або viewer для її API-викликів. Якщо ви підключаєте webhook для подій посилань до Slack або CRM, приймальній стороні ключ Elido взагалі не потрібен; їй потрібен секрет підпису для перевірки корисного навантаження.
Хочете доказ, перш ніж щось підключати? Створіть безкоштовний робочий простір, випустіть ключ viewer і ключ editor, а потім спробуйте той самий виклик запису з кожним із них. 403 на ключі viewer скаже більше, ніж будь-яка таблиця.
Як зберігаються ключі: pepper, хеш і префікс
Токен виглядає як elido_ плюс 52 символи base32, згенеровані з 32 випадкових байтів. Ви бачите його повністю рівно один раз, у відповіді на виклик створення. Після цього він назавжди зникає з нашого боку.
Ми зберігаємо HMAC-SHA256 від токена, обчислений із серверним pepper як ключем, який живе в конфігурації застосунку, а не в базі даних. У кожному запиті вхідний Bearer token (схема, визначена в RFC 6750) хешується так само і шукається за хешем. Викрадений дамп бази даних - це список хешів, які неможливо перевірити без pepper, а бойовий сервіс відмовляється запускатися без налаштованого pepper.
Для ваших записів ми зберігаємо перші вісім символів після elido_ як відображуваний префікс. Сторінка API-ключів показує цей префікс поруч із назвою ключа, роллю, датою створення, датою завершення дії, часом останнього використання й останньою IP-адресою, а також загальною кількістю запитів і кількістю невдалих запитів. Коли ключ з'являється десь у журналі, префікс підказує, який саме це ключ, без потреби комусь бачити повний секрет.
Ліміти частоти, завершення дії та ротація API-ключів
Кожен ключ отримує власний token bucket, окремий від ліміту робочого простору, тож один неконтрольований робочий процес не може з'їсти бюджет для всього іншого. Admin може перевизначити частоту одного ключа від 1 до 10 000 запитів на секунду і його пікове значення від 1 до 20 000 або очистити перевизначення, щоб повернутися до стандартного значення. Понад ліміт ключ отримує 429 з Retry-After: 1 і X-RateLimit-Scope: api_key, тож ваша логіка повторів може відрізнити обмеження ключа від обмеження робочого простору. Гід із лімітів частоти та ідемпотентності пояснює, як правильно робити паузи зі зростаючим інтервалом між повторами.
Завершення дії необов'язкове і задається під час створення як мітка часу RFC 3339. Коли цей час минає, ключ просто перестає збігатися. Відкликання - це один DELETE. Він теж ідемпотентний.
Окремої кнопки "rotate" немає, і я за нею не сумую. Ротація має три кроки:
- Створіть новий ключ із тією самою роллю і новою датою завершення дії.
- Замініть ним старий у сховищі облікових даних інструмента і підтвердьте, що виклик успішний.
- Відкличте старий ключ, а потім перевірте в списку, що його час останнього використання більше не рухається.
Кожен крок потрапляє до журналу аудиту робочого простору: api_key.created з назвою і роллю, api_key.revoked та api_key.rate_limit_set для перевизначень. Фонове сканування також запускається кожні п'ять хвилин і позначає будь-який ключ із понад 1 000 запитів, де більше 30% завершилися невдало. Позначка потрапляє в журнал аудиту і на сам ключ. Без автоматичного відкликання. Вимикання ключа - людське рішення, бо сплеск 404 так само часто означає зламаний робочий процес, як і нападника.
Передавання API-ключів із найменшими привілеями в n8n, Make і Zapier
Платформи автоматизації - це місце, де ключі часто забуваються. Вони лежать у сховищі облікових даних, копіюються в експортований JSON робочого процесу і живуть довше за людину, яка їх налаштувала. Допомагають дві звички:
- Один ключ на інструмент і на сімейство робочих процесів, названий за ним ("n8n: campaign sheets"). Тоді відкликання ламає рівно одну річ, а журнал аудиту показує, який інструмент що зробив.
- Editor для всього, що створює посилання, viewer для всього, що лише читає, і дата завершення дії для обох.
На цьому список закінчується; решта - питання судження. Шпаргалка OWASP із керування секретами варта прочитання про те, як не допускати токени в журнали й експорти, бо саме там ключі автоматизації зазвичай витікають.
Для налаштування конкретних інструментів гід зі скорочувача URL для n8n розміщує ключ в облікових даних Header Auth, а порівняння Make, IFTTT, n8n і Zapier пояснює, де кожна платформа його зберігає. Zapier підключається через той самий токен, як описано в покроковому посібнику з налаштування автоматизації Zapier. Для CI або будь-чого, що має пережити вихід людини з команди, краще підходить машинний користувач: сервісний обліковий запис із власною роллю, окремий від ключа будь-якої людини.
І причина, чому ключ ніколи не повинен відкривати адміністративні кінцеві точки, саме в цій передачі. Щойно токен опинився в сторонньому інструменті, будь-хто з доступом на редагування робочих процесів цього інструмента може ним скористатися. Ви довіряєте всім на їхньому боці, а не лише на своєму.
Токени з окремими областями дії заплановані, але ще не працюють
Ролі навмисно грубі, а іноді занадто грубі. Ключ editor, який лише створює посилання, також може їх видаляти, бо видалення входить до ролі editor. Виправлення - токени з окремими областями дії, наприклад links:write або analytics:read, прив'язані безпосередньо до ключа і накладені поверх ролей.
Це є в нашому плані розробки, але ще не випущено. Сьогодні дозволи ключа - це його робочий простір плюс його роль, і нічого точнішого. Якщо вам потрібен жорсткіший контроль просто зараз, два важелі - нижча роль і короткий строк дії, плюс окремі ключі для кожного завдання, щоб радіус ураження кожного був малим. Швидкий старт API і довідник API та SDK показують поточну модель ключів у робочому коді, а команди, які також хочуть контроль на рівні ідентичностей, можуть прочитати про SCIM і SSO для маркетингових інструментів.
Прочитайте наріжну статтю: чекліст безпеки скорочувача URL описує засоби контролю навколо ключа, від сканування URL до списків дозволених IP.
Також у блозі
Поширені запитання
Що таке дозволи API-ключів?
Це набір дій, які ключ може виконувати через API: які ресурси він може читати, які може змінювати і в якому обліковому записі. В Elido дозволи ключа походять від робочого простору, у якому його видали, і ролі, вибраної під час створення, тому той самий ключ не може діяти в іншому робочому просторі або вище за цю роль.
Що означає принцип найменших привілеїв для API-ключів?
Це означає, що кожен ключ отримує найменший набір дозволів, потрібний для його роботи, і нічого зайвого. Панель, яка лише читає кількість кліків, отримує ключ viewer, робочий процес, що створює посилання, отримує ключ editor, а ключі admin залишаються для рідкісних завдань із керування webhook, доменами або учасниками. Якщо ключ витече, він зможе зробити лише те, що робило одне конкретне завдання.
У чому різниця між областями дії (scopes) API-ключів і ролями?
Область дії (scope) - це вузький дозвіл, наприклад links:write, прив'язаний безпосередньо до токена, а роль - іменований набір дозволів, наприклад editor. Ролі простіше осмислювати; області дії точніші. Сьогодні ключі Elido використовують ролі робочого простору, а токени з окремими областями дії заплановані поверх них, але ще не запущені.
Як часто слід ротувати API-ключі?
Поширена рекомендація - кожні 30-90 днів, а також негайно щоразу, коли людина, яка бачила ключ, іде з команди, ключ з'являється в журналі або його трафік виглядає підозріло. Дата завершення дії, задана під час створення, перетворює цей графік на жорстку зупинку, а не на календарне нагадування, яке люди ігнорують.
Чи може API-ключ отримувати доступ до адміністративних кінцевих точок?
В Elido - ні. API адміністратора платформи приймає лише інтерактивний сеанс із входом у систему і відповідає API-ключу 403 незалежно від ролі людини, яка його створила. Налаштування робочого простору, що потребують прав admin, усе ще доступні, але тільки для ключа, створеного з роллю admin або owner.
Як API-ключі мають зберігатися на боці провайдера?
Ніколи у відкритому вигляді. Провайдер має зберігати хеш токена з ключем (HMAC) і після цього показувати вам лише короткий префікс, щоб сама копія бази даних не давала змоги викликати API. Elido хешує кожен токен через HMAC-SHA256 із pepper на боці сервера і показує повний токен рівно один раз.
Спробуйте Elido
Вставте URL - отримайте коротке посилання
Без реєстрації. Посилання живе 30 днів. Зареєструйтесь, щоб зберегти назавжди.
Безкоштовно, без реєстрації · 2 на день