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] (модуль 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 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 ловил ошибки общего кода. Тесты инструмента подменяют 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 google_oauth


def health_check(self) -> Health:
    return google_oauth.health_check(GOOGLE_AUTH, check=lambda: self.get_json("/sites"))
    # API-ключ: 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.1

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.1
File Size Uploaded Provenance Actions
rb_google_oauth-0.3.1.tar.gz 30.6 kB Without provenance Details for rb_google_oauth-0.3.1.tar.gz

Built distribution (wheel)

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

Total release size: 55.0 kB

Release files / rb_google_oauth-0.3.1.tar.gz

Download URL rb_google_oauth-0.3.1.tar.gz
Size 30.6 kB
Tags Source
SHA-256 checksum
How to use checksums
a53ac33dd2988257fc1dabab3cc6bd0a2e31dea1359a5877da7096ebc238e1c3
BLAKE2b-256 checksum
How to use checksums
147c27847c847871ce8270aa45db3ffd2438e1c3cb6677e79b8a856491240f7d
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.1-py3-none-any.whl

Download URL rb_google_oauth-0.3.1-py3-none-any.whl
Size 24.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5668b0e4179be4abdf1671b7b3b4ad2fc0d4b0c0181f4abb1c748ec3ad077723
BLAKE2b-256 checksum
How to use checksums
a634d78431e38d16deada97969dafcfd10baf233341de2c5ff4361d7226e00a9
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.1

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