Documentation
¶
Overview ¶
Package google provides support for making OAuth2 authorized and authenticated HTTP requests to Google APIs. It supports the Web server flow, client-side credentials, service accounts, Google Compute Engine service accounts, and Google App Engine service accounts.
For more information, please read https://developers.google.com/accounts/docs/OAuth2 and https://developers.google.com/accounts/docs/application-default-credentials.
Example (ServiceAccount) ¶
package main
import (
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
"golang.org/x/oauth2/jwt"
)
func main() {
// Your credentials should be obtained from the Google
// Developer Console (https://console.developers.google.com).
conf := &jwt.Config{
Email: "xxx@developer.gserviceaccount.com",
// The contents of your RSA private key or your PEM file
// that contains a private key.
// If you have a p12 file instead, you
// can use `openssl` to export the private key into a pem file.
//
// $ openssl pkcs12 -in key.p12 -passin pass:notasecret -out key.pem -nodes
//
// The field only supports PEM containers with no passphrase.
// The openssl command will convert p12 keys to passphrase-less PEM containers.
PrivateKey: []byte("-----BEGIN RSA PRIVATE KEY-----..."),
Scopes: []string{
"https://www.googleapis.com/auth/bigquery",
"https://www.googleapis.com/auth/blogger",
},
TokenURL: google.JWTTokenURL,
// If you would like to impersonate a user, you can
// create a transport with a subject. The following GET
// request will be made on the behalf of user@example.com.
// Optional.
Subject: "user@example.com",
}
// Initiate an http.Client, the following GET request will be
// authorized and authenticated on the behalf of user@example.com.
client := conf.Client(oauth2.NoContext)
client.Get("...")
}
Output:
Example (WebServer) ¶
package main
import (
"fmt"
"log"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
)
func main() {
// Your credentials should be obtained from the Google
// Developer Console (https://console.developers.google.com).
conf := &oauth2.Config{
ClientID: "YOUR_CLIENT_ID",
ClientSecret: "YOUR_CLIENT_SECRET",
RedirectURL: "YOUR_REDIRECT_URL",
Scopes: []string{
"https://www.googleapis.com/auth/bigquery",
"https://www.googleapis.com/auth/blogger",
},
Endpoint: google.Endpoint,
}
// Redirect user to Google's consent page to ask for permission
// for the scopes specified above.
url := conf.AuthCodeURL("state")
fmt.Printf("Visit the URL for the auth dialog: %v", url)
// Handle the exchange code to initiate a transport.
tok, err := conf.Exchange(oauth2.NoContext, "authorization-code")
if err != nil {
log.Fatal(err)
}
client := conf.Client(oauth2.NoContext, tok)
client.Get("...")
}
Output:
Index ¶
- Constants
- Variables
- func AppEngineTokenSource(ctx context.Context, scope ...string) oauth2.TokenSource
- func ComputeTokenSource(account string) oauth2.TokenSource
- func ConfigFromJSON(jsonKey []byte, scope ...string) (*oauth2.Config, error)
- func DefaultClient(ctx context.Context, scope ...string) (*http.Client, error)
- func DefaultTokenSource(ctx context.Context, scope ...string) (oauth2.TokenSource, error)
- func JWTConfigFromJSON(jsonKey []byte, scope ...string) (*jwt.Config, error)
- type SDKConfig
Examples ¶
Constants ¶
const JWTTokenURL = "https://accounts.google.com/o/oauth2/token"
JWTTokenURL is Google's OAuth 2.0 token URL to use with the JWT flow.
Variables ¶
var Endpoint = oauth2.Endpoint{
AuthURL: "https://accounts.google.com/o/oauth2/auth",
TokenURL: "https://accounts.google.com/o/oauth2/token",
}
Endpoint is Google's OAuth 2.0 endpoint.
Functions ¶
func AppEngineTokenSource ¶
func AppEngineTokenSource(ctx context.Context, scope ...string) oauth2.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.
Example ¶
package main
import (
"net/http"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
"google.golang.org/appengine"
"google.golang.org/appengine/urlfetch"
)
func main() {
var req *http.Request // from the ServeHTTP handler
ctx := appengine.NewContext(req)
client := &http.Client{
Transport: &oauth2.Transport{
Source: google.AppEngineTokenSource(ctx, "https://www.googleapis.com/auth/bigquery"),
Base: &urlfetch.Transport{
Context: ctx,
},
},
}
client.Get("...")
}
Output:
func ComputeTokenSource ¶
func ComputeTokenSource(account string) oauth2.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.
Example ¶
package main
import (
"net/http"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
)
func main() {
client := &http.Client{
Transport: &oauth2.Transport{
// Fetch from Google Compute Engine's metadata server to retrieve
// an access token for the provided account.
// If no account is specified, "default" is used.
Source: google.ComputeTokenSource(""),
},
}
client.Get("...")
}
Output:
func ConfigFromJSON ¶
ConfigFromJSON uses a Google Developers Console client_credentials.json file to construct a config. client_credentials.json can be downloadable from https://console.developers.google.com, under "APIs & Auth" > "Credentials". Download the Web application credentials in the JSON format and provide the contents of the file as jsonKey.
func DefaultClient ¶
DefaultClient returns an HTTP Client that uses the DefaultTokenSource to obtain authentication credentials.
This client should be used when developing services that run on Google App Engine or Google Compute Engine and use "Application Default Credentials."
For more details, see: https://developers.google.com/accounts/docs/application-default-credentials
Example ¶
package main
import (
"log"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
)
func main() {
client, err := google.DefaultClient(oauth2.NoContext,
"https://www.googleapis.com/auth/devstorage.full_control")
if err != nil {
log.Fatal(err)
}
client.Get("...")
}
Output:
func DefaultTokenSource ¶
DefaultTokenSource is a token source that uses "Application Default Credentials".
It looks for credentials in the following places, preferring the first location found:
- A JSON file whose path is specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
- A JSON file in a location known to the gcloud command-line tool. On Windows, this is %APPDATA%/gcloud/application_default_credentials.json. On other systems, $HOME/.config/gcloud/application_default_credentials.json.
- On Google App Engine it uses the appengine.AccessToken function.
- On Google Compute Engine, it fetches credentials from the metadata server. (In this final case any provided scopes are ignored.)
For more details, see: https://developers.google.com/accounts/docs/application-default-credentials
func JWTConfigFromJSON ¶
JWTConfigFromJSON uses a Google Developers service account JSON key file to read the credentials that authorize and authenticate the requests. Create a service account on "Credentials" page under "APIs & Auth" for your project at https://console.developers.google.com to download a JSON key file.
Example ¶
package main
import (
"io/ioutil"
"log"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
)
func main() {
// Your credentials should be obtained from the Google
// Developer Console (https://console.developers.google.com).
// Navigate to your project, then see the "Credentials" page
// under "APIs & Auth".
// To create a service account client, click "Create new Client ID",
// select "Service Account", and click "Create Client ID". A JSON
// key file will then be downloaded to your computer.
data, err := ioutil.ReadFile("/path/to/your-project-key.json")
if err != nil {
log.Fatal(err)
}
conf, err := google.JWTConfigFromJSON(data, "https://www.googleapis.com/auth/bigquery")
if err != nil {
log.Fatal(err)
}
// Initiate an http.Client. The following GET request will be
// authorized and authenticated on the behalf of
// your service account.
client := conf.Client(oauth2.NoContext)
client.Get("...")
}
Output:
Types ¶
type SDKConfig ¶
type SDKConfig struct {
// contains filtered or unexported fields
}
An SDKConfig provides access to tokens from an account already authorized via the Google Cloud SDK.
Example ¶
package main
import (
"log"
"golang.org/x/oauth2"
"golang.org/x/oauth2/google"
)
func main() {
// The credentials will be obtained from the first account that
// has been authorized with `gcloud auth login`.
conf, err := google.NewSDKConfig("")
if err != nil {
log.Fatal(err)
}
// Initiate an http.Client. The following GET request will be
// authorized and authenticated on the behalf of the SDK user.
client := conf.Client(oauth2.NoContext)
client.Get("...")
}
Output:
func NewSDKConfig ¶
NewSDKConfig creates an SDKConfig for the given Google Cloud SDK account. If account is empty, the account currently active in Google Cloud SDK properties is used. Google Cloud SDK credentials must be created by running `gcloud auth` before using this function. The Google Cloud SDK is available at https://cloud.google.com/sdk/.
func (*SDKConfig) Client ¶
Client returns an HTTP client using Google Cloud SDK credentials to authorize requests. The token will auto-refresh as necessary. The underlying http.RoundTripper will be obtained using the provided context. The returned client and its Transport should not be modified.
func (*SDKConfig) TokenSource ¶
func (c *SDKConfig) TokenSource(ctx context.Context) oauth2.TokenSource
TokenSource returns an oauth2.TokenSource that retrieve tokens from Google Cloud SDK credentials using the provided context. It will returns the current access token stored in the credentials, and refresh it when it expires, but it won't update the credentials with the new access token.
Source Files