oauth2l

oauth2l (pronounced "oauth tool") is a simple command-line tool for working with Google OAuth 2.0 written in Go. Its primary use is to fetch and print OAuth 2.0 access tokens, which can be used with other command-line tools and shell scripts.

Overview

oauth2l supports all Google OAuth 2.0 authentication flows for both user accounts and service accounts in different environments:

When running inside Google Compute Engine (GCE) and Google Kubernetes Engine (GKE), it uses the credentials of the current service account if it is available.
When running inside user context that has an active Google Cloud SDK (gcloud) session, it uses the current gcloud credentials.
When running with command option --credentials xxx, where xxx points to a JSON credential file downloaded from Google Cloud Console, oauth2l uses the file to start an OAuth session. The file can be either a service account key or an OAuth client ID.
When running with command option --type jwt --audience xxx and a service account key, a JWT token signed by the service account key will be generated.
When running with command option --type sso --email xxx, oauth2l invokes an external sso command to retrieve Single Sign-on (SSO) access token.
By default, retrieved tokens will be cached and stored in "~/.oauth2l". The cache location can be overridden via --cache xxx. To disable caching, set cache location to empty ("").

Quickstart

Pre-compiled binaries

Pre-built binaries are available for Darwin (Mac OS X), Linux, and Windows. The latest releases can be downloaded from the links below:

| OS | Link | | -------------- | --------------------------------------------------------------- | | Darwin (amd64) | https://storage.googleapis.com/oauth2l/latest/darwin_amd64.tgz | | Darwin (arm64) | https://storage.googleapis.com/oauth2l/latest/darwin_arm64.tgz | | Linux (amd64) | https://storage.googleapis.com/oauth2l/latest/linux_amd64.tgz | | Linux (arm64) | https://storage.googleapis.com/oauth2l/latest/linux_arm64.tgz | | Windows (amd64)| https://storage.googleapis.com/oauth2l/latest/windows_amd64.tgz |

To download an older version, substitute "latest" for any tagged version you like, omitting the "v" prefix (ex: 1.3.1).

Homebrew (Mac OS X)

On Mac OS X, you can install oauth2l via Homebrew:

$ brew install oauth2l

Note that new releases may not be immediately available via Homebrew due to propagation delay. Details are available at Homebrew oauth2l page.

Docker

An official Docker image is available at:

gcr.io/oauth2l/oauth2l

You can run this directly:

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

Or use it to inject into an existing container:

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

Like the binary releases, the container images are tagged to match the repository tags (without the leading "v"). For master builds, use the "latest" tag.

Everywhere else

On other systems, you need to meet the following requirements to use this tool:

Minimum requirements:

The tool is only available for Linux or Mac
Go 1.10.3 or higher

Nice to have:

Add your $GOPATH/bin into your $PATH (instructions)

# Get the package from Github
$ git clone https://github.com/google/oauth2l
$ cd oauth2l

# Install the package into your $GOPATH/bin/
$ make dev

# Fetch the access token from your credentials with cloud-platform scope
$ ~/go/bin/oauth2l fetch --credentials ~/your_credentials.json --scope cloud-platform

# Or you can run if you $GOPATH/bin is already in your $PATH
$ oauth2l fetch --credentials ~/your_credentials.json --scope cloud-platform

Commands

fetch

Fetch and print an access token for the specified OAuth scopes. For example, the following command prints access token for the following OAuth2 scopes:

https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/cloud-platform

$ oauth2l fetch --scope userinfo.email,cloud-platform
ya29.zyxwvutsrqpnmolkjihgfedcba

header

The same as fetch, except the output is in HTTP header format:

$ oauth2l header --scope cloud-platform
Authorization: Bearer ya29.zyxwvutsrqpnmolkjihgfedcba

The header command is designed to be easy to use with the curl CLI. For example, the following command uses the PubSub API to list all PubSub topics.

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

To send an API request using domain-wide delegation (DwD), for example, to list user@example.com's Gmail labels:

$ curl -H "$(oauth2l header --email user@example.com --credentials service_account_credentials.json --scope https://www.googleapis.com/auth/gmail.labels)" https://gmail.googleapis.com/gmail/v1/users/me/labels

curl

This is a shortcut command that fetches an access token for the specified OAuth scopes and uses the token to make a curl request (via 'usr/bin/curl' by default). Additional flags after "--" will be treated as curl flags.

$ oauth2l curl --scope cloud-platform,pubsub --url https://pubsub.googleapis.com/v1/projects/my-project-id/topics -- -i

To send an API request using domain-wide delegation (DwD), for example, to list user@example.com's Gmail labels:

$ oauth2l curl --email user@example.com --credentials service_account_credentials.json --scope https://www.googleapis.com/auth/gmail.labels --url https://gmail.googleapis.com/gmail/v1/users/me/labels

info

Print information about a valid token. This always includes the list of scopes and expiration time. If the token has either the https://www.googleapis.com/auth/userinfo.email or https://www.googleapis.com/auth/plus.me scope, it also prints the email address of the authenticated identity.

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

test

Test a token. This sets an exit code of 0 for a valid token and 1 otherwise, which can be useful in shell pipelines. It also prints the exit code.

$ oauth2l test --token ya29.zyxwvutsrqpnmolkjihgfedcba
0
$ echo $?
0
$ oauth2l test --token ya29.justkiddingmadethisoneup
1
$ echo $?
1

reset

Reset all tokens cached locally. We cache previously retrieved tokens in the file ~/.oauth2l by default.

$ oauth2l reset

web

Locally deploys and launches the OAuth2l Playground web application in a browser. If the web application packages are not yet installed, it will be installed under ~/.oauth2l-web by default. See Command Options section for all supported options for the web command.

Note that a local installation of Docker and docker-compose tool is required in order to support this feature. For most platforms, Docker can be installed by following the instructions here. For Google workstations, follow special installation procedures at "go/installdocker". The web feature is currently experimental and will be improved in the future.

$ oauth2l web

Command Options

--help

Prints help messages for the main program or a specific command.

$ oauth2l --help

$ oauth2l fetch --help

--credentials

Specifies an OAuth credential file (either an OAuth client ID or a Service Account key) to start the OAuth flow. You can download the file from Google Cloud Console. If you wish to use OAuth client ID with oauth2l, please choose "Desktop" (instead of "Web", etc.) for your application type when generating the file, so that the post-authentication flow can correctly redirect to the oauth2l localhost server.

$ oauth2l fetch --credentials ~/service_account.json --scope cloud-platform

If this option is not supplied, it will be read from the environment variable GOOGLE_APPLICATION_CREDENTIALS. For more information, please read Getting started with Authentication.

$ export GOOGLE_APPLICATION_CREDENTIALS="~/service_account.json"
$ oauth2l fetch --scope cloud-platform

When using an OAuth client ID file, the following applies:

If the first redirect_uris in the --credentials client_id.json is set to urn:ietf:wg:oauth:2.0:oob, the 3LO out of band flow is activated. NOTE: 3LO out of band flow has been deprecated and will stop working entirely in Oct 2022.

If the first redirect_uris in the --credentials client_id.json is set to http://localhost[:PORT], the 3LO loopback flow is activated. When the port is omitted, an available port will be used to spin up the localhost. When a port is provided, oauth2l will attempt to use such port. If the port cannot be used, oauth2l will stop.

--type

The authentication type. The currently supported types are "oauth", "jwt", or "sso". Defaults to "oauth".

oauth

When oauth is selected, the tool will fetch an OAuth access token through one of two different flows. If service account key is provided, 2-legged OAuth flow is performed. If OAuth Client ID is provided, 3-legged OAuth flow is performed, which requires user consent. Learn about the different types of OAuth here.

$ oauth2l fetch --type oauth --credentials ~/client_credentials.json --scope cloud-platform

jwt

When jwt is selected and the json file

Oauth2l

Install / Use

README