Руководство по настройке OAuth apps OpenConnector

OOMOL OpenConnector использует вашу OAuth app провайдера, когда OAuth2-провайдер требует авторизации пользователя. Создайте app в developer console провайдера, скопируйте в неё точный callback URL своего runtime OpenConnector, затем сохраните client configuration app в OpenConnector.

Используйте это руководство для OAuth2-провайдеров, таких как Gmail, Google Drive, Google Calendar, Slack, HubSpot, GitHub, Microsoft Outlook, Notion, Zoom, Zendesk, Jira, Dropbox и других OAuth-провайдеров из каталога OpenConnector.

Руководство охватывает настройку OAuth app. Для провайдеров с другим типом auth используйте поля credentials, показанные на странице провайдера OpenConnector.

Что потребуется

Запущенный runtime OOMOL OpenConnector.
Доступ к web console OpenConnector.
Admin token, если задан OOMOL_CONNECT_ADMIN_TOKEN.
Разрешение на создание OAuth app в developer или admin console провайдера.
Тестовый аккаунт в workspace, tenant, организации или портале провайдера, который нужно подключить.

Если runtime доступен через публичный домен, tunnel или URL Cloudflare Worker, задайте OOMOL_CONNECT_ORIGIN перед созданием OAuth apps провайдеров. Redirect URI формируется из этого origin.

OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

Шаг 1. Настройте callback URL OpenConnector

Сформируйте callback URL из origin, который пользователи открывают в браузере:

<openconnector-origin>/oauth/callback

Для локального runtime по умолчанию используйте:

http://localhost:3000/oauth/callback

Когда OOMOL_CONNECT_ORIGIN указывает на публичный origin, callback URL использует этот origin:

https://connect.example.com/oauth/callback

Укажите этот точный callback URL в OAuth app провайдера. Не добавляйте завершающую косую черту, если её нет в самом origin OpenConnector.

Шаг 2. Создайте OAuth app провайдера

Откройте developer console провайдера и создайте OAuth app, интеграцию, connected app, public app или регистрацию приложения. Названия различаются, но обязательные поля обычно совпадают.

Поле app провайдера	Что указать
Название app	Узнаваемое название, например `OpenConnector Local` или название внутреннего инструмента.
URL домашней страницы или сайта	Ваш продукт, внутренний инструмент, репозиторий или URL runtime. Используйте значение, понятное пользователям и администраторам.
Redirect URI, callback URL или reply URL	Точный callback URL OpenConnector, например `https://connect.example.com/oauth/callback`.
Scopes или permissions	Scopes, необходимые провайдеру OpenConnector. Скопируйте их со страницы провайдера или из руководства по его actions.
Distribution, install или visibility	Если провайдер разрешает и нужны только ваши аккаунты, оставьте app приватной, тестовой, внутренней или не включённой в каталог.

Многие провайдеры позволяют авторизовать собственный аккаунт, тестовых пользователей, workspace или организацию до публикации на marketplace. Для чувствительных scopes, production-использования, широкого распространения или управляемых workspaces некоторым провайдерам всё равно требуются verification, одобрение администратора или review. Окончательные правила указаны на экране авторизации и в admin console провайдера.

Шаг 3. Скопируйте client configuration

После создания app провайдера скопируйте client values, необходимые OpenConnector.

Значение	Обязательно	Примечания
`clientId`	Да	Обычно называется Client ID, App ID, Application ID или Consumer Key.
`clientSecret`	Обычно	Некоторые провайдеры используют public-client flows и не требуют секрет. Если OpenConnector помечает secret провайдера как optional, оставляйте его пустым только тогда, когда сам провайдер также считает его необязательным.
Дополнительные поля	Иногда	Некоторым провайдерам нужны дополнительные параметры OAuth client, например `tenant`, `subdomain`, `developerToken` или идентификаторы аккаунта. Используйте версию console, которая показывает требуемые поля.

Не помещайте OAuth client secrets в browser code, публичные репозитории, снимки экрана, issue reports или prompts Agent.

Шаг 4. Сохраните OAuth client в OpenConnector

Для обычной настройки используйте web console OpenConnector:

Откройте web console OpenConnector, например http://localhost:3000.
Откройте Providers и выберите нужного провайдера.
Выберите Configure OAuth Client или Edit OAuth Client.
Вставьте Client ID и Client Secret app провайдера.
Выберите Save OAuth Client.

Если провайдеру нужны дополнительные client fields, заполните их в той же форме OAuth client. Например, провайдерам Microsoft требуется значение tenant. Если console не показывает обязательное поле провайдера, обновите OpenConnector до версии с полной формой OAuth client этого провайдера.

После сохранения страница провайдера показывает, что OAuth client настроен, и скрывает client secret.

Шаг 5. Подключите тестовый аккаунт

После сохранения OAuth client оставайтесь на странице провайдера и выберите Connect, чтобы начать авторизацию. Подтвердите экран авторизации провайдера. После перенаправления в OpenConnector убедитесь, что аккаунт отображается как подключённый.

Шаг 6. Проверьте action

На странице провайдера или в списке actions console выполните безопасный read action подключённого провайдера. В сведениях об action указаны input schema, необходимые scopes и identity текущей connection.

Для тестирования write actions используйте демонстрационные данные.

Примечания по провайдерам

При создании OAuth apps пригодятся следующие документы:

Семейство провайдеров	Официальная документация	Распространённое примечание
Google APIs	Using OAuth 2.0 for Web Server Applications	Используйте OAuth client типа web application. Добавьте точный redirect URI OpenConnector в authorized redirect URIs. Для чувствительных или ограниченных scopes перед широким production-использованием может потребоваться verification Google.
Slack	Installing with OAuth	Добавьте точный redirect URI OpenConnector в redirect URLs app. Если Slack не принимает локальный callback URL, используйте публичный origin runtime или HTTPS tunnel.
GitHub	Creating an OAuth app	У GitHub OAuth app один authorization callback URL. Создайте отдельные apps, если для локального окружения, staging и production нужны разные callback URLs.
Microsoft	Register an application with the Microsoft identity platform	Настройте redirect URI платформы Web и создайте client secret. Некоторым провайдерам Microsoft в OpenConnector требуется значение `tenant`, например `common`, `organizations` или tenant ID.
HubSpot	Working with OAuth	Scopes в authorization request должны совпадать с configured scopes app. Production redirect URLs должны использовать HTTPS; для тестирования localhost может использовать HTTP.
Notion	Authorization	Создайте публичное подключение и добавьте redirect URI OpenConnector в конфигурацию OAuth. Перед использованием app за пределами своего workspace проверьте текущие правила Notion для типов apps и capabilities.

Устранение неполадок

Симптом	Что проверить
Провайдер сообщает `redirect_uri_mismatch`, invalid redirect URI или invalid callback URL.	Убедитесь, что app провайдера использует `<openconnector-origin>/oauth/callback`. Scheme, host, port, path и завершающая косая черта должны соответствовать origin, открытому пользователями.
Провайдер отклоняет `http://localhost`.	Используйте провайдера с поддержкой localhost для тестирования или опубликуйте runtime через HTTPS tunnel или публичный домен и задайте `OOMOL_CONNECT_ORIGIN` на этот origin перед перезапуском OpenConnector.
Провайдер сообщает, что app не verified, не approved или не allowed в workspace.	Проверьте distribution app у провайдера, тестовых пользователей, одобрение apps в workspace и требования review чувствительных scopes. Marketplace listing часто не связан с приватным тестированием, но правила различаются.
Авторизация успешна, но action не выполняется из-за missing или insufficient scopes.	Добавьте scopes, необходимые action, в app провайдера, сохраните app и повторно подключите аккаунт, чтобы предоставить новые scopes.
OpenConnector сообщает `oauth_client_config_not_found`.	Сохраните OAuth client на той же странице провайдера, где запускаете Connect.
Позднее не выполняется token refresh.	Убедитесь, что провайдер выдал refresh token. Некоторым провайдерам нужны offline-access parameters или повторный consent. Если refresh token отсутствует, подключите аккаунт повторно.
Во время выполнения используется неверный аккаунт.	Подключитесь повторно из профиля браузера, где выполнен вход в нужный аккаунт, затем выберите соответствующую connection в console перед тестированием actions.

Контрольный список безопасности

Задайте OOMOL_CONNECT_ENCRYPTION_KEY перед сохранением OAuth client secrets или credentials подключённых аккаунтов.
Храните OOMOL_CONNECT_ADMIN_TOKEN в секрете и используйте runtime tokens для вызывающих сторон /v1 и /mcp.
Используйте минимально необходимые scopes, когда это допускают провайдер и набор actions OpenConnector.
Храните отдельные OAuth apps для локального окружения, staging и production, если правила callback провайдера упрощают так аудит.
Удаляйте неиспользуемые apps провайдеров, старые client secrets и устаревшие connections OpenConnector.