oauth

README

OAuth

This folder contains some tools for doing OAuth and user authentication via Google OAuth.

Documentation

Index

• Variables
• type Callbacks
• type Config
• type Handler
  • func New(config *Config) (*Handler, error)
  • func (h *Handler) AuthenticationMiddleware(requireAuth bool, unauthorizedHandler func(w http.ResponseWriter)) func(http.Handler) http.Handler
  • func (h *Handler) Claims(ctx context.Context) *verifier.StandardClaims
  • func (h *Handler) MustClaims(ctx context.Context) *verifier.StandardClaims
• type TokenManager

Variables

var (
	// ErrNeedMountURL occurs when a mount url is not specified
	ErrNeedMountURL = errors.New("must specify a mount url")
	// ErrNeedClientID occurs when a client id is not specified
	ErrNeedClientID = errors.New("must specify a client id")
	// ErrNeedClientSecret occurs when a client secret is not specified
	ErrNeedClientSecret = errors.New("must specify a client secret")
	// ErrNeedSecretKey occurs when a secret key is not specified
	ErrNeedSecretKey = errors.New("must specify a secret key")
	// ErrInvalidRedirect occurs when we have a non-whitelisted
	// redirect parameter
	ErrInvalidRedirect = errors.New("bad redirect value")
	// ErrInvalidStateValue occurs when we the state returned
	// by the provider fails JWT validation
	ErrInvalidStateValue = errors.New("bad state value")
	// ErrInvalidCodeValue occurs when we the code returned
	// by the provider is blank
	ErrInvalidCodeValue = errors.New("bad code value")
	// ErrInvalidToken occurs when we the token returned after the exchange
	// by the provider is bad
	ErrInvalidToken = errors.New("invalid token")

	// MessageMountURLParsingFailed occurs when we can't parse the URL provided
	// by MountURL
	MessageMountURLParsingFailed = "parsing mount url failed"
	// MessageStateCookieRetrieval occurs when we can't retrieve the state cookie after
	// the redirect from the provider
	MessageStateCookieRetrieval = "failed to get oauth state cookie"
	// MessageExchangeFailed occurs when we can't finish the exchange for the longer lived
	// tokens from the provider
	MessageExchangeFailed = "exchange failed"
	// MessageUserFailed occurs when we can't get information about the user from
	// the provider
	MessageUserFailed = "user retrieval failed"
	// MessageStateGenerationFailed occurs when we can't generate the state cookie for some
	// reason
	MessageStateGenerationFailed = "state generation failed"
	// MessageTokenRejected is displayed when a token handed back from Google has been rejected
	// for some reason, often due to an Audience or Domain mismatch
	MessageTokenRejected = "The token received was rejected, make sure you signed in with the right account."
)

Types

type Callbacks

type Callbacks interface {
	// OnError is invoked when any error is encountered in the handlers
	OnError(w http.ResponseWriter, err error)
	// OnSuccess is invoked when an id token is retrieved for the first
	// time at the end of an OAuth flow
	OnSuccess(w http.ResponseWriter, location, raw string, claims *verifier.StandardClaims)
	// OnInvalidToken is invoked when an id token is determined to be invalid
	// based off of the verification configuration passed into the handler
	OnInvalidToken(w http.ResponseWriter, err error)
	// OnRefresh is invoked when an id token is successfully refreshed
	// in middleware
	OnRefresh(w http.ResponseWriter, raw string) error
}

Callbacks encapsulate the state handling logic when the flow endpoints/middleware either encounter an error, success, or get a refreshed token

type Config

type Config struct {
	// ClientTimeout is the timeout for doing the OAuth token exchange
	// if none is specified, defaults to 10 seconds
	ClientTimeout time.Duration
	// Verifier specifies the JWT verifier for the id token
	Verifier *verifier.Verifier
	// TokenManager manages token storage
	TokenManager TokenManager
	// Callbacks manage the error/success handling of the endpoint
	Callbacks Callbacks
	// AllowedRedirects whitelists where we can redirect to after getting a token
	AllowedRedirects []string
	// Logger is a zerolog instance used for logging
	Logger *zerolog.Logger

	// ClientID is the Google Client ID
	ClientID string
	// ClientSecret is the Google Client Secret
	ClientSecret string
	// MountURL is the URL where this handler is mounted
	MountURL string
	// SecretKey is the secret for JWT generation for state management
	SecretKey string
	// contains filtered or unexported fields
}

Config is a configuration object for OAuth handlers.

type Handler

type Handler struct {
	*http.ServeMux
	// contains filtered or unexported fields
}

Handler handles oauth2 authentication requests.

func New

func New(config *Config) (*Handler, error)

New creates a new handler based on the given config.

func (*Handler) AuthenticationMiddleware

func (h *Handler) AuthenticationMiddleware(requireAuth bool, unauthorizedHandler func(w http.ResponseWriter)) func(http.Handler) http.Handler

AuthenticationMiddleware provides a mechanism for validating tokens passed in Authorization headers

func (*Handler) Claims

func (h *Handler) Claims(ctx context.Context) *verifier.StandardClaims

Claims returns claims if they exist on the context

func (*Handler) MustClaims

func (h *Handler) MustClaims(ctx context.Context) *verifier.StandardClaims

MustClaims panics if no claims exist on the context

type TokenManager

type TokenManager interface {
	Set(ctx context.Context, subject, token string) error
	Get(ctx context.Context, subject string) (string, error)
}

TokenManager maintains state for storing tokens