oauth

Documentation

Overview

Package oauth supports making OAuth2-authenticated HTTP requests.

Example usage:

// Specify your configuration. (typically as a global variable)
var config = &oauth.Config{
	ClientId:     YOUR_CLIENT_ID,
	ClientSecret: YOUR_CLIENT_SECRET,
	Scope:        "https://www.googleapis.com/auth/buzz",
	AuthURL:      "https://accounts.google.com/o/oauth2/auth",
	TokenURL:     "https://accounts.google.com/o/oauth2/token",
	RedirectURL:  "http://you.example.org/handler",
}

// A landing page redirects to the OAuth provider to get the auth code.
func landing(w http.ResponseWriter, r *http.Request) {
	http.Redirect(w, r, config.AuthCodeURL("foo"), http.StatusFound)
}

// The user will be redirected back to this handler, that takes the
// "code" query parameter and Exchanges it for an access token.
func handler(w http.ResponseWriter, r *http.Request) {
	t := &oauth.Transport{Config: config}
	t.Exchange(r.FormValue("code"))
	// The Transport now has a valid Token. Create an *http.Client
	// with which we can make authenticated API requests.
	c := t.Client()
	c.Post(...)
	// ...
	// btw, r.FormValue("state") == "foo"
}

Index

• type Cache
• type CacheFile
  • func (f CacheFile) PutToken(tok *Token) error
  • func (f CacheFile) Token() (*Token, error)
• type Config
  • func (c *Config) AuthCodeURL(state string) string
• type OAuthError
  • func (oe OAuthError) Error() string
• type Token
  • func (t *Token) Expired() bool
• type Transport
  • func (t *Transport) AuthenticateClient() error
  • func (t *Transport) Client() *http.Client
  • func (t *Transport) Exchange(code string) (*Token, error)
  • func (t *Transport) Refresh() error
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Types

type Cache

type Cache interface {
	Token() (*Token, error)
	PutToken(*Token) error
}

Cache specifies the methods that implement a Token cache.

type CacheFile

type CacheFile string

CacheFile implements Cache. Its value is the name of the file in which the Token is stored in JSON format.

func (CacheFile) PutToken

func (f CacheFile) PutToken(tok *Token) error

func (CacheFile) Token

func (f CacheFile) Token() (*Token, error)

type Config

type Config struct {
	// ClientId is the OAuth client identifier used when communicating with
	// the configured OAuth provider.
	ClientId string

	// ClientSecret is the OAuth client secret used when communicating with
	// the configured OAuth provider.
	ClientSecret string

	// Scope identifies the level of access being requested. Multiple scope
	// values should be provided as a space-delimited string.
	Scope string

	// AuthURL is the URL the user will be directed to in order to grant
	// access.
	AuthURL string

	// TokenURL is the URL used to retrieve OAuth tokens.
	TokenURL string

	// RedirectURL is the URL to which the user will be returned after
	// granting (or denying) access.
	RedirectURL string

	// TokenCache allows tokens to be cached for subsequent requests.
	TokenCache Cache

	// AccessType is an OAuth extension that gets sent as the
	// "access_type" field in the URL from AuthCodeURL.
	// See https://developers.google.com/accounts/docs/OAuth2WebServer.
	// It may be "online" (the default) or "offline".
	// If your application needs to refresh access tokens when the
	// user is not present at the browser, then use offline. This
	// will result in your application obtaining a refresh token
	// the first time your application exchanges an authorization
	// code for a user.
	AccessType string

	// ApprovalPrompt indicates whether the user should be
	// re-prompted for consent. If set to "auto" (default) the
	// user will be prompted only if they haven't previously
	// granted consent and the code can only be exchanged for an
	// access token.
	// If set to "force" the user will always be prompted, and the
	// code can be exchanged for a refresh token.
	ApprovalPrompt string
}

Config is the configuration of an OAuth consumer.

func (*Config) AuthCodeURL

func (c *Config) AuthCodeURL(state string) string

AuthCodeURL returns a URL that the end-user should be redirected to, so that they may obtain an authorization code.

type OAuthError

type OAuthError struct {
	// contains filtered or unexported fields
}

OAuthError is the error type returned by many operations.

In retrospect it should not exist. Don't depend on it.

func (OAuthError) Error

func (oe OAuthError) Error() string

type Token

type Token struct {
	AccessToken  string
	RefreshToken string
	Expiry       time.Time // If zero the token has no (known) expiry time.

	// Extra optionally contains extra metadata from the server
	// when updating a token. The only current key that may be
	// populated is "id_token". It may be nil and will be
	// initialized as needed.
	Extra map[string]string
}

Token contains an end-user's tokens. This is the data you must store to persist authentication.

func (*Token) Expired

func (t *Token) Expired() bool

Expired reports whether the token has expired or is invalid.

type Transport

type Transport struct {
	*Config
	*Token

	// Transport is the HTTP transport to use when making requests.
	// It will default to http.DefaultTransport if nil.
	// (It should never be an oauth.Transport.)
	Transport http.RoundTripper
	// contains filtered or unexported fields
}

Transport implements http.RoundTripper. When configured with a valid Config and Token it can be used to make authenticated HTTP requests.

	t := &oauth.Transport{config}
     t.Exchange(code)
     // t now contains a valid Token
	r, _, err := t.Client().Get("http://example.org/url/requiring/auth")

It will automatically refresh the Token if it can, updating the supplied Token in place.

func (*Transport) AuthenticateClient

func (t *Transport) AuthenticateClient() error

AuthenticateClient gets an access Token using the client_credentials grant type.

func (*Transport) Client

func (t *Transport) Client() *http.Client

Client returns an *http.Client that makes OAuth-authenticated requests.

func (*Transport) Exchange

func (t *Transport) Exchange(code string) (*Token, error)

Exchange takes a code and gets access Token from the remote server.

func (*Transport) Refresh

func (t *Transport) Refresh() error

Refresh renews the Transport's AccessToken using its RefreshToken.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip executes a single HTTP transaction using the Transport's Token as authorization headers.

This method will attempt to renew the Token if it has expired and may return an error related to that Token renewal before attempting the client request. If the Token cannot be renewed a non-nil os.Error value will be returned. If the Token is invalid callers should expect HTTP-level errors, as indicated by the Response's StatusCode.