Перейти к содержанию
FoxAuth

Блог

Какая схема OAuth нужна вашему приложению?

Сервер, SPA, мобильное приложение, телевизор, cron-задача или ИИ-агент: какая схема OAuth нужна каждому и как руководство FoxAuth её настраивает.

Автор: FoxAuth ·

«Мне просто нужен вход для моего React-приложения». Ответы на такую просьбу обычно приходят в виде списка спецификаций: RFC 6749 для самого OAuth, RFC 7636 для PKCE, сверху OpenID Connect, RFC 8252, если это мобильное приложение, RFC 8628, если это телевизор, RFC 8707, если у вас есть API. Каждый пункт списка верен, но ни один из них не говорит, какая схема нужна вашему приложению.

Я делаю FoxAuth, сервер OAuth 2.1 и OpenID Connect, и от новых пользователей первой слышу именно эту просьбу. Начинать со списка не стоит: нужная вам схема OAuth следует из двух фактов о вашей ситуации, и когда они известны, из всего списка вам нужна одна строка. Ниже два этих вопроса, ответ для каждого их сочетания и страница, которую мы сделали на сайте FoxAuth: она задаёт эти вопросы за вас.

Схема OAuth зависит от того, кто действует, а для человека ещё и от того, где работает код

Первый вопрос: кто действует. Это может быть человек, который входит, программа, за которой нет человека, или ИИ-агент. Второй вопрос зависит от первого. Для человека это вопрос, где работает ваш код, потому что от этого зависят две вещи, вокруг которых построена любая схема: есть ли место, где хранить секрет, и можно ли открыть браузер. Для программы это вопрос, что вы создаёте. Для агента это вопрос, до чего агенту нужно добраться.

В дереве блоки под двумя пронумерованными вопросами показывают частые ответы и схему для каждого.

Выбор схемы OAuth по двум вопросам. Кто действует: человек, программа или ИИ-агент. Для человека, где работает код: серверу подходит Authorization Code с PKCE и секретом; приложению в браузере подходит Authorization Code с PKCE без секрета; приложению на телефоне, компьютере или в терминале подходит PKCE через системный браузер; устройству без клавиатуры подходит схема с кодом устройства; приложению за обратным прокси подходит forward auth на прокси. Для программы, что вы создаёте: программе, которая вызывает API, подходит Client Credentials; API, который нужно защитить, получает токены с привязкой к аудитории; платформе для других разработчиков подходит динамическая регистрация клиентов. Для агента, что ему нужно: подключение к вашему MCP-серверу, напрямую или через ваш прокси, использует документ метаданных клиента и токен только для вашего сервера; работа в Google человека использует обмен токенов; управление FoxAuth использует административный MCP.1 Кто действует?ЧеловекПрограмма без человекаИИ-агент2 Где работает ваш код?2 Что вы создаёте?2 Что нужно агенту?На сервереCode + PKCE, с секретомВ браузереCode + PKCE, без секретаТелефон, компьютер или терминалCode + PKCE в системном браузереУстройство без клавиатурыКод устройства (RFC 8628)За обратным проксиForward auth на проксиПрограмма, вызывающая APIClient CredentialsAPI, который нужно защититьТокены с аудиторией (RFC 8707)Платформа для разработчиковСаморегистрация (RFC 7591)Попасть на ваш MCP-серверАдрес описания, токен для сервераРаботать в Google человекаОбмен токенов (RFC 8693)Управлять самим FoxAuthАдминистративный MCPАгент на компьютере человека,входящий от его имени, считаетсяприложением для ПК или терминалаВсе схемы для человека, кроме кода устройства, это OpenID Connect поверх Authorization Code + PKCE.

То же решение в виде таблицы, со спецификацией, на которой держится каждый ответ:

Кто действует Ответ Схема Спецификация
Человек На сервере Authorization Code + PKCE, с секретом OpenID Connect, RFC 7636
Человек В браузере Authorization Code + PKCE, публичное приложение OpenID Connect, RFC 7636
Человек Телефон, компьютер или терминал Authorization Code + PKCE в системном браузере RFC 8252
Человек Нет клавиатуры Код устройства RFC 8628
Человек За обратным прокси Forward auth, OpenID Connect на прокси OpenID Connect
Программа Вызывает API Client Credentials OAuth 2.1
Программа API, который нужно защитить Токены с привязкой к аудитории RFC 8707
Программа Платформа для разработчиков Динамическая регистрация клиентов RFC 7591, RFC 7592
ИИ-агент Подключиться к вашему MCP-серверу Документ метаданных клиента, токен для вашего сервера Авторизация MCP, RFC 9728
ИИ-агент Работать в Google человека Обмен токенов RFC 8693
ИИ-агент Управлять FoxAuth Административный MCP Авторизация MCP

Большая часть ветки «человек» сводится к одной схеме, Authorization Code с PKCE; от строки к строке меняется только то, где хранится секрет, или то, что его нет вовсе. В ветке агента фраза «агенту нужен OAuth» означает три разные вещи, смотря до чего он пытается дотянуться.

На сервере ваш код хранит секрет

Самый простой и самый безопасный случай: сайт со своим сервером, скажем на Next.js, Django, Rails или Laravel. Сервер может хранить секрет, которого браузер никогда не видит. Человек нажимает «Войти», ваш сервер отправляет браузер на страницу входа, человек входит там, и браузер возвращается на ваш адрес возврата с одноразовым кодом. Затем ваш сервер обменивает этот код на токены напрямую у сервера авторизации, в обход браузера, и подтверждает своим секретом, кто он. Он отправляет ещё и проверку PKCE, о ней рассказано в следующем разделе; FoxAuth по умолчанию требует её, а секрет добавляет доказательство того, какое именно приложение спрашивает.

Ваш сервер не хранит ничьих паролей: пароль видит только сервер авторизации. Храните секрет на сервере, в переменной окружения, и никогда в коде. Обычный http допустим только для localhost.

В браузере и на телефоне секрета нет, и код защищает PKCE

Одностраничному приложению на React, Vue или Angular негде хранить секрет: всё, что есть в коде для браузера, открыто всем. Вместо секрета код защищает PKCE. Приложение придумывает случайную строку (code_verifier), отправляет её хеш (code_challenge) вместе с запросом на вход, а саму строку предъявляет, когда обменивает код на токены. Код, украденный на обратном пути, бесполезен без этой строки, а её знает только эта вкладка браузера. Приложение регистрируется как публичное, без секрета. ID публичного приложения может использовать кто угодно, поэтому вход с вашим приложением связывают адреса возврата, которые вы зарегистрировали. Если ваша библиотека умеет держать токены в памяти, не кладите их в localStorage.

Приложение на телефоне, на компьютере или в терминале использует ту же схему с одним отличием: вход открывается в системном браузере, а не в WebView внутри вашего приложения. Человек вводит пароль в браузере, которому доверяет, и ваше приложение пароля не видит. На компьютере и в терминале код возвращается на http://127.0.0.1, на тот порт, который ваше приложение слушает в этот момент (RFC 8252, раздел 7.3), поэтому один зарегистрированный адрес возврата подходит для любого порта. Приложение на телефоне обычно получает код через HTTPS-ссылку, которую оно закрепило за собой, или через собственную схему URL, например com.example.app:/callback (разделы 7.1 и 7.2).

ИИ-агент, который работает на компьютере самого человека и входит от его имени, тоже относится сюда. Для OAuth это приложение на компьютере или в терминале, и настраивается оно так же.

Без клавиатуры человек входит на своём телефоне

Телевизор, приставка или киоск не могут всерьёз просить ввести пароль. Схема с кодом устройства (RFC 8628) переносит вход на второй экран. Устройство просит у сервера авторизации короткий код и показывает его вместе с адресом. Человек открывает адрес на телефоне, вводит код и входит как обычно. Тем временем устройство каждые несколько секунд спрашивает, подтверждён ли код, и получает свои токены, как только код подтвердят. Короткий код быстро истекает; хранит устройство токены, которые получает в конце. Опрашивайте не чаще, чем указано в ответе, и добавляйте пять секунд к интервалу каждый раз, когда сервер отвечает slow_down.

Приложение без собственного входа ставится за ваш прокси

Интерфейс Prometheus или Jaeger, внутренняя панель, инструмент, который кто-то написал для команды: у многих приложений нет входа, и добавлять его не ваша задача. Вместо этого поставьте приложение за Caddy, Traefik или nginx. При каждом запросе прокси спрашивает у сервера авторизации, можно ли пропустить этот запрос. Человека, который ещё не вошёл, отправляют на страницу входа и обратно, а когда он вошёл, прокси передаёт запрос дальше и сообщает, кто это, в заголовках X-Auth-*. Приложение не меняется.

Такая схема безопасна, только если до приложения можно добраться исключительно через прокси: запрос, который дошёл до него другим путём, минует проверку. Пошаговое руководство: Вход перед веб-приложением.

Без человека программа входит сама за себя

Фоновой задаче, задаче cron или другому сервису, который вызывает ваш API, некому входить. Для этого случая есть схема Client Credentials: программа предъявляет собственные ID и секрет и получает токен доступа на своё имя. Кешируйте токен, пока он не истечёт, и не запрашивайте новый при каждом вызове. Если секрет утёк, выпустите новый.

Платформа для сторонних разработчиков встречается реже: они сами регистрируют свои приложения одним запросом, через динамическую регистрацию клиентов (RFC 7591), а изменяют или удаляют их токеном, который получили в ответ. Это настройка всего сервера, поэтому в FoxAuth для неё нужен ваш собственный сервер, а не проект в Cloud.

Ваш API отклоняет токен, выпущенный для другого API

Вторая половина случая с программой касается вызываемого API. Токен с верной подписью не обязательно предназначен вам. Если ваш API принимает любой токен, подписанный сервером авторизации, то токен, выданный для какого-то другого API, откроет и ваш. Это исправляют индикаторы ресурсов (RFC 8707): клиент называет API, когда просит токен, сервер записывает этот API в claim aud токена, а ваш API отклоняет токен, в aud которого указан кто-то другой, даже если подпись в порядке.

«ИИ-агенту нужен OAuth» означает одно из трёх

Когда агент подключается к вашему MCP-серверу, ваш сервер ничем не отличается от обычного сервера ресурсов OAuth, и важна та же проверка аудитории, что и для любого API. Подробно о том, что бывает, если её пропустить, я писал в статье MCP-сервер должен проверять, кому выдан токен. Новое здесь то, как агент представляется. Хост агента, который поддерживает документы метаданных клиента (client ID metadata documents), как и предпочитает текущая спецификация авторизации MCP, заранее не регистрируется. Он сообщает адрес документа, который его описывает, человек входит и видит, какой агент запрашивает доступ, и агент получает токен, который работает только на вашем сервере. Хосту, который не может опубликовать такой документ, нужно приложение, заранее зарегистрированное для него в консоли, или динамическая регистрация; на вашем собственном сервере её включает суперадминистратор. Шаги описаны в руководстве Защита MCP-сервера с помощью OAuth.

Если вы не хотите писать ничего из этого в MCP-сервере, поставьте его за свой прокси: при каждом запросе прокси просит сервер авторизации проверить токен вместе с правами (scope), которые нужны вызываемому инструменту, и самому MCP-серверу для этого не нужен никакой код. В руководстве это отдельный ответ, а в документации есть Защита MCP-сервера на вашем прокси.

Когда агенту нужно действовать в Google, GitHub или Slack человека, задача другая: агент не должен держать у себя ключи человека. Человек один раз подключает свой аккаунт и даёт согласие; сервер авторизации хранит токен провайдера в зашифрованном виде; а когда агенту нужен этот токен, он обменивает свой собственный токен (RFC 8693) на токен Google этого человека, которым стоит воспользоваться для одного запроса и не хранить. Человек видит свои подключённые аккаунты и может отключить любой из них, и агент сразу теряет доступ.

Третий случай: агент управляет самим сервером авторизации. Например, вы пишете своему агенту для программирования «создай приложение для моего нового сервиса». В FoxAuth для этого есть административный MCP. Агент подключается после того, как вы вошли, действует ровно с вашими правами, проходит те же проверки и лимиты тарифа, что и консоль, а каждое его изменение записывается в журнал аудита с вашим именем и именем агента. Самые опасные действия, например удаление проекта, остаются в консоли. Агент подключается через собственный MCP-клиент FoxAuth или как приложение, которое разрешил суперадминистратор; приложение, зарегистрировавшее себя само, не подключится никогда. В FoxAuth Cloud административный MCP включён, а справочник инструментов MCP перечисляет, что он умеет.

Страница руководства задаёт два вопроса за вас

Объяснять это дерево отдельно в каждой переписке с поддержкой не масштабируется, поэтому мы вынесли его на страницу Что вам нужно? на сайте FoxAuth. Она задаёт те же два вопроса. Для каждого ответа она показывает проблему, которую убирает схема, и что с ней меняется, саму схему шаг за шагом, что увидит человек (страницу входа, экран согласия с именем агента, короткий код на телевизоре) и короткий список «Полезно знать» с ошибками, которых стоит избегать, например WebView и localStorage, о которых шла речь выше.

Большинство ответов заканчиваются двумя способами настройки. Первый: кнопка, которая открывает ваш проект в FoxAuth Cloud с уже выбранной ситуацией, так что всё, что вы создаёте, сразу получает правильные настройки. Второй: промпт, который нужно вставить в Claude, Cursor или другого агента для программирования. Он называет схему и проверки, которые должен делать ваш код, даёт адреса возврата, если они есть, и там, где для шага есть инструмент административного MCP, говорит агенту, какой из них вызвать, так что агент может сделать и часть работы в консоли.

Страница также говорит, где может работать каждый ответ. «Готово в Cloud» значит, что бесплатный проект в Cloud позволяет настроить это уже сейчас. «Свой сервер» значит, что нужна настройка или действие, доступные только суперадминистратору, а тенант в Cloud суперадминистратором никогда не бывает; саморегистрация разработчиков как раз из таких. Под двумя вопросами есть список задач, которые обычно идут следующими, например добавить «Войти через Google», запрашивать второй фактор или выяснить, почему кто-то не может войти, и отдельная вкладка на случай, когда ваш клиент является компанией и её ИТ-отдел начинает просить корпоративный вход и SCIM.

Начните с бесплатного тарифа Cloud, а в продакшене работайте на своём сервере

Текущий релиз FoxAuth 2.0.0. В нём есть все схемы из дерева выше, и все, кроме динамической регистрации, работают на бесплатном тарифе Cloud. Он подойдёт, если вам нужны стандартные схемы, с которыми потом можно перейти на другой сервер, если вы ставите за вход MCP-сервер или внутреннее приложение или если вы предпочитаете, чтобы настройку сделал ваш агент для программирования. Запускать его можно двумя способами.

FoxAuth Cloud бесплатен на время беты и не просит банковскую карту. В бесплатном тарифе нет лимита на активных пользователей в месяц, приложения и API, и в него входят до десяти проектов на администратора, каждый по выбранному вами адресу, вход через Google, Apple, GitHub, Microsoft или любого провайдера OpenID, машинные токены, вход на устройствах, DPoP и PAR и административный MCP. Собственный домен настраивается по запросу. Команды, которые придут во время беты, пользуются облаком бесплатно ещё год после запуска платных тарифов. SLA у него пока нет, так что с него стоит начинать, но полагаться на него в продакшене рано.

Или вы запускаете тот же сервер сами. Исходный код доступен по лицензии FSL-1.1-ALv2, и это не лицензия открытого исходного кода: код можно читать, изменять, разворачивать у себя и распространять, а также строить на нём бизнес, но нельзя предоставлять его другим в коммерческом продукте или сервисе, который конкурирует с FoxAuth, а каждая версия переходит под Apache 2.0 через два года после выхода.

Пока у Cloud нет SLA, продакшен работает на вашем собственном сервере. Компания, которой нужен собственный экземпляр, у нас или на своей инфраструктуре, с SLA на время реакции по дефектам, может запросить приглашение в Enterprise на той же странице цен.

Чтобы получить свою схему и настройку для проверки, ответьте на два вопроса в руководстве.