Разрешения API-ключа определяют, какой ущерб может нанести утёкший ключ. Для инструмента ссылок безопасный вариант по умолчанию - ключ, привязанный к одному рабочему пространству, ограниченный минимальной нужной ролью, хранимый в виде хеша с pepper, с собственным лимитом запросов и сроком действия. Ключ, который только создаёт ссылки, не должен иметь доступа к webhook, участникам или оплате и никогда не должен открывать административный endpoint. В этом и состоит принцип минимальных привилегий, а большая его часть сводится к решениям, которые вы принимаете за тридцать секунд создания ключа.
За прошедший год я видел множество настроек автоматизации, и картина повторяется: в пятницу днём кто-то вставляет свой всесильный ключ в n8n, всё работает, и никто больше об этом не думает, пока этот человек не уходит или экспорт сценария не оказывается на общем диске. Далее я расскажу, как работают области действия и роли API-ключей в продукте коротких ссылок, что фактически может делать каждая роль и как передать ключ инструменту автоматизации, не отдавая ему всё рабочее пространство.
Этот материал дополняет наш более широкий чек-лист безопасности сокращателя URL, где рассматриваются сканирование, подпись webhook и журналы аудита на уровне всей платформы. Здесь внимание сосредоточено на самом ключе.
Что означают разрешения API-ключа в инструменте ссылок
API инструмента ссылок работает не только со ссылками. Один токен, создающий go.example.com/spring-sale, в зависимости от разрешений может читать аналитику кликов, добавлять пользовательский домен, приглашать участника или регистрировать webhook, который отправляет каждое событие на внешний сервер. Последнее меня особенно тревожит. Webhook - это постоянный поток данных, который создавший его человек может направить на любой сервер, а ваша команда может неделями этого не замечать.
Поэтому у разрешений три измерения. Где работает ключ: в каком аккаунте или рабочем пространстве? Что он может там делать: читать, записывать, администрировать? И как долго и с какой скоростью? Определение минимальных привилегий от NIST сводится к выдаче лишь доступа, необходимого для задачи, и все три измерения в него входят. Ключ с правами только на чтение, который никогда не истекает и не имеет лимита запросов, всё равно наделён лишними привилегиями во времени.
API-ключи с областью рабочего пространства: один ключ, одно рабочее пространство
В Elido каждый ключ выпускается внутри рабочего пространства и остаётся в нём. Вызовите с ним endpoint другого рабочего пространства - получите 404, тот же ответ, что и для несуществующего рабочего пространства, поэтому ключ даже не может подтвердить существование других.
Это важнее, чем кажется. Агентства и большие команды нередко состоят в пяти или десяти рабочих пространствах. Если бы личный ключ наследовал всё, к чему имеет доступ его создатель, утечка одного токена из проекта одного клиента открыла бы доступ ко всем клиентам. API-ключи с областью рабочего пространства сокращают радиус поражения до одного рабочего пространства.
Ключ также ограничен ролью, выбранной при создании, и никогда не превышает текущую роль своего создателя. Фактический доступ определяется меньшей из двух ролей. Понизьте администратора, создавшего ключ, до редактора - ключ понизится вместе с ним. Пользовательские разрешения этого участника также будут отброшены, когда роль ключа оказывается меньшей, потому что они описывают человека, а не ключ.
Ролевые API-ключи: что может каждая роль
Ключи Elido используют те же четыре роли, что и люди: viewer, editor, admin и owner. Вы выбираете одну при создании ключа; если не выбрать, ключ по умолчанию получит роль editor, покрывающую обычную задачу автоматизации: создание ссылок и чтение аналитики без административного доступа.
Вот как это выглядит на практике для функций, которых обычно касаются интеграции.
| Роль | Ссылки и кампании | Аналитика | Webhook | Домены, участники, ключи |
|---|---|---|---|---|
| viewer | Только чтение | Чтение, запуск экспорта CSV | Список endpoint | Просмотр доменов и участников |
| editor | Создание, изменение, удаление, массовое создание | Чтение, запуск экспорта CSV | Список endpoint | Просмотр доменов и участников |
| admin | Всё, что может editor | Плюс экспорт данных, отчёты по расписанию | Создание, изменение, повторная отправка | Управление доменами, участниками, ключами |
| owner | Всё | Всё | Всё | Всё |
Панели отчётности, которая передаёт число кликов в инструмент BI, нужна роль viewer. Задаче Google Sheets, выпускающей ссылки кампаний, нужна роль editor. В повседневной автоматизации почти ничто не требует admin, а ключ owner я бы счёл тревожным признаком: owner существует для людей, управляющих рабочим пространством, и я не могу представить задачу автоматизации, которой он нужен.
Стоит знать два ограничения. Создавать, просматривать или отзывать ключи вообще могут только admin и owner, поэтому ключ viewer или editor не может выпустить себе более привилегированного собрата. И ключ любой роли не получает доступ к API администратора платформы. Этот интерфейс полностью отклоняет аутентификацию API-ключом кодом 403 и сообщением "admin access requires an interactive session". Ключ предназначен для интеграции одного рабочего пространства, и только это он открывает.
Почему управление webhook требует ключа admin
Именно это часто удивляет людей. Читать список endpoint webhook разрешено любому участнику, включая ключи viewer. Но создание endpoint, изменение его назначения или повторная отправка доставки требуют разрешения workspace.edit, которое есть только у admin и owner.
Причина - описанная выше проблема постоянного потока данных. Редактор может создать тысячу ссылок, и вы это заметите. Если бы редактор мог добавить webhook для всех событий, направленный на свой сервер, он с этого момента молча получал бы каждое событие ссылки. Поэтому изменения webhook оставлены тем же людям, которые могут менять настройки рабочего пространства.
На практике настройте webhook один раз вручную как admin в панели управления. Затем выдайте автоматизации, которая их использует, ключ editor или viewer для вызовов API. Если вы подключаете webhook для событий ссылок к Slack или CRM, принимающей стороне ключ Elido вообще не нужен: ей нужен секрет подписи для проверки полезной нагрузки.
Хотите убедиться до настройки? Создайте бесплатное рабочее пространство, выпустите ключ viewer и ключ editor, затем попробуйте один и тот же вызов записи с каждым. Код 403 для ключа viewer скажет больше любой таблицы.
Как хранятся ключи: pepper, хеш и префикс
Токен выглядит как elido_ и следующие за ним 52 символа base32, сгенерированные из 32 случайных байтов. Полностью вы увидите его ровно один раз, в ответе на вызов создания. После этого с нашей стороны он исчезает навсегда.
Мы храним HMAC-SHA256 токена с серверным pepper в качестве ключа; pepper находится в конфигурации приложения, а не в базе данных. При каждом запросе входящий Bearer-токен, схема которого определена в RFC 6750, хешируется так же, и поиск идёт по хешу. Украденный дамп базы данных содержит список хешей, которые нельзя проверить без pepper, а сервис в продакшене отказывается запускаться, если pepper не задан.
Для ваших записей мы сохраняем первые восемь символов после elido_ как отображаемый префикс. Страница API-ключей показывает этот префикс рядом с именем ключа, ролью, датой создания, сроком действия, временем и IP последнего использования, а также общим числом и числом неудачных запросов. Если ключ появляется где-то в журнале, префикс позволит определить его без необходимости кому-либо видеть полный секрет.
Лимиты запросов, срок действия и ротация API-ключей
У каждого ключа есть собственное ведро токенов, отдельное от лимита рабочего пространства, поэтому один вышедший из-под контроля сценарий не съест бюджет всего остального. Admin может переопределить для одного ключа скорость от 1 до 10 000 запросов в секунду и всплеск от 1 до 20 000 или удалить переопределение, чтобы вернуться к значению по умолчанию. При превышении лимита ключ получит 429 с Retry-After: 1 и X-RateLimit-Scope: api_key, поэтому ваша логика повтора сможет отличить ограничение ключа от ограничения рабочего пространства. О правильном снижении частоты рассказывает руководство по лимитам запросов и идемпотентности.
Срок действия необязателен и задаётся при создании как временная метка RFC 3339. После его окончания ключ просто перестаёт совпадать. Отзыв выполняется одним DELETE. Он также идемпотентен.
Единой кнопки "ротация" нет, и я по ней не скучаю. Ротация состоит из трёх шагов:
- Создайте новый ключ с той же ролью и новым сроком действия.
- Замените им ключ в хранилище учётных данных инструмента и подтвердите успешный вызов.
- Отзовите старый ключ, затем проверьте в списке, что время его последнего использования больше не меняется.
Каждый шаг попадает в журнал аудита рабочего пространства: 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 или всего, что должно пережить уход человека, лучше подходит машинный пользователь: служебный аккаунт со своей ролью, отдельный от ключа любого человека.
Именно поэтому ключ никогда не должен открывать административные endpoint. Когда токен находится в стороннем инструменте, использовать его может любой, у кого есть доступ на редактирование сценариев этого инструмента. Вы доверяете всем на их стороне, а не только на своей.
Токены с отдельными областями действия запланированы, но пока недоступны
Роли намеренно укрупнены, иногда даже слишком. Ключ editor, который только создаёт ссылки, также может их удалять, поскольку удаление входит в роль editor. Решение - токены с отдельными областями действия, например links:write или analytics:read, назначенными непосредственно ключу поверх ролей.
Это есть в нашей дорожной карте, но ещё не выпущено. Сегодня разрешения ключа - это его рабочее пространство и роль, ничего более точного. Если вам уже сейчас нужен более строгий контроль, используйте меньшую роль и короткий срок действия, а также отдельные ключи для каждой задачи, чтобы радиус поражения каждого был мал. Быстрый старт API и справочник API и SDK показывают текущую модель ключей в рабочем коде, а команды, которым также нужен контроль на уровне идентификации, могут прочитать о SCIM и SSO для маркетинговых инструментов.
Прочтите основной материал: чек-лист безопасности сокращателя URL описывает меры защиты вокруг ключа, от сканирования URL до списков разрешённых IP.
Материалы по теме
Частые вопросы
Что такое разрешения API-ключа?
Это набор действий, которые ключу разрешено выполнять через API: какие ресурсы он может читать, какие изменять и в каком аккаунте. В Elido разрешения ключа определяются рабочим пространством, в котором он выпущен, и ролью, выбранной при создании, поэтому один и тот же ключ не может действовать в другом рабочем пространстве или выше этой роли.
Что означает принцип минимальных привилегий для API-ключей?
Каждый ключ получает только минимальный набор разрешений, нужный для его задачи, и ничего сверх этого. Панели, которая лишь читает число кликов, нужен ключ viewer; сценарию, создающему ссылки, нужен ключ editor; ключи admin оставляют для редких задач управления webhook, доменами или участниками. Украденный ключ в таком случае сможет сделать лишь то, что делала эта одна задача.
Чем отличаются области действия API-ключа от ролей?
Область действия - это узкое разрешение, например links:write, назначенное непосредственно токену, а роль - именованный набор разрешений, например editor. Роли проще воспринимать, области действия точнее. Сейчас ключи Elido используют роли рабочего пространства, а токены с отдельными областями действия запланированы поверх них, но пока недоступны.
Как часто нужно ротировать API-ключи?
Обычно рекомендуют делать это каждые 30-90 дней, а также сразу, если видевший ключ сотрудник уходит, ключ появляется в журнале или его трафик выглядит подозрительно. Указав срок действия при создании, вы превратите это расписание в жёсткую остановку, а не в напоминание календаря, которое все игнорируют.
Может ли API-ключ получить доступ к административным endpoint?
В Elido - нет. API администратора платформы принимает только интерактивную авторизованную сессию и отвечает API-ключу кодом 403 независимо от роли создавшего его пользователя. Настройки рабочего пространства, требующие прав admin, по-прежнему доступны, но только ключу, созданному с ролью admin или owner.
Как API-ключи следует хранить на стороне провайдера?
Никогда не в открытом виде. Провайдер должен хранить хеш токена с ключом и затем показывать вам лишь короткий префикс, чтобы одной копии базы данных было недостаточно для вызовов API. Elido хеширует каждый токен с помощью HMAC-SHA256 и серверного pepper и показывает полный токен ровно один раз.
Попробуйте Elido
Вставьте URL - получите короткую ссылку
Без регистрации. Ссылка живёт 30 дней. Зарегистрируйтесь, чтобы оставить её навсегда.
Бесплатно, без регистрации · 2 в день