Package: google-oauth2l
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 forworking with[Google OAuth 2.0](https://developers.google.com/identity/protocols/OAuth2).Its primary use is to fetch andprint OAuth 2.0 access tokens, which can be used with other command-linetools and shell scripts.This tool also demonstrates how to design a simple and easy-to-use OAuth2.0 client experience. If you need to reimplement this functionality inanother programming language, please use [Go OAuth2l](go/oauth2client)as reference code.## Overview`oauth2l` supports all Google OAuth 2.0 authentication flows for both useraccounts and service accounts in different environments:*   When running inside Google Compute Engine (GCE) and Google ContainerEngine (GKE), it uses the credentials of the current service accountif 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 toa 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 beeither a service account key or an OAuth client ID.*   When running with command option `--sso {email}`, it invokes anexternal `sso` command to retrieve Single Sign-on (SSO) access token.NOTE: `oauth2l` caches the OAuth credentials in user's home directory toavoid 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### --jsonSpecifies an OAuth credential file, either an OAuth client ID or a ServiceAccount 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_cliUsing an external Single Sign-on (SSO) command to fetch OAuth token.The command outputs an OAuth access token to its stdout. The defaultcommand 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```### --jwtWhen this option is set and the json file specified in the `--json` optionis a service account key file, a JWT token signed by the service accountprivate key will be generated. When this option is set, no scope list isneeded 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### fetchFetch 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-platformya29.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.### headerThe same as `fetch`, except the output is in HTTP header format:```$ oauth2l header userinfo.emailAuthorization: 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 ashell 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'```### infoPrint information about a valid token. This always includes the list of scopesand 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 emailaddress of the authenticated identity.```$ oauth2l info $(oauth2l fetch pubsub){"expires_in": 3599,"scope": "https://www.googleapis.com/auth/pubsub","email": "user@gmail.com"...}```### testTest 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```### resetReset all tokens cached locally. We cache previously retrieved tokens in thefile `~/.oauth2l.token`.```$ oauth2l reset```