Веб-сервисы десятилетиями строились вокруг одной простой идеи: за компьютером всегда находится человек.
Пользователь открывает сайт, нажимает кнопку, заполняет форму регистрации, подтверждает электронную почту, получает API-ключ и начинает работать с сервисом.
Вся современная система аутентификации выросла именно из этой модели.
Но с появлением AI-агентов ситуация начала быстро меняться.
Сегодня агенты уже пишут код, создают pull request'ы, сортируют обращения пользователей, обновляют записи в корпоративных системах и взаимодействуют с различными сервисами без постоянного участия человека.
Возникает проблема: большинство современных продуктов по-прежнему не умеют регистрировать AI-агентов как самостоятельных участников системы.
На практике разработчики обычно используют обходные пути — выдают агенту API-ключ или токен сессии пользователя. Однако такой подход создает множество ограничений:
- права доступа оказываются слишком широкими;
- сложно понять, какой именно агент выполнил действие;
- невозможно отозвать доступ для конкретной сессии;
- аудит действий становится значительно сложнее.
Компания WorkOS предлагает альтернативу — открытый протокол auth.md, предназначенный специально для регистрации AI-агентов.
Что такое auth.md
По своей сути auth.md представляет собой обычный Markdown-файл, который публикуется в заранее известном месте.
Например:
https://service.com/auth.md
В этом файле сервис описывает правила регистрации агентов:
- какие способы регистрации поддерживаются;
- какие уровни доступа существуют;
- каким образом выдаются учетные данные;
- как осуществляется аудит;
- каким образом можно отозвать выданные права.
Главная особенность заключается в том, что один и тот же файл одновременно работает как документация для людей и как источник информации для самих агентов.
Вместо того чтобы заставлять пользователя вручную проходить регистрацию, агент может самостоятельно получить файл, прочитать его структуру, выбрать подходящий способ регистрации и выполнить весь процесс автоматически.
Фактически auth.md превращается в своеобразную инструкцию для AI-агентов по подключению к сервису.
Как агент находит нужные точки подключения
В протоколе предусмотрен механизм автоматического обнаружения.
Работа происходит в два этапа.
Первым источником информации выступает специальный ресурс:
/.well-known/oauth-protected-resource
Он содержит метаданные защищенного ресурса и сообщает агенту, где находится сервер авторизации.
После этого агент обращается к следующему адресу:
/.well-known/oauth-authorization-server
Именно здесь находится блок:
agent_auth
В нем публикуются все необходимые параметры:
- register_uri;
- claim_uri;
- revocation_uri;
- identity_types_supported.
Дополнительно предусмотрен еще один важный механизм.
Если агент обращается к API без авторизации и получает ответ:
401 Unauthorized
сервер должен вернуть заголовок:
WWW-Authenticate: Bearer resource_metadata="https://api.service.com/.well-known/oauth-protected-resource"
Благодаря этому агент может автоматически начать процесс обнаружения даже без предварительного изучения документации.
Два способа регистрации агентов
В основе auth.md лежат два основных сценария регистрации.
Сервис может поддерживать любой из них или сразу оба.
Первый сценарий: Agent Verified Flow
Этот вариант предполагает участие поставщика AI-агента.
Например:
- OpenAI;
- Anthropic;
- Cursor;
- или другой доверенный провайдер.
В момент регистрации поставщик подтверждает личность пользователя через специальный механизм ID-JAG.
Процесс выглядит следующим образом.
Сначала агент получает согласие пользователя.
Затем запрашивает у своего провайдера специальный идентификационный токен ID-JAG.
После этого токен отправляется на конечную точку сервиса:
/agent/auth
Далее приложение выполняет проверку:
- анализирует заголовок токена;
- определяет алгоритм подписи;
- получает открытые ключи провайдера;
- проверяет подпись;
- валидирует параметры безопасности.
Проверяются такие поля как:
aud
exp
iat
jti
client_id
Если все проверки пройдены успешно, сервис немедленно выдает агенту учетные данные.
При этом человеку не нужно:
- вводить коды;
- переходить по ссылкам;
- подтверждать электронную почту;
- выполнять какие-либо дополнительные действия.
Весь процесс происходит автоматически.
Как работает отзыв доступа
Каждая делегация доступа привязывается к комбинации:
(iss, sub, aud)
Если пользователь отзывает разрешение, провайдер может отправить специальный logout-токен на адрес:
revocation_uri
После этого доступ агента немедленно аннулируется.
Авторы отдельно подчеркивают важное ограничение.
Для учетных данных, выданных через ID-JAG, не используются refresh-токены.
Когда срок действия заканчивается, агент обязан получить новый ID-JAG и пройти процедуру повторно.
Второй сценарий: User Claimed Flow
Этот вариант рассчитан на сервисы, которые не хотят зависеть от поставщиков AI-агентов.
В основе схемы лежит одноразовый код подтверждения (OTP).
Здесь агент начинает регистрацию самостоятельно, а затем пользователь подтверждает её через электронную почту.
Для этого используются две конечные точки:
POST /agent/auth/claim
POST /agent/auth/claim/complete
Первая инициирует отправку письма с кодом.
Вторая завершает процесс после ввода кода.
Anonymous Start
В первом варианте агент может зарегистрироваться без указания личности пользователя.
После регистрации он сразу получает ограниченные права доступа.
Работа может начаться немедленно.
Позже пользователь проходит процедуру подтверждения через OTP-код, после чего права автоматически расширяются.
При этом выданный ранее ключ не заменяется.
Меняется только набор доступных разрешений.
Email Required
Во втором варианте агент обязан сразу указать электронную почту пользователя.
Сервис немедленно отправляет письмо с кодом подтверждения.
До завершения проверки никакие учетные данные не выдаются.
Такой подход подходит для сервисов, где даже минимальный доступ до подтверждения считается недопустимым.
После успешного завершения процедуры создается полноценный набор учетных данных.
Как система связывает агента с пользователем
После завершения регистрации сервис должен определить, к какой учетной записи относится агент.
В документации рекомендуется использовать следующий порядок проверки.
1. Поиск существующей делегации
Сначала проверяется наличие уже известной пары:
(iss, sub)
Если такая запись существует, она считается наиболее надежным идентификатором.
2. Поиск по подтвержденному адресу электронной почты
Если делегация не найдена, выполняется поиск существующего пользователя по электронной почте.
3. Автоматическое создание пользователя
Если совпадений нет, система может создать нового пользователя автоматически или отклонить регистрацию согласно внутренним правилам сервиса.
Какие события рекомендуется сохранять в журнале
Для полноценного аудита WorkOS предлагает фиксировать стандартный набор событий.
Среди них:
registration.created
claim.requested
otp.generated
claim.confirmed
registration.expired
registration.revoked
Для сценариев с ID-JAG дополнительно рекомендуется сохранять:
iss
sub
agent_platform
Это позволяет связывать журналы приложения с журналами поставщика AI-агента и значительно упрощает расследование инцидентов безопасности.
Минимальный список требований для внедрения auth.md
Авторы протокола приводят базовый список действий для интеграции.
Необходимо:
- Опубликовать файл auth.md.
- Создать ресурс:
/.well-known/oauth-protected-resource
- Возвращать заголовок WWW-Authenticate для ответов 401.
- Реализовать конечную точку:
/agent/auth
- Для OTP-сценариев реализовать:
/agent/auth/claim
/agent/auth/claim/complete
- Для сценариев Agent Verified настроить список доверенных провайдеров и проверку ID-JAG.
Почему это важно
Главная идея auth.md заключается не в создании очередной системы авторизации.
WorkOS пытается решить фундаментальную проблему современной индустрии AI-агентов.
Большинство существующих механизмов доступа создавались для людей, а не для автономных систем.
Когда агенту выдают обычный API-ключ, становится сложно контролировать его полномочия, отслеживать действия и отзывать разрешения.
auth.md предлагает стандартизированный способ регистрации агентов на основе существующих OAuth-механизмов, не привязываясь к инфраструктуре WorkOS и сохраняя совместимость с уже существующими стандартами безопасности.
Если экосистема поддержит эту инициативу, разработчики получат единый способ безопасной регистрации AI-агентов вместо множества несовместимых решений, которые используются сегодня.