oauth2l

The oauth2l tool automatically detects the appropriate authentication context based on your environment:

• Google Compute Engine (GCE) / Google Kubernetes Engine (GKE): Uses the current service account credentials if available.
• Google Cloud SDK (gcloud): Uses the current active gcloud session credentials.
• JSON Credential Files: Use the --credentials xxx flag to point to a service account key or OAuth client ID JSON file.
• JWT (Service Accounts): Use --type jwt --audience xxx with a service account key to generate a signed JWT token.
• SSO: Use --type sso --email xxx to invoke an external sso command for Single Sign-on tokens.

Caching

By default, tokens are cached in ~/.oauth2l.

• Override location: --cache xxx
• Disable caching: --cache "" (empty string)

You can install oauth2l using several methods depending on your environment:

Homebrew (Mac OS X)

brew install oauth2l

Docker

Use the official image gcr.io/oauth2l/oauth2l. You can run it directly:

docker run -it gcr.io/oauth2l/oauth2l header cloud-platform

Or copy the binary into your own Dockerfile:

FROM my-awesome-container
COPY --from=gcr.io/oauth2l/oauth2l /bin/oauth2l /bin/oauth2l

From Source (Linux or Mac)

Requires Go 1.10.3 or higher:

git clone https://github.com/google/oauth2l
cd oauth2l
make dev

Note: If you install from source, ensure $GOPATH/bin is in your $PATH to run oauth2l directly.

You can install oauth2l using pip. Depending on your OS and desired installation scope, use one of the following methods:

System-wide installation (typically /usr/local/bin):

# Mac only. Install pip first if needed
$ sudo easy_install pip

# Install and upgrade
$ pip install google-oauth2l --upgrade

# If you encounter errors on OS X El Capitan or later
$ pip install google-oauth2l --upgrade --ignore-installed

User-specific installation (typically ~/.local/bin on Linux or ~/Library/Python/2.7/bin on Mac):

$ pip install --user google-oauth2l

# Install oauth2l under the current user
$ pip install --user google-oauth2l

The oauth2l CLI provides several commands to fetch, inspect, and manage OAuth 2.0 access tokens. The primary commands are:

• fetch: Fetches an access token.
• header: Fetches an access token and returns it in an HTTP header format (e.g., Authorization: Bearer <token>).
• curl: Fetches an access token and immediately uses it to make a curl request to a specified URL.
• info: Displays metadata and information about an existing OAuth access token.
• test: Validates an OAuth access token. Returns exit code 0 if the token is valid.
• reset: Clears the local credential cache.
• web: Launches a local instance of the OAuth2l Playground web app (experimental).

When using fetch, header, or curl commands, you must specify an authentication type using the --type flag. The available types are:

• oauth: Executes a 2-legged OAuth (2LO) flow for Service Accounts or a 3-legged OAuth (3LO) flow for OAuth Client IDs. This is the default.
• jwt: Signs claims using a private key. This only works for Service Accounts. Requires the --audience flag.
• sso: Exchanges a LOAS credential for an OAuth token. Requires the --email flag.

# Example: Using OAuth flow (default)
# Example: Using JWT flow
# Example: Using SSO flow

The header command is a wrapper for fetch that outputs the token in the Authorization: Bearer <token> HTTP header format. This is ideal for use with curl.

Direct usage with curl:

$ curl -H "$(oauth2l header pubsub)" https://pubsub.googleapis.com/v1/projects/my-project-id/topics

Recommended: Create a shell alias for frequent API calls:

alias gcurl='curl -H "$(oauth2l header cloud-platform)" -H "Content-Type: application/json" '
$ gcurl 'https://pubsub.googleapis.com/v1/projects/my-project-id/topics'

The test command checks if a token is valid. It returns an exit code of 0 for a valid token and 1 for an invalid one, making it useful for shell script logic.

$ oauth2l test <TOKEN>
$ echo $?

$ oauth2l test ya29.zyxwvutsrqpnmolkjihgfedcba

To clear all locally cached credentials, use the reset command. oauth2l caches tokens in the user's home directory at ~/.oauth2l.token to avoid repeated prompts.

$ oauth2l reset

The fetch command retrieves and prints an access token for the specified OAuth scopes.

Output Formats: Use the -f flag to specify the output format. Supported formats are:

• bare (default): Prints only the token string.
• json: Prints a JSON object containing the token, expiry, and metadata.
• json_compact: Compact JSON output.
• pretty: Pretty-printed JSON.
• header: (Use the header command instead for HTTP header format).

Example usage:

# Fetch bare token
$ oauth2l fetch userinfo.email cloud-platform

# Fetch JSON metadata
$ oauth2l fetch -f json userinfo.email cloud-platform

oauth2l info

Prints metadata about a token, including expiration time and scopes. If the token has userinfo.email or plus.me scopes, it also prints the authenticated email address.

$ oauth2l info --token <TOKEN>
{
    "expires_in": 3599,
    "scope": "https://www.googleapis.com/auth/pubsub",
    "email": "user@gmail.com"
}

oauth2l test

Validates a token and returns an exit code (0 for valid, 1 for invalid). This is ideal for shell pipelines.

$ oauth2l test --token <TOKEN>
0
$ echo $?
0

oauth2l info --token $(oauth2l fetch --scope pubsub)

When using a Service Account key file with the --json option, you can use the --jwt flag to generate a JWT token signed by the service account's private key.

When using --jwt, you do not provide a list of scopes; instead, you must provide a single JWT audience (e.g., the URL of the service you are accessing).

$ oauth2l fetch --jwt --json ~/service_account.json https://pubsub.googleapis.com/google.pubsub.v1.Publisher