Skip to content

Commit

Permalink
Improved OAuth2l Client Interface (#70)
Browse files Browse the repository at this point in the history 
-Uses advanced go-flags library to parse command-line flags, which
improves organization, flexibility, and better built-in help doc.
-Added explicit flags for GUAC arguments such as scope and audience.
-Added support for a new "curl" command.
-Fixed variadic bug in sso.go that incorrectly handles multiple scopes.
  • Loading branch information
@andyrzhao @shinfan
andyrzhao authored and shinfan committed Aug 5, 2019
1 parent cf46f2e commit 717448a
Show file tree
Hide file tree
Showing 5 changed files with 516 additions and 124 deletions.
244 changes: 182 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,21 @@ accounts and service accounts in different environments:
* 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
* When running with command option `--credentials 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.
* 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

Expand All @@ -50,59 +57,16 @@ https://github.com/golang/go/wiki/GOPATH))

```bash
# Get the package from Github
$ go get github.com/google/oauth2l
$ go get -u github.com/google/oauth2l

# Install the package into your $GOPATH/bin/
$ go install github.com/google/oauth2l

# Fetch the access token from your credentials with cloud-platform scope
$ ~/go/bin/oauth2l fetch --json ~/your_credentials.json cloud-platform
$ ~/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 --json ~/your_credentials.json cloud-platform
```

## 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).

```bash
$ 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:

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

Then use oauth2l with the SSO CLI:

```bash
$ 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. See how to construct the
audience [here](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#jwt-auth).

Example:

```bash
oauth2l fetch --jwt --json ~/service_account.json https://pubsub.googleapis.com/google.pubsub.v1.Publisher
$ oauth2l fetch --credentials ~/your_credentials.json --scope cloud-platform
```

## Commands
Expand All @@ -116,7 +80,7 @@ the following command prints access token for the following OAuth2 scopes:
* https://www.googleapis.com/auth/cloud-platform

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

Expand All @@ -125,23 +89,25 @@ ya29.zyxwvutsrqpnmolkjihgfedcba
The same as `fetch`, except the output is in HTTP header format:

```bash
$ oauth2l header userinfo.email
$ oauth2l header --scope cloud-platform
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.
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.

```bash
$ curl -H "$(oauth2l header pubsub)" https://pubsub.googleapis.com/v1/projects/my-project-id/topics
$ curl -H "$(oauth2l header --scope 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:
### 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.

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

### info
Expand All @@ -153,7 +119,7 @@ and expiration time. If the token has either the
address of the authenticated identity.

```bash
$ oauth2l info $(oauth2l fetch pubsub)
$ oauth2l info --token $(oauth2l fetch --scope pubsub)
{
"expires_in": 3599,
"scope": "https://www.googleapis.com/auth/pubsub",
Expand All @@ -168,19 +134,173 @@ Test a token. This sets an exit code of 0 for a valid token and 1 otherwise,
which can be useful in shell pipelines.

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

### reset

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

```bash
$ oauth2l reset
```

## Command Options

### --help

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

```bash
$ oauth2l --help
```

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

```bash
$ 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](https://cloud.google.com/docs/authentication/getting-started).

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

### --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](https://developers.google.com/identity/protocols/OAuth2).

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

#### jwt

When jwt is selected and the json file specified in the `--credentials` option
is a service account key file, a JWT token signed by the service account
private key will be generated. When using this option, no scope parameter is
needed but a single JWT audience must be provided. See how to construct the
audience [here](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#jwt-auth).

```bash
$ oauth2l fetch --type jwt --credentials ~/service_account.json --audience https://pubsub.googleapis.com/
```

#### sso

When sso is selected, the tool will use an external Single Sign-on (SSO)
CLI to fetch an OAuth access token. The default SSO CLI only works with
Google's corporate SSO. An email is required in addition to scope.

To use oauth2l with the default SSO CLI:

```bash
$ oauth2l header --type sso --email me@google.com --scope cloud-platform
```

To use oauth2l with a custom SSO CLI:

```bash
$ oauth2l header --type sso --ssocli /usr/bin/sso --email me@google.com --scope cloud-platform
```

Note: The custom SSO CLI should have the following interface:

```bash
$ /usr/bin/sso me@example.com scope1 scope2
```

### --scope

The scope(s) that will be authorized by the OAuth access token. Required for
oauth and sso authentication types. When using multiple scopes, provide the
the parameter as a comma-delimited list and do not include spaces. (Alternatively,
multiple scopes can be specified as a space-delimited string surrounded in quotes.)

```bash
$ oauth2l fetch --scope cloud-platform,pubsub
```

### --audience

The single audience to include in the signed JWT token. Required for jwt
authentication type.

```bash
$ oauth2l fetch --type jwt --audience https://pubsub.googleapis.com/
```

### --email

The email associated with SSO. Required for sso authentication type.

```bash
$ oauth2l fetch --type sso --email me@google.com --scope cloud-platform
```

### --ssocli

Path to SSO CLI. For optional use with "sso" authentication type.

```bash
$ oauth2l fetch --type sso --ssocli /usr/bin/sso --email me@google.com --scope cloud-platform
```

### --cache

Path to token cache file. Disables caching if set to empty (""). Defaults to ~/.oauth2l if not configured.

```bash
$ oauth2l fetch --cache ~/different_path/.oauth2l --scope cloud-platform
```

### fetch --output_format

Token's output format for "fetch" command. One of bare, header, json, json_compact, pretty. Default is bare.

```bash
$ oauth2l fetch --output_format pretty --scope cloud-platform
```

### curl --url

URL endpoint for curl request. Required for "curl" command.

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

### curl --curlcli

Path to Curl CLI. For optional use with "curl" command.

```bash
$ oauth2l curl --curlcli /usr/bin/curl --type sso --email me@google.com --scope cloud-platform --url https://pubsub.googleapis.com/v1/projects/my-project-id/topics
```
Loading

0 comments on commit 717448a

Please sign in to comment.