sgauth

README

Google Authenticator

This is the initial repository of Google Authenticator --- a shard-agnostic client library that provides a unified future-proof interface for Google API authentication.

The project is still at very early stage so everything is subject to change.

Concept

Google Authenticator is a future-proof client library that aims to simplify the developer experience with Google API authentication.

Comparing with existing Google Authentication Libraries, it bring the following advantages:

• Lightweight concept: Decouple the authentication client from underlying workflow. Application only provides credentials and then make the API call. As a result, developers should only need minimum knowledge about the authentication workflow.

• Unified interface: The developer only needs to provide a general settings object. This unified credential object is an extensible structure that can contain arbitrary type of credentials.

Quickstart

To use the authenticator library in your application simply import the package in your source code:

import "github.com/google/oauth2l/sgauth"

To use the authenticator to call Google APIs, simply create a authenticator settings object with the credentials supported by Google APIs, and use the settings to create the client. For example, to call Google API with HTTP and API key:

import "github.com/google/oauth2l/sgauth"

// Create the settings with pasted API key.
settings := &sgauth.Settings{
                APIKey: "YOUR_API_KEY",
            }
// Create the HTTP client with the settings using authenticator.
http, err := sgauth.NewHTTPClient(ctx, createSettings(args))
if err != nil {
	// Call Google API here
}

Credentials

To authenticate against Google API, users need to provide required credentials. The authenticator takes a general settings object that supports multiple types of credentials:

• Service account JSON: You can explicitly set the JSON string downloaded from Pantheon so it can be used by either OAuth or JWT auth flow. If you prefer to use the JWT token authentication flow, the aud value has to be provided. Alternatively, you can use the OAuth flow where you need to specify the scope value.

• API Key: The Google API key.

• Application Default Credentials: If no credentials set explicitly, Google Authenticator will try to look for your service account JSON file at the default path --- the path specified by the $GOOGLE_APPLICATION_CREDENTIAL environment variable.

• Authorized User: If no above conditions are defined and you can still auth to google by genearating ADC with command gcloud auth application-default login. This will store ADC at wellknown path ~/.config/gcloud/application_default_credentials.json

Protocols

Google authenticator supports three protocols which are widely supported by Google APIs: REST, gRPC, ProtoRPC

To use the library calling REST APIs, simply create a HTTP client:

import "github.com/google/oauth2l/sgauth"

// Create the settings
settings := &sgauth.Settings{
                // Config your credential settings
            }
// Create the HTTP client with the settings using authenticator.
http, err := sgauth.NewHTTPClient(ctx, createSettings(args))
if err != nil {
	// Call REST Google API here
}

Or you can use the library with a gRPC API client:

import "github.com/google/oauth2l/sgauth"

// Create the settings
settings := &sgauth.Settings{
                // Config your credential settings
            }
// Create the gRPC connection with the settings using authenticator.
conn, err := sgauth.NewGrpcConn(ctx, createSettings(args), "YOUR_HOST", "YOUR_PORT")
if err != nil {
    return nil, err
}
client := library.NewLibraryServiceClient(conn)

To use the library calling ProtoRPC APIs:

import "github.com/google/oauth2l/sgauth"
import "github.com/wora/protorpc/client"

// Create the settings
settings := &sgauth.Settings{
                // Config your credential settings
            }
// Create the HTTP client with the settings using authenticator.
http, err := sgauth.NewHTTPClient(ctx, createSettings(args))
if err != nil {
	// Call REST Google API here
}
client := &client.Client{
		HTTP:        http,
		BaseURL:     "YOUR_PROTORPC_BASE_URL",
		UserAgent:   "protorpc/0.1",
}

Documentation

Overview

Copyright 2018 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2018 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2018 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2018 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2018 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2018 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2018 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Variables
• func AppEngineTokenSource(ctx context.Context, scope ...string) internal.TokenSource
• func ComputeTokenSource(account string) internal.TokenSource
• func DefaultTokenSource(ctx context.Context, scope string) (internal.TokenSource, error)
• func FindJSONCredentials(ctx context.Context, settings *Settings) (*credentials.Credentials, error)
• func GuessUnixHomeDir() string
• func JWTTokenSource(ctx context.Context, settings *Settings) (internal.TokenSource, error)
• func NewGrpcConn(ctx context.Context, settings *Settings, host string, port string) (*grpc.ClientConn, error)
• func NewHTTPClient(ctx context.Context, settings *Settings) (*http.Client, error)
• func OAuthJSONTokenSource(ctx context.Context, settings *Settings) (internal.TokenSource, error)
• type Settings
  • func (s Settings) AuthMethod() string
• type Token
  • func FetchToken(ctx context.Context, settings *Settings) (*Token, error)

Variables

var DefaultScope = "https://www.googleapis.com/auth/cloud-platform"

var MethodAPIKey = "apikey"

var MethodJWT = "jwt"

var MethodOAuth = "oauth"

Functions

func AppEngineTokenSource

func AppEngineTokenSource(ctx context.Context, scope ...string) internal.TokenSource

AppEngineTokenSource returns a token source that fetches tokens issued to the current App Engine application's service account. If you are implementing a 3-legged OAuth 2.0 flow on App Engine that involves user accounts, see oauth2.Config instead.

The provided context must have come from appengine.NewContext.

func ComputeTokenSource

func ComputeTokenSource(account string) internal.TokenSource

ComputeTokenSource returns a token source that fetches access tokens from Google Compute Engine (GCE)'s metadata server. It's only valid to use this token source if your program is running on a GCE instance. If no account is specified, "default" is used. Further information about retrieving access tokens from the GCE metadata server can be found at https://cloud.google.com/compute/docs/authentication.

func DefaultTokenSource

func DefaultTokenSource(ctx context.Context, scope string) (internal.TokenSource, error)

DefaultTokenSource returns the token source for "Application Default Credentials". It is a shortcut for FindDefaultCredentials(ctx, scope).TokenSource.

func FindJSONCredentials

func FindJSONCredentials(ctx context.Context, settings *Settings) (*credentials.Credentials, error)

func GuessUnixHomeDir

func GuessUnixHomeDir() string

func JWTTokenSource

func JWTTokenSource(ctx context.Context, settings *Settings) (internal.TokenSource, error)

func NewGrpcConn

func NewGrpcConn(ctx context.Context, settings *Settings, host string, port string) (*grpc.ClientConn, error)

func NewHTTPClient

func NewHTTPClient(ctx context.Context, settings *Settings) (*http.Client, error)

Returns the HTTP client using the given settings.

func OAuthJSONTokenSource

func OAuthJSONTokenSource(ctx context.Context, settings *Settings) (internal.TokenSource, error)

Types

type Settings

type Settings struct {
	// The JSON credentials content downloaded from Google Cloud Console.
	CredentialsJSON string
	// If specified, use OAuth. Otherwise, JWT.
	Scope string
	// The audience field for JWT auth
	Audience string
	// The Google API key
	APIKey string
	// This is only used for domain-wide delegation.
	// UNIMPLEMENTED
	User string
	// The identifier to the user that the per-user quota will be charged
	// against. If not specified, the identifier to the authenticated account
	// is used. If there is no authenticated account too, the caller's network
	// IP address will be used.
	// UNIMPLEMENTED
	QuotaUser string
	// A user specified project that is responsible for the request quota and
	// billing charges.
	QuotaProject string
	// End-user OAuth Flow handler that redirects the user to the given URL
	// and returns the token.
	OAuthFlowHandler func(url string) (token string, err error)
	// The state string used for 3LO session verification.
	// UNIMPLEMENTED
	State string
}

An extensible structure that holds the credentials for Google API authentication.

func (Settings) AuthMethod

func (s Settings) AuthMethod() string

type Token

type Token struct {
	internal.Token
}

Wrapper of internal.Token that is visible from public. Token represents the credentials used to authorize the requests to access protected resources on the OAuth 2.0 provider's backend.

func FetchToken

func FetchToken(ctx context.Context, settings *Settings) (*Token, error)

Returns a token from the given settings. Returns nil for API keys.