gothic

Documentation

Overview

Package gothic wraps common behaviour when using Goth. This makes it quick, and easy, to get up and running with Goth. Of course, if you want complete control over how things flow, in regard to the authentication process, feel free and use Goth directly.

See https://github.com/bupd/goth/blob/master/examples/main.go to see this in action.

Index

• Constants
• Variables
• func BeginAuthHandler(res http.ResponseWriter, req *http.Request)
• func GetAuthURL(res http.ResponseWriter, req *http.Request) (string, error)
• func GetContextWithProvider(req *http.Request, provider string) *http.Request
• func GetFromSession(key string, req *http.Request) (string, error)
• func Logout(res http.ResponseWriter, req *http.Request) error
• func StoreInSession(key string, value string, req *http.Request, res http.ResponseWriter) error

Constants

const ProviderParamKey key = iota

ProviderParamKey can be used as a key in context when passing in a provider

const SessionName = "_gothic_session"

SessionName is the key used to access the session store.

Variables

var CompleteUserAuth = func(res http.ResponseWriter, req *http.Request) (goth.User, error) {
	if !keySet && defaultStore == Store {
		fmt.Println("goth/gothic: no SESSION_SECRET environment variable is set. The default cookie store is not available and any calls will fail. Ignore this warning if you are using a different store.")
	}

	providerName, err := GetProviderName(req)
	if err != nil {
		return goth.User{}, err
	}

	provider, err := goth.GetProvider(providerName)
	if err != nil {
		return goth.User{}, err
	}

	value, err := GetFromSession(providerName, req)
	if err != nil {
		return goth.User{}, err
	}
	defer Logout(res, req)
	sess, err := provider.UnmarshalSession(value)
	if err != nil {
		return goth.User{}, err
	}

	err = validateState(req, sess)
	if err != nil {
		return goth.User{}, err
	}

	user, err := provider.FetchUser(sess)
	if err == nil {

		return user, err
	}

	params := req.URL.Query()
	if params.Encode() == "" && req.Method == "POST" {
		req.ParseForm()
		params = req.Form
	}

	_, err = sess.Authorize(provider, params)
	if err != nil {
		return goth.User{}, err
	}

	err = StoreInSession(providerName, sess.Marshal(), req, res)

	if err != nil {
		return goth.User{}, err
	}

	gu, err := provider.FetchUser(sess)
	return gu, err
}

CompleteUserAuth does what it says on the tin. It completes the authentication process and fetches all the basic information about the user from the provider.

It expects to be able to get the name of the provider from the query parameters as either "provider" or ":provider".

See https://github.com/bupd/goth/blob/master/examples/main.go to see this in action.

var GetProviderName = getProviderName

GetProviderName is a function used to get the name of a provider for a given request. By default, this provider is fetched from the URL query string. If you provide it in a different way, assign your own function to this variable that returns the provider name for your request.

var GetState = func(req *http.Request) string {
	params := req.URL.Query()
	if params.Encode() == "" && req.Method == http.MethodPost {
		return req.FormValue("state")
	}
	return params.Get("state")
}

GetState gets the state returned by the provider during the callback. This is used to prevent CSRF attacks, see http://tools.ietf.org/html/rfc6749#section-10.12

var SetState = func(req *http.Request) string {
	state := req.URL.Query().Get("state")
	if len(state) > 0 {
		return state
	}

	nonceBytes := make([]byte, 64)
	_, err := io.ReadFull(rand.Reader, nonceBytes)
	if err != nil {
		panic("gothic: source of randomness unavailable: " + err.Error())
	}
	return base64.URLEncoding.EncodeToString(nonceBytes)
}

SetState sets the state string associated with the given request. If no state string is associated with the request, one will be generated. This state is sent to the provider and can be retrieved during the callback.

var Store sessions.Store

Store can/should be set by applications using gothic. The default is a cookie store.

Functions

func BeginAuthHandler

func BeginAuthHandler(res http.ResponseWriter, req *http.Request)

BeginAuthHandler is a convenience handler for starting the authentication process. It expects to be able to get the name of the provider from the query parameters as either "provider" or ":provider".

BeginAuthHandler will redirect the user to the appropriate authentication end-point for the requested provider.

See https://github.com/bupd/goth/blob/master/examples/main.go to see this in action.

func GetAuthURL

func GetAuthURL(res http.ResponseWriter, req *http.Request) (string, error)

GetAuthURL starts the authentication process with the requested provided. It will return a URL that should be used to send users to.

It expects to be able to get the name of the provider from the query parameters as either "provider" or ":provider".

I would recommend using the BeginAuthHandler instead of doing all of these steps yourself, but that's entirely up to you.

func GetContextWithProvider

func GetContextWithProvider(req *http.Request, provider string) *http.Request

GetContextWithProvider returns a new request context containing the provider

func GetFromSession

func GetFromSession(key string, req *http.Request) (string, error)

GetFromSession retrieves a previously-stored value from the session. If no value has previously been stored at the specified key, it will return an error.

func Logout

func Logout(res http.ResponseWriter, req *http.Request) error

Logout invalidates a user session.

func StoreInSession

func StoreInSession(key string, value string, req *http.Request, res http.ResponseWriter) error

StoreInSession stores a specified key/value pair in the session.