oauth2http

README

go-oauth2http

Update 2015-06-30: this project now builds and works again, but conventions around Go development are moving fast around here. It's likely this project does this all wrong (I now question the need for the Gorilla deps, for example).

Go library for easily adding required oauth2 resources.

Design goal is to be simple to configure, modular, easy to add, and work with just net/http.

See http://godoc.org/github.com/jtolds/go-oauth2http

Also see the examples at: https://github.com/jtolds/go-oauth2http/blob/master/examples/group/main.go https://github.com/jtolds/go-oauth2http/blob/master/examples/one/main.go

Contrast to https://github.com/GoIncremental/negroni-oauth2, which requires negroni.

Since this package uses github.com/gorilla/sessions (and therefore, github.com/gorilla/context), make sure to use context.ClearHandler or similar.

Documentation

Overview

go-oauth2http

Go library for easily adding required oauth2 resources.

Design goal is to be simple to configure, modular, easy to add, and work with just net/http.

See the examples at: https://github.com/jtolds/go-oauth2http/blob/master/examples/group/main.go https://github.com/jtolds/go-oauth2http/blob/master/examples/one/main.go

Since this package uses github.com/gorilla/sessions (and therefore, github.com/gorilla/context), make sure to use context.ClearHandler or similar.

Index

• type Provider
  • func Facebook(conf oauth2.Config) *Provider
  • func Github(conf oauth2.Config) *Provider
  • func Google(conf oauth2.Config) *Provider
  • func LinkedIn(conf oauth2.Config) *Provider
• type ProviderGroup
  • func NewProviderGroup(store sessions.Store, session_namespace string, group_base_url string, ...) (*ProviderGroup, error)
  • func (g *ProviderGroup) Handler(provider_name string) (rv *ProviderHandler, exists bool)
  • func (g *ProviderGroup) LoggedIn(r *http.Request) (bool, error)
  • func (g *ProviderGroup) LoginRequired(h http.Handler, login_redirect func(redirect_to string) (url string)) http.Handler
  • func (g *ProviderGroup) LoginURL(provider_name, redirect_to string, force_prompt bool) string
  • func (g *ProviderGroup) LogoutAll(w http.ResponseWriter, r *http.Request) error
  • func (g *ProviderGroup) LogoutAllURL(redirect_to string) string
  • func (g *ProviderGroup) LogoutURL(provider_name, redirect_to string) string
  • func (g *ProviderGroup) Providers() map[string]*ProviderHandler
  • func (g *ProviderGroup) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (g *ProviderGroup) Tokens(r *http.Request) (map[string]*oauth2.Token, error)
• type ProviderHandler
  • func NewProviderHandler(provider *Provider, store SessionGetter, handler_base_url string, ...) *ProviderHandler
  • func (o *ProviderHandler) LoggedIn(r *http.Request) (bool, error)
  • func (o *ProviderHandler) LoginRequired(h http.Handler) http.Handler
  • func (o *ProviderHandler) LoginURL(redirect_to string, force_prompt bool) string
  • func (o *ProviderHandler) Logout(w http.ResponseWriter, r *http.Request) error
  • func (o *ProviderHandler) LogoutURL(redirect_to string) string
  • func (o *ProviderHandler) Session(r *http.Request) (*sessions.Session, error)
  • func (o *ProviderHandler) Token(r *http.Request) (*oauth2.Token, error)
• type RedirectURLs
• type SessionGetter
  • func SessionFromStore(store sessions.Store, session_namespace string) SessionGetter

Types

type Provider

type Provider struct {
	Name string
	oauth2.Config
}

Provider is a named *oauth2.Config

func Facebook

func Facebook(conf oauth2.Config) *Provider

func Github

func Github(conf oauth2.Config) *Provider

func Google

func Google(conf oauth2.Config) *Provider

func LinkedIn

func LinkedIn(conf oauth2.Config) *Provider

type ProviderGroup

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

ProviderGroup is an http.Handler that keeps track of authentication for multiple OAuth2 providers.

Assuming OAuth2 providers have been configured for Facebook, Google, LinkedIn, and Github, ProviderGroup handles requests to the following paths:

• /all/logout
• /facebook/login
• /facebook/logout
• /facebook/_cb
• /google/login
• /google/logout
• /google/_cb
• /linkedin/login
• /linkedin/logout
• /linkedin/_cb
• /github/login
• /github/logout
• /github/_cb

ProviderGroup will also return associated state to you about each OAuth2 provider's state, in addition to a LoginRequired middleware and a Login URL generator.

func NewProviderGroup

func NewProviderGroup(store sessions.Store, session_namespace string,
	group_base_url string, urls RedirectURLs,
	providers ...*Provider) (*ProviderGroup, error)

NewProviderGroup makes a provider group. Requires a configured Gorilla session store, a session namespace (will be prepended to ":"+provider_name), the base URL of the ProviderGroup's http.Handler, a collection of URLs for redirecting, and a list of specific configured providers.

func (*ProviderGroup) Handler

func (g *ProviderGroup) Handler(provider_name string) (rv *ProviderHandler,
	exists bool)

Handler returns a specific ProviderHandler given the Provider name

func (*ProviderGroup) LoggedIn

func (g *ProviderGroup) LoggedIn(r *http.Request) (bool, error)

LoggedIn returns true if the user is logged in with any provider

func (*ProviderGroup) LoginRequired

func (g *ProviderGroup) LoginRequired(h http.Handler,
	login_redirect func(redirect_to string) (url string)) http.Handler

LoginRequired is a middleware for redirecting users to a login page if they aren't logged in yet. login_redirect should take the URL to redirect to after logging in and return a URL that will actually do the logging in. If you already know which provider a user should use, consider using (*ProviderHandler).LoginRequired instead, which doesn't require a login_redirect URL.

func (*ProviderGroup) LoginURL

func (g *ProviderGroup) LoginURL(provider_name, redirect_to string,
	force_prompt bool) string

LoginURL returns the login URL for a given provider. redirect_to is the URL to navigate to after logging in, and force_prompt tells OAuth2 whether or not the login prompt should always be shown regardless of if the user is already logged in.

func (*ProviderGroup) LogoutAll

func (g *ProviderGroup) LogoutAll(w http.ResponseWriter, r *http.Request) error

LogoutAll will not return any HTTP response, but will simply prepare a response for logging a user out completely from all providers. If a user should log out of just a specific OAuth2 provider, use the Logout method on the associated ProviderHandler.

func (*ProviderGroup) LogoutAllURL

func (g *ProviderGroup) LogoutAllURL(redirect_to string) string

LogoutAllURL returns the logout URL for all providers. redirect_to is the URL to navigate to after logging out.

func (*ProviderGroup) LogoutURL

func (g *ProviderGroup) LogoutURL(provider_name, redirect_to string) string

LogoutURL returns the logout URL for a given provider. redirect_to is the URL to navigate to after logging out.

func (*ProviderGroup) Providers

func (g *ProviderGroup) Providers() map[string]*ProviderHandler

Tokens will return a map of all the currently valid OAuth2 tokens

func (*ProviderGroup) ServeHTTP

func (g *ProviderGroup) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler

func (*ProviderGroup) Tokens

func (g *ProviderGroup) Tokens(r *http.Request) (map[string]*oauth2.Token,
	error)

Tokens will return a map of all the currently valid OAuth2 tokens

type ProviderHandler

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

ProviderHandler is an http.Handler that keeps track of authentication for a single OAuth2 provider

ProviderHandler handles requests to the following paths:

• /login
• /logout
• /_cb

ProviderHandler will also return associated state to you about its state, in addition to a LoginRequired middleware and a Login URL generator.

func NewProviderHandler

func NewProviderHandler(provider *Provider, store SessionGetter,
	handler_base_url string, urls RedirectURLs) *ProviderHandler

NewProviderHandler makes a provider handler. Requres a provider configuration, a session store, a base URL for the handler, and a collection of URLs for redirecting.

func (*ProviderHandler) LoggedIn

func (o *ProviderHandler) LoggedIn(r *http.Request) (bool, error)

LoggedIn returns true if the user is logged in with this provider

func (*ProviderHandler) LoginRequired

func (o *ProviderHandler) LoginRequired(h http.Handler) http.Handler

LoginRequired is a middleware for redirecting users to a login page if they aren't logged in yet. If you are using a ProviderGroup and don't know which provider a user should use, consider using (*ProviderGroup).LoginRequired instead

func (*ProviderHandler) LoginURL

func (o *ProviderHandler) LoginURL(redirect_to string,
	force_prompt bool) string

LoginURL returns the login URL for this provider redirect_to is the URL to navigate to after logging in, and force_prompt tells OAuth2 whether or not the login prompt should always be shown regardless of if the user is already logged in.

func (*ProviderHandler) Logout

func (o *ProviderHandler) Logout(w http.ResponseWriter, r *http.Request) error

Logout prepares the request to log the user out of just this OAuth2 provider. If you're using a ProviderGroup you may be interested in LogoutAll.

func (*ProviderHandler) LogoutURL

func (o *ProviderHandler) LogoutURL(redirect_to string) string

LogoutURL returns the logout URL for this provider redirect_to is the URL to navigate to after logging out.

func (*ProviderHandler) Session

func (o *ProviderHandler) Session(r *http.Request) (*sessions.Session, error)

Session returns a provider-specific authenticated session for the current user. This session is cleared whenever a user logs out.

func (*ProviderHandler) Token

func (o *ProviderHandler) Token(r *http.Request) (*oauth2.Token, error)

Token returns a token if the provider is currently logged in, or nil if not.

type RedirectURLs

type RedirectURLs struct {
	// ErrorURL should return a URL for an error given an HTTP status code
	// and an error message
	ErrorURL func(code int, msg string) string

	// If a login URL isn't provided to redirect to after successful login, use
	// this one.
	DefaultLoginURL string

	// If a logout URL isn't provided to redirect to after successful logout, use
	// this one.
	DefaultLogoutURL string
}

RedirectURLs contains a collection of URLs to redirect to in a variety of cases

type SessionGetter

type SessionGetter func(r *http.Request) (*sessions.Session, error)

func SessionFromStore

func SessionFromStore(store sessions.Store,
	session_namespace string) SessionGetter

SessionFromStore returns a SessionGetter given a constant session store and a session namespace