Любой сервис с OAuth — чек-лист

Общая часть, которая повторяется у Google, Microsoft, Slack, Notion и остальных. Собрано по реальным поломкам, а не по документации поставщиков.

Перед началом

1. Проверьте, нет ли пути проще. У многих сервисов есть официальный CLI (gh, az, aws) или готовый MCP-сервер. OAuth-приложение заводить дольше всего.
2. Проверьте, нет ли уже настроенного источника в этом или соседнем рабочем месте — форму config.json проще скопировать, чем собирать заново.
3. Сверьте адреса API веб-поиском. Документация поставщиков меняется, а адреса в примерах устаревают.

Пять мест, где ломается чаще всего

1. Redirect URI

Адрес возврата должен совпадать посимвольно: протокол, домен, порт, путь. http вместо https, лишний слэш в конце, www — всё это даёт redirect_uri_mismatch.

Узнайте, какой адрес отправляет ваша установка, и впишите именно его. При работе через веб-интерфейс это адрес вашего сервера, а не localhost.

2. Чужое приложение

Не переиспользуйте OAuth-приложение, заведённое под другой инструмент. В нём прописан чужой адрес возврата и часто чужой набор прав. Новое приложение создаётся за пару минут и экономит час разбирательств.

3. Права выдаются один раз

Права привязаны к выданному токену. Если сначала подключили один сервис, а потом понадобился второй — токен не расширится сам. Нужно пройти согласие заново с новым набором прав.

Типичная картина: «Search Console работает, а почта нет» — потому что токен выдавался под Search Console.

4. Приложение не опубликовано

Пока приложение в статусе тестового, войти могут только аккаунты из списка тестовых пользователей. Забыли добавить свою почту — получите отказ на экране согласия, причём формулировка редко объясняет причину.

5. Нет токена обновления

Без него доступ живёт около часа и не восстанавливается. Выдаётся только при явном запросе офлайн-доступа и показе экрана согласия. Если при повторной авторизации согласие не показывалось — токена обновления, скорее всего, нет.

Как проверить: подождать час и повторить запрос. Отвалилось — проходить согласие заново.

Права: брать минимум

Запрашивайте только то, что нужно сейчас. Чтение вместо полного доступа, конкретные репозитории и папки вместо «всех». Расширить права позже — это повторное согласие, а не катастрофа.

Где хранить секреты

clientSecret, токены и пароли — в хранилище секретов, не в файлах конфигурации и не в переписке. В настройках источника оставляйте ссылку на запись в хранилище.

Проверка после настройки

1. Запрос, возвращающий идентификатор аккаунта — убедиться, что подключён тот аккаунт.
2. Запрос по назначению — список писем, файлов, задач.
3. Повторить через час — проверка живого токена обновления.
4. Записать в описание источника: какой аккаунт, какие права, где лежит секрет.