Аутентификация MCP в Didit: вход через OAuth

Didit MCP аутентифицируется с помощью функции «Войти через Didit» (OAuth 2.1). Он выступает в роли пользователя Didit с разрешениями вашей роли в консоли: режима API-ключа не существует.

Вход через Didit

Размещённый сервер (https://mcp.didit.me/mcp) является ресурсным сервером OAuth 2.1. Didit Business Console (business.didit.me) выступает в роли сервера авторизации: он показывает экран согласия и выдаёт токены. Ваш MCP-клиент выполняет стандартный сценарий автоматически:

Обнаружение

Клиент отправляет запрос на /mcp без токена и получает 401 с заголовком WWW-Authenticate: Bearer, в котором resource_metadata указывает на метаданные защищённого ресурса (RFC 9728):

https://mcp.didit.me/.well-known/oauth-protected-resource/mcp

Этот документ описывает ресурс (https://mcp.didit.me/mcp), сервер авторизации (https://business.didit.me) и поддерживаемые области доступа. Тот же документ также доступен в корне исходного домена по адресу https://mcp.didit.me/.well-known/oauth-protected-resource для клиентов, которые сначала проверяют этот путь.

Регистрация (динамическая регистрация клиента)

Клиент читает метаданные сервера авторизации по адресу https://business.didit.me/.well-known/oauth-authorization-server и, если у него ещё нет client id, регистрирует себя на registration_endpoint (RFC 7591). С вашей стороны ничего заранее настраивать не нужно: локальные клиенты с loopback- или нативным URL обратного вызова (Claude Code, Cursor, MCP Inspector) и облачные клиенты с проверенным URL обратного вызова (Claude) регистрируются именно так. Удалённый URL обратного вызова, который Didit не проверял, отклоняется с ошибкой invalid_redirect_uri. Такой клиент сначала должен быть зарегистрирован оператором.

Авторизация (PKCE)

Клиент открывает https://business.didit.me/authorize с PKCE-челленджем S256. Вы входите в систему (или регистрируетесь) и видите, какие разрешения запрашиваются. Клиенты являются публичными: токен-эндпоинт не принимает client secret (token_endpoint_auth_methods_supported равен none), поэтому связь кода с клиентом обеспечивает именно PKCE.

Согласие

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

Вызов инструментов

Клиент отправляет токен доступа с каждым запросом. MCP проверяет токен через интроспекцию по RFC 7662 в сервисе аутентификации Didit (токены непрозрачные, а не JWT), читает разрешения вашей организации из ответа интроспекции и действует от вашего имени на время этого запроса.

Области доступа

Метаданные ресурса объявляют три области доступа. На экране согласия простым языком показано, какие из них запрашивает клиент:

Область доступа	Предоставляет
`didit:management`	Управление вашим рабочим пространством: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` и `analytics`.
`didit:verification`	Запуск и проверка верификаций: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` и `analytics`.
`didit:staff`	Зарезервировано для учётных записей сотрудников Didit. Для обычной учётной записи не открывает ничего, а в сборке с открытым исходным кодом не определено ни одного инструмента только для сотрудников.

Обе области доступа включают analytics. Управление lists требует didit:management, а доступ к blocklist требует didit:verification. В справочнике инструментов указано, к какой области доступа относится каждый инструмент. Одобренные вами области доступа передаются в токене и проверяются на стороне сервера. Поэтому приложение, подключённое только с didit:verification, получает отказ при обращении к интерфейсу управления, даже если ваша роль это позволяет. Сервер авторизации также знает области OpenID (openid profile email): подключение, которое запрашивает только их, может узнать, кто вы, и больше ничего. Эффективные разрешения приложения представляют собой пересечение одобренных областей доступа и вашей роли в консоли, но никогда не превышают более узкое из двух. Чтобы создать сессию верификации с помощью didit_session_create, нужны область доступа didit:verification и роль с create:sessions или write:sessions. Роль Developer включает create:sessions. Одобрение только didit:management не позволяет создавать сессии, даже если ваша роль содержит нужное разрешение.

Роли и разрешения

Токен представляет вас, поэтому агент может работать во всех организациях, в которых вы состоите, в рамках одного подключения. Инструменты, работающие между приложениями (didit_session_search, didit_analytics, didit_context_get и остальные инструменты *_search), автоматически агрегируют данные по всем этим организациям. Ваша роль всегда проверяется бэкендом Didit отдельно для каждой организации. Каждый инструмент соответствует одному идентификатору разрешения бэкенда (например, write:sessions для didit_session_update_status и delete:sessions для didit_session_delete). В справочнике инструментов это указано для каждого инструмента. Сервер также проверяет это разрешение до отправки запроса, используя разрешения, которые ответ интроспекции содержит для вашей организации:

В режиме enforce инструмент, который ваша роль не может выполнить, не включается в tools/list. Если всё же вызвать его, возвращается ошибка missing_scope, которая называет разрешение: "Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."
В режиме shadow (режим сервера по умолчанию) все инструменты показываются в списке, а вызов передаётся бэкенду. Бэкенд отвечает 403, если роль не имеет разрешения. Решение лишь записывается в журнал аудита сервера.

В любом случае MCP никогда не предоставляет больше, чем уже разрешает ваша роль в консоли. READER может просматривать и читать, а OWNER или ADMIN могут записывать и удалять.

Время жизни токена

Одобренное приложение получает собственную сессию, отдельную от браузерной сессии, из которой вы его одобрили. Токены доступа имеют короткий срок действия. Клиент автоматически обновляет их с помощью токена обновления (grant_types_supported включает refresh_token). Обновление сохраняет области доступа приложения и остаётся привязанным к этому приложению. Если обновление не удалось (например, после того как вы отключили приложение), клиент при следующем вызове заново запускает Вход через Didit. Выход из консоли не завершает сессии в подключённых приложениях, а отключение приложения никогда не выполняет выход из системы нигде.

Отключение приложения

Из консоли

В разделе Settings → Authentication → Connected apps показано каждое приложение, которое вы одобрили, с его зарегистрированным названием и выданными разрешениями. Отключить немедленно прекращает доступ этого приложения: и его токен доступа, и его refresh-токен перестают работать, а остальное не затрагивается.

Из приложения (RFC 7009)

Клиент может отозвать собственный доступ, отправив токен на revocation_endpoint сервера авторизации, который указан в метаданных по адресу https://business.didit.me/.well-known/oauth-authorization-server. Как требует RFC 7009, успешный вызов возвращает 200 независимо от того, был ли токен ещё действительным, поэтому ответ никогда не сообщает, был ли токен действительным. Ответ 503 означает, что отозвать токен не удалось: считайте токен всё ещё действительным и повторите запрос.

curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'

Почему без API-ключа? Каждый MCP-инструмент обращается к эндпоинтам консоли, доступным в контексте пользователя (/organization/{org}/application/{app}/…), которые авторизуют Bearer-токен с привилегиями, зависящими от роли, и отклоняют x-api-key. API-ключ приложения предназначен для прямых вызовов REST API из вашего собственного бэкенда (например, для создания сессий), а не для этого MCP. didit_org_list_api_keys показывает метаданные ключей со скрытыми значениями; инструмент, который раскрывает сам ключ, на размещённом коннекторе скрыт.

Подключение с каждого клиента

Все клиенты используют один и тот же процесс; различается только способ передачи им URL.

Claude
Claude Code
Cursor
Универсальный клиент

Используйте глубокую ссылку, которую Business Console показывает на странице интеграции. Она открывает claude.ai с предзаполненным диалогом Add custom connector:

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp

Подтвердите, затем выполните Вход через Didit. Claude Desktop использует тот же URL в Settings → Connectors → Add custom connector. Подробности в разделе Connect Claude.

claude mcp add --transport http didit https://mcp.didit.me/mcp

Затем выполните /mcp внутри Claude Code, чтобы запустить вход через браузер.

~/.cursor/mcp.json:

{ "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }

Cursor регистрируется сам и открывает браузер при первом использовании.

Направьте любой клиент Streamable HTTP с поддержкой OAuth 2.1 на https://mcp.didit.me/mcp. Он должен:

Выполнить POST /mcp, получить 401 и прочитать resource_metadata из WWW-Authenticate.
Запросить https://mcp.didit.me/.well-known/oauth-protected-resource/mcp, затем метаданные сервера авторизации по адресу https://business.didit.me/.well-known/oauth-authorization-server.
Зарегистрироваться на registration_endpoint, если у него нет идентификатора клиента.
Выполнить поток авторизации по коду с PKCE (S256) на authorization_endpoint, затем обменять код на токен в token_endpoint.
Отправлять Authorization: Bearer <access_token> с каждым запросом POST /mcp.

Клиенты без поддержки OAuth могут работать через npx -y mcp-remote@latest https://mcp.didit.me/mcp, который выполняет за них шаги 1–5.

Ошибки аутентификации

HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"

Ответ 401 от /mcp означает, что токен отсутствует, истёк или был отозван: клиенту следует обновить токен или заново выполнить Вход через Didit. Ответ 403 или ошибка missing_scope для конкретного инструмента обычно означает одно из двух: ваша роль не имеет нужного разрешения (например, READER пытается выполнить запись), либо подключение было одобрено без области действия, которая нужна этому инструменту. Это не означает, что всё подключение неисправно. Повторное подключение с одобрением обеих областей действия исправляет второй случай; первый требует смены роли. Если не работает ни один инструмент, проверьте Settings → Authentication → Connected apps в консоли: приложение, которое там было отключено, нужно одобрить заново.

Справочник инструментов

Что делает каждый инструмент, его scope и разрешение роли.

Расширенные возможности

Роли, поведение между приложениями и самостоятельное развёртывание.

Руководства