Skip to main content

command-line google oauth tools

Project description

oauth2l
-------

[![Build Status](https://travis-ci.org/google/oauth2l.svg?branch=master)](https://travis-ci.org/google/oauth2l)
[![Coverage](https://coveralls.io/repos/google/oauth2l/badge.svg?branch=master)](https://coveralls.io/r/google/oauth2l?branch=master)
[![PyPI](https://img.shields.io/pypi/v/google-oauth2l.svg)](https://pypi.python.org/pypi/google-oauth2l)
[![Versions](https://img.shields.io/pypi/pyversions/google-oauth2l.svg)](https://pypi.python.org/pypi/google-oauth2l)

`oauth2l` (pronounced "oauth tool") is a simple command-line tool for
working with
[Google OAuth 2.0](https://developers.google.com/identity/protocols/OAuth2).
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.

This tool also demonstrates how to design a simple and easy-to-use OAuth
2.0 client experience. If you need to reimplement this functionality in
another programming language, please use [Go OAuth2l](go/oauth2client)
as reference code.

## 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 Container
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 `--json xxx`, where `xxx` points to
a JSON credential file downloaded from
[Google Cloud Console](https://console.cloud.google.com/apis/credentials),
`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 `--sso {email}`, it invokes an
external `sso` command to retrieve Single Sign-on (SSO) access token.

NOTE: `oauth2l` caches the OAuth credentials in user's home directory to
avoid prompting user repeatedly.

## Install

```
# Mac only. Install `pip` first.
$ sudo easy_install pip

# Install `oauth2l` under the OS, typically "/usr/local/bin".
$ pip install google-oauth2l --upgrade

# If you see an error on OS X El Capitan or up, please try
$ pip install google-oauth2l --upgrade --ignore-installed

# Install `oauth2l` under the current user, typically "~/.local/bin" (on Linux)
# and "~/Library/Python/2.7/bin" (on Mac).
$ pip install --user google-oauth2l
```

## Command Options

### --json

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](https://console.cloud.google.com/apis/credentials).

```
$ oauth2l fetch --json ~/service_account.json cloud-platform
```

### --sso and --sso_cli

Using an external Single Sign-on (SSO) command to fetch OAuth token.
The command outputs an OAuth access token to its stdout. The default
command is for Google's corporate SSO. For example:

```
$ sso me@example.com scope1 scope2
```

Then use oauth2l with the SSO CLI:

```
$ oauth2l header --sso me@example.com --sso_cli /usr/bin/sso cloud-platform
$ oauth2l header --sso me@google.com cloud-platform
```

### --jwt

When this option is set and the json file specified in the `--json` option
is a service account key file, a JWT token signed by the service account
private key will be generated. When this option is set, no scope list is
needed but a single JWT audience must be provided.

Example:

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

## 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 userinfo.email cloud-platform
ya29.zyxwvutsrqpnmolkjihgfedcba

$ oauth2l fetch -f json userinfo.email cloud-platform
{
"access_token": "ya29.zyxwvutsrqpnmolkjihgfedcba",
"token_expiry": "2017-02-27T21:20:47Z",
"user_agent": "oauth2l/1.0.0",
...
}
```

NOTE: the `-f` flag specifies the output format. The supported formats are:
bare (default), header, json, json_compact, pretty.

### header

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

```
$ oauth2l header userinfo.email
Authorization: Bearer ya29.zyxwvutsrqpnmolkjihgfedcba
```

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

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

If you need to call Google APIs frequently using `curl`, you can define a
shell alias for it. For example:

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

### 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 $(oauth2l fetch 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.

```
$ oauth2l test ya29.zyxwvutsrqpnmolkjihgfedcba
$ echo $?
0
$ oauth2l test ya29.justkiddingmadethisoneup
$ echo $?
1
```

### reset

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

```
$ oauth2l reset
```


Project details


Release history Release notifications

This version
History Node

1.0.2

History Node

1.0.1

History Node

1.0.0

History Node

0.9.3

History Node

0.9.2

History Node

0.9.1

History Node

0.9.0

History Node

0.8.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
google_oauth2l-1.0.2-py2.py3-none-any.whl (17.4 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Mar 1, 2018
google-oauth2l-1.0.2.tar.gz (21.3 kB) Copy SHA256 hash SHA256 Source None Mar 1, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page