Storing OAuth refresh tokens in macOS Keychain

Chapter 4 of 8. This chapter is self-contained. If you want the full chronological build-up: Chapter 1 (the motivation), Chapter 2 (Google Cloud project + enabling the APIs), and Chapter 3 (the OAuth 2.0 protocol walkthrough) are the prerequisites. For now, what you need to know: this chapter assumes you've already created an OAuth client in Google Cloud Console (Desktop application type) and completed the consent flow once, which gave you a refresh_token printed to stdout. The whole chapter is about what to do with it next.

Why the refresh token deserves better than .env

A Google OAuth refresh token is a long-lived bearer credential. Anyone holding it can mint access tokens for your account, against any scope that was authorised, without your involvement. The default install-script advice — write it to a .env file — works, but it leaves the credential in plaintext on disk, readable by every process that runs under your user.

macOS Keychain solves three problems at once: the credential is encrypted at rest behind your login keychain's master key; the OS gates access per-application (per RFC 6749 §10.4, refresh-token storage is left to the implementer, and Keychain is the documented Apple-blessed implementation); and the security CLI gives you a stable interface that any process can shell out to without linking against a framework.

Writing the token in

The security add-generic-password subcommand creates an entry under your default keychain. Pick a service name that disambiguates this token from anything else in there:

security add-generic-password \
  -s "gsc-telemetry:captain_random:refresh_token" \
  -a "$USER" \
  -w "$REFRESH_TOKEN" \
  -U  # update if it already exists

The -U flag matters more than it looks. Without it, re-running the install script after a token rotation throws The specified item already exists in the keychain. (per Apple's Keychain Services error reference). With it, the entry is atomically replaced.

Reading the token from Python

Shell out to security find-generic-password from Python via subprocess.run (see the subprocess module docs for the security semantics of arguments-as-list). The -w flag prints the password to stdout; everything else stays on stderr:

import subprocess

def read_refresh_token() -> str:
    result = subprocess.run(
        [
            "security",
            "find-generic-password",
            "-s",
            "gsc-telemetry:captain_random:refresh_token",
            "-a",
            os.getenv("USER"),
            "-w",
        ],
        capture_output=True,
        text=True,
        check=True,
    )
    return result.stdout.strip()

The first call after a fresh shell session triggers a Keychain access prompt. Tick "Always Allow" only if this script will run unattended (per Apple's docs, this stores a permanent access entry against the specific binary path; renaming the script invalidates it).

Refresh-to-access exchange

With the refresh token in hand, the google-auth library handles the access-token mint. Per RFC 6749 §6, you exchange grant_type=refresh_token plus your client credentials for a fresh access token; google-auth wraps the call:

from google.oauth2.credentials import Credentials

creds = Credentials(
    token=None,                       # access token — filled by refresh()
    refresh_token=read_refresh_token(),
    token_uri="https://oauth2.googleapis.com/token",
    client_id=os.environ["GOOGLE_OAUTH_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_OAUTH_CLIENT_SECRET"],
    scopes=[
        "https://www.googleapis.com/auth/webmasters.readonly",
        "https://www.googleapis.com/auth/analytics.readonly",
    ],
)
creds.refresh(google.auth.transport.requests.Request())

Access tokens last one hour. The Credentials object handles re-minting transparently when the access token expires mid-script — but only if refresh_token is set, and only if client_id + client_secret are also passed (per Google's OAuth docs, the client secret is part of the refresh exchange).

What to do when the token gets revoked

Refresh tokens don't expire on a schedule but they can be revoked: by the user from their Google account page, by Google's automatic policies (six months of inactivity, scope changes, password reset), or by your application calling revoke(). When that happens, creds.refresh() raises RefreshError. The right response is to surface a clear error and re-run the consent flow — the refresh token can't be recovered.

Build that into your CLI as a --reauth subcommand. The pattern: delete the Keychain entry (security delete-generic-password -s "..."), run the InstalledAppFlow once more, prompt for the new token, write it back to Keychain. The whole cycle takes about thirty seconds and is the only time the user sees the consent screen after first install.