ssgo

README

#ssgo

This package aims to make it easy to build web applications in Go that use external sites as their primary user account system.

Currently supported sites:

• github
• reddit

Planned integrations:

• imgur
• twitter
• facebook
• google

Super easy github integration:

import "github.com/captncraig/ssgo/hub"

Make an sso object:

cid, secret := os.Getenv("GH_CLIENT_ID"),os.Getenv("GH_CLIENT_SECRET")
gh = ssgo.NewGithub(cid, secret, "public_repo", "write:repo_hook")

Link the provided http handlers to whatever endpoint you want them to live at:

http.HandleFunc("/login", gh.RedirectToLogin)
http.HandleFunc("/ghauth", gh.ExchangeCodeForToken)

Use the Route helper to direct traffic based on a user's cookie value:

http.HandleFunc("/", gh.Route(loggedOut, loggedIn))

The appropriate handler will be invoked for requests, and if the user is logged in to github, you will receive a populated Credentials struct to your loggedIn handler.

c.Client will give you an http.Client that you can use with go-github to make authenticated requests for that user.

See this example for full working code.

internals:

Internally we store a randomly generated authToken cookie in the browser, which is a key into a boltDb database that stores the accessToken and some basic account info. You can control the db file name with the ssgo.boltdb environment variable if you so choose.

If your application wants to use the same bolt db as the sso system, you can use the helpers in the ssgo package to load or store json to your own bucket.

Documentation

Index

• func EnsureBoltBucketExists(bucket string) error
• func GetDb() *bolt.DB
• func LookupBoltJson(bucket string, key string, v interface{}) error
• func StoreBoltJson(bucket string, key string, data interface{}) error
• type AuthenticatedHandler
• type Credentials
• type SSO
  • func NewGithub(clientId, clientSecret string, scopes ...string) SSO
  • func NewReddit(clientId, clientSecret, redirectUri string, scopes ...string) SSO

Functions

func EnsureBoltBucketExists

func EnsureBoltBucketExists(bucket string) error

func GetDb

func GetDb() *bolt.DB

func LookupBoltJson

func LookupBoltJson(bucket string, key string, v interface{}) error

func StoreBoltJson

func StoreBoltJson(bucket string, key string, data interface{}) error

Types

type AuthenticatedHandler

type AuthenticatedHandler func(w http.ResponseWriter, r *http.Request, credentials *Credentials)

Like an http.HandleFunc, but accepts a credentials object as a third argument.

type Credentials

type Credentials struct {
	// Shortname of site they are authenticated with
	Site string
	// Oauth token for user.
	Token *oauth2.Token
	// Http client with oauth credentials ready to go.
	Client *http.Client
}

Container for a user's oauth credentials

type SSO

type SSO interface {
	//Redirect the request to the provider's authorization page
	RedirectToLogin(w http.ResponseWriter, r *http.Request)
	//Handle callback from authorization page. This needs to be hosted at the url that is registered with the provider.
	ExchangeCodeForToken(w http.ResponseWriter, r *http.Request)
	//Lookup the credentials for a given request from the cookie. Will return nil if no valid cookie is found.
	LookupToken(r *http.Request) *Credentials
	//Basic http handler that looks up the token for you and provides credentials to your handler. Credentials may be nil.
	Handle(handler AuthenticatedHandler) http.HandlerFunc
	//Select a handler based on whether the user has a valid cookie or not.
	Route(loggedOut http.HandlerFunc, loggedIn AuthenticatedHandler) http.HandlerFunc

	ClearCookie(w http.ResponseWriter)
}

Core interface for working with a third-party website

func NewGithub

func NewGithub(clientId, clientSecret string, scopes ...string) SSO

func NewReddit

func NewReddit(clientId, clientSecret, redirectUri string, scopes ...string) SSO