goth

README

Goth: Multi-Provider Authentication for Go

Package goth provides a simple, clean, and idiomatic way to write authentication packages for Go web applications.

Unlike other similar packages, Goth, lets you write OAuth, OAuth2, or any other protocol providers, as long as they implement the Provider and Session interfaces.

This package was inspired by https://github.com/intridea/omniauth.

Installation

$ go get github.com/Ticket-Service/auth

Supported Providers

• Amazon
• Apple
• Auth0
• Azure AD
• Battle.net
• Bitbucket
• Box
• Cloud Foundry
• Dailymotion
• Deezer
• DigitalOcean
• Discord
• Dropbox
• Eve Online
• Facebook
• Fitbit
• Gitea
• GitHub
• Gitlab
• Google
• Google+ (deprecated)
• Heroku
• InfluxCloud
• Instagram
• Intercom
• Kakao
• Lastfm
• LINE
• Linkedin
• Mailru
• Meetup
• MicrosoftOnline
• Naver
• Nextcloud
• Okta
• OneDrive
• OpenID Connect (auto discovery)
• Oura
• Patreon
• Paypal
• SalesForce
• Shopify
• Slack
• Soundcloud
• Spotify
• Steam
• Strava
• Stripe
• TikTok
• Tumblr
• Twitch
• Twitter
• Typetalk
• Uber
• VK
• WeCom
• Wepay
• Xero
• Yahoo
• Yammer
• Yandex
• Zoom

Examples

See the examples folder for a working application that lets users authenticate through Twitter, Facebook, Google Plus etc.

To run the example either clone the source from GitHub

$ git clone git@github.com:markbates/goth.git

or use

$ go get github.com/Ticket-Service/auth

$ cd goth/examples
$ go get -v
$ go build
$ ./examples

Now open up your browser and go to http://localhost:3000 to see the example.

To actually use the different providers, please make sure you set environment variables. Example given in the examples/main.go file

Security Notes

By default, gothic uses a CookieStore from the gorilla/sessions package to store session data.

As configured, this default store (gothic.Store) will generate cookies with Options:

&Options{
   Path:   "/",
   Domain: "",
   MaxAge: 86400 * 30,
   HttpOnly: true,
   Secure: false,
 }

To tailor these fields for your application, you can override the gothic.Store variable at startup.

The following snippet shows one way to do this:

key := ""             // Replace with your SESSION_SECRET or similar
maxAge := 86400 * 30  // 30 days
isProd := false       // Set to true when serving over https

store := sessions.NewCookieStore([]byte(key))
store.MaxAge(maxAge)
store.Options.Path = "/"
store.Options.HttpOnly = true   // HttpOnly should always be enabled
store.Options.Secure = isProd

gothic.Store = store

Issues

Issues always stand a significantly better chance of getting fixed if they are accompanied by a pull request.

Contributing

Would I love to see more providers? Certainly! Would you love to contribute one? Hopefully, yes!

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Write Tests!
4. Make sure the codebase adhere to the Go coding standards by executing gofmt -s -w ./
5. Commit your changes (git commit -am 'Add some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create new Pull Request

Documentation

Overview

Package goth provides a simple, clean, and idiomatic way to write authentication packages for Go web applications.

This package was inspired by https://github.com/intridea/omniauth.

See the examples folder for a working application that lets users authenticate through Twitter or Facebook.

Index

• Constants
• func ClearProviders()
• func ContextForClient(h *http.Client) context.Context
• func HTTPClientWithFallBack(h *http.Client) *http.Client
• func UseProviders(viders ...Provider)
• type Params
• type Provider
  • func GetProvider(name string) (Provider, error)
• type Providers
  • func GetProviders() Providers
• type Session
• type User

Constants

const NoAuthUrlErrorMessage = "an AuthURL has not been set"

Functions

func ClearProviders

func ClearProviders()

ClearProviders will remove all providers currently in use. This is useful, mostly, for testing purposes.

func ContextForClient

func ContextForClient(h *http.Client) context.Context

ContextForClient provides a context for use with oauth2.

func HTTPClientWithFallBack

func HTTPClientWithFallBack(h *http.Client) *http.Client

HTTPClientWithFallBack to be used in all fetch operations.

func UseProviders

func UseProviders(viders ...Provider)

UseProviders adds a list of available providers for use with Goth. Can be called multiple times. If you pass the same provider more than once, the last will be used.

Types

type Params

type Params interface {
	Get(string) string
}

Params is used to pass data to sessions for authorization. An existing implementation, and the one most likely to be used, is `url.Values`.

type Provider

type Provider interface {
	Name() string
	SetName(name string)
	BeginAuth(state string) (Session, error)
	UnmarshalSession(string) (Session, error)
	FetchUser(Session) (User, error)
	Debug(bool)
	RefreshToken(refreshToken string) (*oauth2.Token, error) // Get new access token based on the refresh token
	RefreshTokenAvailable() bool                             // Refresh token is provided by auth provider or not
}

Provider needs to be implemented for each 3rd party authentication provider e.g. Facebook, Twitter, etc...

func GetProvider

func GetProvider(name string) (Provider, error)

GetProvider returns a previously created provider. If Goth has not been told to use the named provider it will return an error.

type Providers

type Providers map[string]Provider

Providers is list of known/available providers.

func GetProviders

func GetProviders() Providers

GetProviders returns a list of all the providers currently in use.

type Session

type Session interface {
	// GetAuthURL returns the URL for the authentication end-point for the provider.
	GetAuthURL() (string, error)
	// Marshal generates a string representation of the Session for storing between requests.
	Marshal() string
	// Authorize should validate the data from the provider and return an access token
	// that can be stored for later access to the provider.
	Authorize(Provider, Params) (string, error)
}

Session needs to be implemented as part of the provider package. It will be marshaled and persisted between requests to "tie" the start and the end of the authorization process with a 3rd party provider.

type User

type User struct {
	RawData           map[string]interface{}
	Provider          string
	Email             string
	Name              string
	FirstName         string
	LastName          string
	NickName          string
	Description       string
	UserID            string
	AvatarURL         string
	Location          string
	AccessToken       string
	AccessTokenSecret string
	RefreshToken      string
	ExpiresAt         time.Time
	IDToken           string
}

User contains the information common amongst most OAuth and OAuth2 providers. All the "raw" data from the provider can be found in the `RawData` field.