Единая авторизация Aseller

Аудитория: команды, которые делают отдельный сервис экосистемы (свой репозиторий, свой стек, своя БД) и хотят, чтобы пользователи Aseller входили в него без второй регистрации, а их тулы были доступны в MCP платформы.

Состояние: описывает код api-new в ветках develop, pre-stage, stage на 25.09.2026. Источник истины — сам код: core/services/v1/auth/, core/services/v1/sso/, core/services/v1/mcp/.

Что это такое

api-new — центр учётных записей экосистемы. Он единственный выпускает JWT, ведёт пользователей, права и сессии. Сервис экосистемы не заводит свою авторизацию: он получает идентичность пользователя от платформы и проверяет её у платформы же.

Одна строка в таблице external_tools описывает сервис целиком — она же SSO-клиент, она же MCP-канал, она же (если нужно) плитка микрофронта в интерфейсе. Всё, что ниже, работает от этой строки.

Три канала, и когда какой

Канал	Кто инициирует	Зачем
Браузерный SSO	Пользователь нажал «Войти через Aseller»	Вход в веб-интерфейс сервиса. Даёт пару токенов и профиль с правами
Token introspection	Бэкенд сервиса на каждом запросе	Проверить пользовательский токен, не зная JWT_KEY платформы
MCP-федерация	Платформа, по расписанию и на вызове тула	Тулы сервиса появляются в общем MCP Aseller и вызываются от имени пользователя

Каналы независимы: можно взять только introspection (бэкенд принимает токен, выданный Host UI), можно добавить SSO (свой вход), можно выставить MCP-канал — или всё сразу, как сделал калькулятор.

JWKS пока не работает

/.well-known/jwks.json в api-new — заглушка: токены подписаны HS256 симметричным ключом. Сервис не может и не должен проверять подпись сам — единственный правильный способ проверить токен снаружи это POST /auth/validate. Не просите JWT_KEY и не храните его у себя.

Кто есть кто

• Платформа (api-new) — выпускает токены, держит реестр, проксирует MCP-вызовы.
• Сервис экосистемы — ваш сервис. В реестре у него есть code (slug), сервисный секрет и, опционально, mcpUrl.
• Сервисный кред — пара заголовков X-Service-Client: <code> и X-Service-Secret: <секрет>. Ими сервис доказывает платформе, что он — это он, при серверных вызовах.
• Пользователь — учётная запись Aseller. У неё есть роль, права (permissions), доступные магазины (shopIds) и мастер (для суб-пользователей).

Что нужно получить от администратора платформы

Перед началом интеграции попросите завести строку реестра и сообщить:

1. code вашего сервиса — с него начинаются имена ваших тулов в федерации;
2. сервисный секрет — платформа хранит только его sha256, поэтому секрет генерируете вы и передаёте админу хеш, а не сам секрет;
3. базовый URL платформы для нужного окружения (dev / stage / prod).

Как админ заводит строку без SQL — Реестр external_tools.

Поток данных при входе

Пользователь            Фронт сервиса        Платформа (api-new)        Бэкенд сервиса
    │                        │                       │                        │
    │ «Войти через Aseller»  │                       │                        │
    ├───────────────────────▶│                       │                        │
    │                        │ редирект на страницу платформы                 │
    │                        ├──────────────────────▶│                        │
    │ логинится (если надо)  │                       │                        │
    │◀───────────────────────┼───────────────────────┤                        │
    │                        │ POST /sso/grant (Bearer ACCESS пользователя)    │
    │                        ├──────────────────────▶│                        │
    │                        │◀── redirect c #sso_code во fragment ────────────┤
    │                        │                       │                        │
    │                        │ передаёт sso_code на свой бэкенд                │
    │                        ├────────────────────────────────────────────────▶│
    │                        │                       │  POST /sso/token        │
    │                        │                       │◀───────────────────────┤
    │                        │                       │  (X-Service-Client/Secret)
    │                        │                       ├── accessToken 60с ─────▶│
    │                        │                       │   refreshToken 30д      │
    │                        │                       │   user, permissions,    │
    │                        │                       │   shopIds, epoch        │

Ключевое: sso_code живёт 60 секунд, одноразовый, и бесполезен без сервисного секрета — поэтому его не страшно провести через браузер.

Куда дальше

• Подключение сервиса — SSO-флоу и introspection по шагам, с примерами кода.
• MCP-федерация — как выставить свой MCP-канал и попасть в общий список тулов.
• Реестр external_tools — админ-ручки заведения сервиса и выдачи прав на тулы, без SQL.
• Справочник — переменные окружения, коды ошибок, TTL, матрица ревокации, схема таблиц.