Документация

FoxAuth построен на OAuth-server.ts — сервере авторизации OAuth 2.1 и OpenID Connect с доступным исходным кодом (source-available), который вы разворачиваете у себя. Эта документация охватывает три задачи: запустить сервер, подключить к нему приложение и сопровождать его, когда от него начинают зависеть реальные пользователи. Выберите ту, которой заняты сейчас.

Запуск сервера

Начните с раздела Запуск с Docker Compose. Одна команда запускает MongoDB, подготавливает схему и поднимает сервер авторизации — пожалуй, это самый быстрый способ увидеть работающий экземпляр. Если вы предпочитаете работать с исходным кодом, раздел Запуск из исходного кода описывает, как клонировать репозиторий и запустить сервер на Bun.

В обоих случаях следующий шаг — Создание первого администратора: в новой базе данных нет ни одной учётной записи, и первая создаётся на одноразовом экране настройки. Первым делом включите там второй фактор.

Подключение приложения

Приложение взаимодействует с сервером как OAuth-клиент, и клиент должен существовать до того, как сможет запросить токен. Раздел Регистрация первого клиента разбирает то, на чём чаще всего спотыкаются: разницу между публичным и конфиденциальным клиентом, почему redirect URI сравниваются точно и никогда по шаблону и из какого бакета пользователей клиент впускает людей.

Затем Получение первого токена проводит через Authorization Code flow с PKCE от начала до конца с помощью curl: от code challenge до декодированного ID-токена и вызова UserInfo. PKCE обязателен для каждого клиента, а не только для публичных. Так требует OAuth 2.1, и, по нашему опыту, именно это чаще всего удивляет тех, кто переходит с сервера OAuth 2.0.

Если подключаемое приложение — MCP-сервер, то это не OAuth-клиент, а защищённый ресурс, и схема отличается настолько, что ей посвящена отдельная страница: Защита MCP-сервера с помощью OAuth. Там MCP-сервер объявляется на этом сервере, публикуются две вещи, которые обязан публиковать любой MCP-сервер, проверяется токен и показаны как отказ, так и успешный запрос.

Работа в продакшене

Раздел Развёртывание охватывает платформы, которыми действительно пользуются: Fly.io, Kubernetes, Docker Compose на одном хосте. База данных — одна из двух, MongoDB или PostgreSQL, и выбор между ними определяет заданная вами строка подключения. Что бы вы ни выбрали, важен раздел За обратным прокси. URL издателя (issuer) должен быть адресом https:// и совпадать с тем, что настроено в клиентах. Прокси, который переписывает заголовки, когда его об этом не просили, — обычная причина того, что токены проходят проверку локально и не проходят в продакшене.

Прежде чем переходить на другую версию, прочитайте раздел Обновление. Сервер находится на релизе 0.x, а значит, HTTP-интерфейс и admin API ещё могут меняться между минорными версиями; что изменилось, сказано в changelog. После обновления нужно заново запустить скрипт настройки, чтобы появились новые коллекции и индексы, а затем bun run db:migrate — для всего, что релиз должен перестроить.

Работа с реальными пользователями

Когда через сервер начинают входить люди, основная работа переходит в консоль. Подключение внешнего провайдера идентификации позволяет пользователям бакета входить через Google, Microsoft, Apple, GitHub или любой провайдер OpenID и определяет, какие учётные записи такой вход может создавать или связывать. Когда это настроено, Провижининг пользователей из Entra ID или Okta передаёт пользователей и группы бакета под управление каталога по SCIM, а Выход через внешних провайдеров позволяет выходу там завершать сессии здесь.

Группы и claim groups описывает группы администраторов, которым принадлежат проекты и бакеты, перенос работы между ними и группы бакета, которые relying party читает вместо ролей. Прекращение доступа пользователя сравнивает деактивацию, блокировку, выход на всех устройствах и удаление и называет единственный токен, который ни один из этих способов не может отозвать. Ротация ключей подписи показывает, как одним действием и без перезапуска ротировать ключи экземпляра и каждого бакета и как сразу отозвать скомпрометированный ключ.

Стоит ли ему доверять

Сервер авторизации — это входная дверь ко всему, что за ним стоит. Прежде чем ставить его перед реальными пользователями, вы вправе спросить, от чего он защищает и откуда это известно. Модель угроз отвечает на первый вопрос: активы, атакующие и для каждой угрозы — механизм защиты в коде и тест, который его гарантирует, а также ограничения, актуальные на сегодня. Гарантии безопасности отвечают на второй: сканирование, которое запускается при каждом push и каждую неделю, где публикуется каждый результат и что ещё не сделано. Как сообщить об уязвимости, описано в политике безопасности.

Справочник

Раздел Reference генерируется из исходного кода самого сервера при каждой сборке, поэтому описывает тот релиз, из которого собран сайт; ничего в нём не поддерживается вручную:

• Настройки — каждый флаг и параметр уровня сервера: что он делает и требует ли его изменение перезапуска.
• Эндпоинты — каждый маршрут, который обслуживает сервер, какой флаг им управляет, а также его класс CORS и класс ограничения частоты запросов.
• Admin API — API управления, на котором работает консоль.
• MCP-инструменты — операции, которые может выполнять ИИ-агент: намеренно составленный allow-list, более узкий, чем весь административный интерфейс.
• Точки расширения (addon seams) — именованные функции, которые вы заменяете своими вместо того, чтобы делать форк.
• Переменные окружения — что должно быть задано, чтобы сервер запустился.

Чем этот сервер не является

Он поддерживает OAuth 2.1 и OpenID Connect — и ничего больше. Поддержки SAML нет и не планируется. Гранты Implicit и Resource Owner Password Credentials не реализованы, потому что OAuth 2.1 их убирает. Если приложение зависит от любого из них, его придётся изменить, прежде чем оно сможет работать с этим сервером.

Если вы ещё решаете, стоит ли вообще его запускать, сравнения ставят его рядом с серверами, с которыми его обычно сопоставляют команды, и указывают дату проверки каждого утверждения.