oauth2

Documentation

Overview

Package oauth2 implements an oAuth 2 client.

When possible, users should opt to use the provider specific packages in gnd.la/social rather than using this package directly, since they build on top on this one and provide more provider-specific functionality.

Index

• Constants
• func Handler(handler OAuth2TokenHandler, client *Client, scopes []string) app.Handler
• type Client
  • func New(authorization string, exchange string) *Client
  • func (c *Client) Authorization(redirectURI string, scopes []string, state string) string
  • func (c *Client) Clone(ctx httpclient.Context) *Client
  • func (c *Client) Exchange(redirectURI string, code string) (*Token, error)
  • func (c *Client) Get(u string, form url.Values, accessToken string) (*httpclient.Response, error)
  • func (c *Client) Parse(s string) error
  • func (c *Client) Post(u string, form url.Values, accessToken string) (*httpclient.Response, error)
• type OAuth2TokenHandler
• type Token
  • func NewToken(r *httpclient.Response) (*Token, error)
  • func ParseJSONToken(r io.Reader) (*Token, error)
  • func ParseToken(r io.Reader) (*Token, error)
• type TokenType

Constants

const (
	// Code is the GET parameter name where the oAuth 2 provider
	// returns the oAuth 2 code.
	Code = "code"
	// State is the GET parameter name where the oAuth 2 provider
	// returns the state sent in the authorization step.
	State = "state"
)

Functions

func Handler

func Handler(handler OAuth2TokenHandler, client *Client, scopes []string) app.Handler

Handler returns an app.Handler from the given OAuth2TokenHandler, client and scopes.

Types

type Client

type Client struct {
	// Id is the application ID, obtained from the oAuth 2 provider.
	Id string
	// Secret is the application secret, obtained from the oAuth 2
	// provider.
	Secret string
	// AuthorizationURL is the URL for redirecting a user to perform client
	// authorization.
	AuthorizationURL string
	// AuthorizationParameters lists additional parameters
	// to be sent to AuthorizationURL when requesting authorization
	// from a user.
	AuthorizationParameters map[string]string
	// ExchangeURL is the URL for exchanging an oAuth 2
	// code for a token.
	ExchangeURL string
	// ExchangeParameters lists additional parameters to be sent
	// to ExchangeURL when exchanging a code for a token.
	ExchangeParameters map[string]string
	// HTTPClient is the underlying HTTP client used by this
	// oAuth 2 Client. It doesn't need to be explicitely
	// initialized, it will be automatically set up on the
	// first HTTP request.
	HTTPClient *httpclient.Client
	// ResponseHasError is used to check if an *httpclient.Response
	// from the provider represents an error. If this field is
	// nil, responses with non 2xx codes will be considered errors.
	ResponseHasError func(*httpclient.Response) bool
	// DecodeError is used to decode an error from an *httpclient.Response
	// which has been determined to contain an error. If this field is
	// nil, the entire response body will be returned as an error using
	// errors.New.
	DecodeError func(*httpclient.Response) error
	// ScopeSeparator indicates the string used to separate scopes. If
	// empty, it defaults to ",". Note that some provides use ","
	// (e.g. Facebook), while others use an space " " (e.g. Google).
	ScopeSeparator string
}

Client represents an oAuth 2 client. Use New to initialize a *Client.

func New

func New(authorization string, exchange string) *Client

New returns a new oAuth 2 Client. The authorization parameter must be the URL for redirecting a user to perform client authorization. Exchange is the URL for exchanging an oAuth 2 code for a token.

func (*Client) Authorization

func (c *Client) Authorization(redirectURI string, scopes []string, state string) string

Authorization returns the URL for requesting authorization from the user. Note that most providers require redirectURI to be registered with them.

func (*Client) Clone

func (c *Client) Clone(ctx httpclient.Context) *Client

Clone returns a copy of the Client which uses the given context.

func (*Client) Exchange

func (c *Client) Exchange(redirectURI string, code string) (*Token, error)

Exchange exchanges the given code for a *Token. Note that redirectURI must match the value used in Authorization().

func (*Client) Get

func (c *Client) Get(u string, form url.Values, accessToken string) (*httpclient.Response, error)

Get sends an oAuth 2 GET request.

func (*Client) Parse

func (c *Client) Parse(s string) error

func (*Client) Post

func (c *Client) Post(u string, form url.Values, accessToken string) (*httpclient.Response, error)

Get sends an oAuth 2 POST request.

type OAuth2TokenHandler

type OAuth2TokenHandler func(ctx *app.Context, client *Client, token *Token)

OAuth2TokenHandler is a handler type which receives a *Client and a *Token in addition to the *app.Context. An OAuth2TokenHandler must be wrapped via Handler before adding it to an app.

type Token

type Token struct {
	// Key is the token value.
	Key string
	// Scopes contains the scopes granted by the user. Note that
	// not all providers return this information.
	Scopes []string
	// Refresh is used by Google tokens to obtain a new fresh
	// token from an expired one.
	Refresh string
	// Type is the token type. Currently, this is always
	// TokenTypeBearer.
	Type TokenType
	// Expires indicates when the token expires. If this field is
	// the zero time, it indicates that the provider did not provide
	// an expiration. If the expiration time returned by the provider
	// is the string "0" (as e.g. Facebook does), it's interpreted as
	// a non-expiring token and its expiration is set 100 years into
	// the future.
	Expires time.Time
}

Token represents an oAuth 2 token. Note that not all oAuth 2 providers use all the fields.

func NewToken

func NewToken(r *httpclient.Response) (*Token, error)

NewToken returns a Token from an httpclient.Response. Note that this function supports both JSON encoded tokens and query string encoded ones. It uses the response Content-Type to decide which parsing strategy to use.

func ParseJSONToken

func ParseJSONToken(r io.Reader) (*Token, error)

ParseJSONToken parses an oAuth 2 token from its JSON representation. See also ParseToken.

func ParseToken

func ParseToken(r io.Reader) (*Token, error)

ParseToken parses an oAuth 2 token from a query string. See also NewToken and ParseJSONToken.

type TokenType

type TokenType int

TokenType indicates the type of oAuth 2 token. At this time, only bearer tokens are supported.

const (
	// TokenTypeBearer represents a token of type bearer.
	TokenTypeBearer TokenType = iota
)