Skip to main content

google-oauth (rb-google-oauth)

Общая авторизация Google для CLI-инструментов (gsc, …) — аналог yandex-oauth для Google. Один набор ключей — в общем слоте keychain google-oauth:* для всех инструментов: вход в любом из них авторизует остальные. Без дублирования кода и без .env-файлов.

Сейчас поддерживаются ключ сервисного аккаунта (access token получается и обновляется сам через google-auth) и API-ключи (PageSpeed Insights и другие). Вход пользователя через браузер (OAuth) пока не нужен, но схема хранения к нему готова (см. «Как добавить OAuth пользователя»).

Только macOS и Linux.

Что даёт

Объект Назначение
Profile Чем инструмент отличается: имя CLI, название сервиса, scopes, «исторические» env-переменные инструмента, нужные API-ключи (ApiKey), подсказка после входа
GoogleAuth(profile) Найти ключ сервисного аккаунта / API-ключ, credentials(scopes) (google-auth), refresh(creds), bearer(scopes).headers() — токен с автообновлением для каждого запроса, status(check=), store_*, logout
CredentialStore(profile) Keychain ОС через keyring + имена переменных окружения; backend() для doctor
make_auth_app(auth, output, check=None, api_key_checks=None) Готовая Typer-команда auth login / logout / status [--check] (модуль rb_google_oauth.auth_command); auth status — отчёт §8 стандарта tools
health_check(auth, check=None, provider=None) → Health Делегат для Provider.health_check() инструмента по шаблону cli-generator (см. «Проверка доступов»)
credential_status, status_report, status_problems, status_exit_code Сборка отчёта auth status --json для инструмента со своей командой auth
Ошибки CliError (базовый — его ловит output.guard инструмента), InvalidArguments (exit 2), NotAuthorized (exit 3), TokenRequestFailed (exit 5), CredentialStoreUnavailable, CredentialsUnhealthy (exit 3)

Импорт google_oauth не трогает сеть, keychain, google-auth и typer.

Где лежат ключи

Что Keychain (service / account) Переменные окружения (по приоритету)
Ключ сервисного аккаунта (JSON) google-oauth:service_account / default env инструмента из профиля (например GSC_GOOGLE_SERVICE_ACCOUNT_JSON) → GOOGLE_OAUTH_SERVICE_ACCOUNT_JSON → env инструмента с путём к файлу → GOOGLE_OAUTH_SERVICE_ACCOUNT_FILE
API-ключ <name> google-oauth:api_key / <name> env инструмента (например GSC_PAGESPEED_API_KEY) → GOOGLE_OAUTH_<NAME>_API_KEY

Любая переменная окружения приоритетнее keychain. Недоступный keychain (headless Linux без Secret Service) при чтении — не ошибка: работают переменные окружения, auth status называет причину. На сервере ключи задаются окружением, например через секрет-менеджер — env-переменные из секрет-менеджера -- gsc … с GOOGLE_OAUTH_SERVICE_ACCOUNT_JSON (JSON ключа целиком) и GOOGLE_OAUTH_<NAME>_API_KEY; ничего не записывается, auth login не нужен.

Подключение к инструменту

pyproject.toml инструмента:

dependencies = ["rb-google-oauth>=0.2,<0.3", ...]

[tool.uv.sources]
rb-google-oauth = { git = "https://github.com/bolandeu/google-oauth.git", tag = "v0.2.0" }

Дистрибутив — rb-google-oauth (google-oauth на PyPI — чужой пакет), импорт — google_oauth. Пин — на тег релиза, обновление: новый tag + uv lock --upgrade-package rb-google-oauth. После переименования в существующем venv: uv sync --reinstall-package rb-google-oauth.

Профиль:

from rb_google_oauth import ApiKey, GoogleAuth, Profile

PROFILE = Profile(
    cli_name="gsc",
    service="Google Search Console",
    scopes=("https://www.googleapis.com/auth/webmasters.readonly", "https://www.googleapis.com/auth/webmasters"),
    service_account_env=("GSC_GOOGLE_SERVICE_ACCOUNT_JSON", "GOOGLE_SERVICE_ACCOUNT_JSON"),
    service_account_file_env=("GOOGLE_SERVICE_ACCOUNT_FILE",),
    api_keys=(ApiKey("pagespeed", "PageSpeed Insights", env=("GSC_PAGESPEED_API_KEY", "GOOGLE_PAGESPEED_API_KEY")),),
)
auth = GoogleAuth(PROFILE)

Клиент API:

bearer = auth.bearer(scopes)  # ключ читается при первом запросе
headers = bearer.headers()  # {"Authorization": "Bearer …"}, обновляется сам
psi_key = auth.api_key("pagespeed")  # или None

Команда: app.add_typer(make_auth_app(auth, output), name="auth"). core/errors.py инструмента импортирует CliError/InvalidArguments/NotAuthorized отсюда, чтобы output.guard ловил ошибки общего кода. Тесты инструмента подменяют rb_google_oauth.credentials.keyring.* (или тот же модуль через реэкспорт).

Проверка доступов (auth status, §8 стандарта tools)

make_auth_app выдаёт auth status [--check] --json в общей для всех инструментов форме: запись google (сервисный аккаунт, обязателен) и по записи на API-ключ (ApiKey(required=…), по умолчанию необязателен). source — env / file / keychain / missing, source_ref — имя переменной, путь к файлу или слот keychain, значений нет. Под --check сервисный аккаунт проверяется получением access token у Google (бесплатно), затем запросом check инструмента; API-ключ — запросом из api_key_checks={"pagespeed": …}, без него unchecked. Код выхода 3 — обязательный ключ не в порядке или любой ключ invalid.

Инструмент по шаблону cli-generator делегирует Provider.health_check():

import rb_google_oauth


def health_check(self) -> Health:
    return rb_google_oauth.health_check(GOOGLE_AUTH, check=lambda: self.get_json("/sites"))
    # API-ключ: rb_google_oauth.health_check(GOOGLE_AUTH, check, provider="pagespeed")

Лимит 10 с на всю проверку, без повторов; 401/403 и отказ Google → invalid, сеть/429/5xx/таймаут → unreachable; значения секретов вычищаются из message. expires_at — None: у ключей нет срока.

Почему так: готовые библиотеки

По правилу «сначала готовое» сравнивались (сентябрь 2026):

Библиотека Решение
google-auth (Google, Apache 2.0) Берём. Сервисный аккаунт с автообновлением токена, api_key.Credentials, токен пользователя из JSON (from_authorized_user_info), ADC, impersonation — вся криптография и работа с токенами
keyring (MIT) Берём. Keychain macOS / Secret Service Linux, как в yandex-oauth
google-auth-oauthlib (Google) Позже — для входа пользователя через браузер (InstalledAppFlow)
google-api-python-client (Google) Нет: это клиенты API, а не авторизация
oauth2client (Google) Нет: устарел с 2018, заменён google-auth
pydata-google-auth Нет: только вход пользователя, токен в файле, без сервисных аккаунтов и keychain
gcloud-aio-auth Нет: асинхронный, инструменты синхронные
Authlib Нет: универсальный OAuth, для Google избыточен

Своё здесь только то, чего нет ни в одной из них: общий слот keychain и порядок env-переменных, Profile, Typer-команда, статус и типизированные ошибки CLI.

ADC (google.auth.default(), доступы gcloud) намеренно не подхватывается: он молча берёт чужие доступы с машины, и можно работать не под тем аккаунтом.

Как добавить OAuth пользователя

Вид учётных данных уже в имени записи keychain (google-oauth:<kind>). Для OAuth: запись google-oauth:authorized_user / default с JSON формата google-auth (Credentials.to_json()), вход — google-auth-oauthlib InstalledAppFlow.run_local_server, чтение — google.oauth2.credentials.Credentials.from_authorized_user_info, после обновления токена — перезапись JSON в keychain. BearerToken уже работает с любыми google-auth Credentials.

Разработка и релизы

uv sync
gate check   # гейт: lock, ruff, ty, pytest, wheel, osv-scanner, gitleaks; идёт на этой машине

Версия — из git-тега vX.Y.Z; релиз — antagor publish (стандарт: https://github.com/bolandeu/python-package-gate/blob/main/skills/cli-builder/reference/standard.md, «Release»). Справка команд auth — контракт: uv run pytest --snapshot-update после её изменения.

Metadata

Release files for rb-google-oauth 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rb-google-oauth 0.3.2
File Size Uploaded Provenance Actions
rb_google_oauth-0.3.2.tar.gz 30.6 kB Without provenance Details for rb_google_oauth-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rb-google-oauth 0.3.2
File Interpreter ABI Platform Actions
rb_google_oauth-0.3.2-py3-none-any.whl Python 3 none any Details for rb_google_oauth-0.3.2-py3-none-any.whl

Total release size: 55.1 kB

Release files / rb_google_oauth-0.3.2.tar.gz

Download URL rb_google_oauth-0.3.2.tar.gz
Size 30.6 kB
Tags Source
SHA-256 checksum
How to use checksums
95e63795a464e23ca771bcf4260218a860f6d4afb4758330ba4c9453400a5ec3
BLAKE2b-256 checksum
How to use checksums
d6bf349c6d2204cdac2471923586a0c334b0be475d1ca03353d1b8efbaaa525e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / rb_google_oauth-0.3.2-py3-none-any.whl

Download URL rb_google_oauth-0.3.2-py3-none-any.whl
Size 24.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2a5e88c400eac2ad0a9211aa2e2502feedfc09b1dd3a9953ff37a30c0e3b058b
BLAKE2b-256 checksum
How to use checksums
591a5d6af8916629a29ad30e9ecfd8aacf4fe21e4f0b433a483514a1ce1757d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for rb-google-oauth 0.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page