oauth

README

oauth

OAuth helpers for a web server to authenticate users

Work In Progress

Contributions welcome

Documentation

Index

• Variables
• func DecryptBytes(key *[32]byte, b []byte) ([]byte, error)
• func EncryptBytes(key *[32]byte, b []byte) ([]byte, error)
• func NewKey() (*[32]byte, error)
• type Handler
  • func (h *Handler) Cookie(r *http.Request) ([]byte, error)
  • func (h *Handler) GetUserInfo(tok *oauth2.Token) (*Profile, error)
  • func (h *Handler) HandleLogin(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) HandleLogoff(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) HandleRedirect(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) SetCookie(w http.ResponseWriter, in []byte)
• type Profile

Variables

var (
	ErrCookieExpired = errors.New("cookie expired")
	ErrCookieDomain  = errors.New("cookie used for wrong domain")
	ErrInvalidCipher = errors.New("Invalid Cipher: could not decrypt bytes provided")
)

Functions

func DecryptBytes

func DecryptBytes(key *[32]byte, b []byte) ([]byte, error)

func EncryptBytes

func EncryptBytes(key *[32]byte, b []byte) ([]byte, error)

func NewKey

func NewKey() (*[32]byte, error)

Types

type Handler

type Handler struct {
	// Config is the oauth2 config including client ID and client secret.
	// Config must be set.
	oauth2.Config

	// StateKey is the key used in the OAuth2 flow to encrypt the state
	// across the redirect. A consistent State key is required across the
	// services executing HandleLogin and the HandleRedirect. This key can
	// be rotated freely as it is only necessary to be consistent accross a
	// single OAuth flow. StateKey must be set.
	//
	// See NewKey to generate new keys of this type and for further
	// documentation.
	StateKey *[32]byte

	// CookieKey is the key used to encrypt and decrypt cookies. A
	// consistent Cookie key is required across the services running
	// HandleRedirect and GetCookie. Rotating this key will log all users
	// out (their cookies will be invalid). CookieKey must be set.
	//
	// See NewKey to generate new keys of this type and for further
	// documentation.
	//
	// TODO: providing an option of a slice of keys here for decryption
	// will allow for a seamless rotation to occur across MaxAge.
	CookieKey *[32]byte

	// Domain is the fully qualified domain name that the cookies will be
	// restricted to. Cookies from other domains will not normally be sent
	// by browsers. This field is used to make sure on the server side that
	// cookies are not reused across domains. This is important if you are
	// using this package for a service for multiple domains. Domain must
	// be set.
	Domain string

	// CookieName is the name to be given to the session cookie when it is
	// set in the user's browser. Defaults to "session".
	CookieName string

	// Service (e.g. microsoft, google, etc) is prepended to the subject ID
	// of the oauth user and the result is used as the preencrypted cookie
	// payload. This allows for a more straightforward migration from a
	// single OAuth provider to multiple OAuth providers by keeping the ID
	// spaces clearly dilineated and ensuring uniqueness. The composite ID
	// is also given in the Profile info to WriteProfile. Service must be
	// set.
	Service string

	// UserInfo is the URL with which to look up user profile information.
	//
	// e.g. "https://openidconnect.googleapis.com/v1/userinfo"
	//
	// UserInfo must be set
	UserInfo string

	// WriteProfile is an optional callback function to upload profile
	// information from authenticated users to a database for use in
	// authorization. See the Profile type for more information. Defaults
	// to a no-op.
	WriteProfile func(http.ResponseWriter, *Profile) error

	// FinalizeLogin defaults to http.Redirect(w, r, "/", 307) and is
	// called after the redirect is complete and cookie is issued.
	FinalizeLogin http.HandlerFunc

	// ACL is an optional access control list function. Return an error if
	// the user is not allowed. By default all users are allowed.
	ACL func(*Profile) error

	// Log is an optional logger for debugging. Defaults to a no-op logger.
	Log *log.Logger
}

func (*Handler) Cookie

func (h *Handler) Cookie(r *http.Request) ([]byte, error)

func (*Handler) GetUserInfo

func (h *Handler) GetUserInfo(tok *oauth2.Token) (*Profile, error)

func (*Handler) HandleLogin

func (h *Handler) HandleLogin(w http.ResponseWriter, r *http.Request)

HandleLogin will redirect the user to Google's consent page to ask for permission for the scopes specified in the Handler Config.

Use this when the user is not authenticated and the current GET request requires authorization. For POSTS you should just fail and expect the user to log on before posting.

func (*Handler) HandleLogoff

func (h *Handler) HandleLogoff(w http.ResponseWriter, r *http.Request)

HandleLogoff will invalidate the cookie in the user's browser.

func (*Handler) HandleRedirect

func (h *Handler) HandleRedirect(w http.ResponseWriter, r *http.Request)

HandleRedirect gets the redirect from Google OAuth with the authorization codes, retrieves the scopes from the identity provider, issues a cookie, and redirects to the original URL.

func (*Handler) SetCookie

func (h *Handler) SetCookie(w http.ResponseWriter, in []byte)

type Profile

type Profile struct {
	ID            string `json:"-"`
	Sub           string `json:"sub"`
	Name          string `json:"name"`
	GivenName     string `json:"given_name"`
	FamilyName    string `json:"family_name"`
	Profile       string `json:"profile"`
	Picture       string `json:"picture"`
	Email         string `json:"email"`
	EmailVerified bool   `json:"email_verified"`
	Gender        string `json:"gender"`
	Locale        string `json:"locale"`
}