README

Goth: Multi-Provider Authentication for Go GoDoc Build Status Go Report Card

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/markbates/goth

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
  • Linkedin
  • LINE
  • Mailru
  • Meetup
  • MicrosoftOnline
  • Naver
  • Nextcloud
  • Okta
  • OneDrive
  • OpenID Connect (auto discovery)
  • Oura
  • Paypal
  • SalesForce
  • Shopify
  • Slack
  • Soundcloud
  • Spotify
  • Steam
  • Strava
  • Stripe
  • Tumblr
  • Twitch
  • Twitter
  • Typetalk
  • Uber
  • VK
  • Wepay
  • Xero
  • Yahoo
  • Yammer
  • Yandex

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/markbates/goth
$ 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
Expand ▾ Collapse ▴

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

    View Source
    const NoAuthUrlErrorMessage = "an AuthURL has not been set"

    Variables

    This section is empty.

    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 of the "raw" datafrom the provider can be found in the `RawData` field.

                          Directories

                          Path Synopsis
                          Package gothic wraps common behaviour when using Goth.
                          Package gothic wraps common behaviour when using Goth.
                          providers
                          amazon
                          Package amazon implements the OAuth2 protocol for authenticating users through amazon.
                          Package amazon implements the OAuth2 protocol for authenticating users through amazon.
                          apple
                          Package `apple` implements the OAuth2 protocol for authenticating users through Apple.
                          Package `apple` implements the OAuth2 protocol for authenticating users through Apple.
                          auth0
                          Package auth0 implements the OAuth2 protocol for authenticating users through uber.
                          Package auth0 implements the OAuth2 protocol for authenticating users through uber.
                          azuread
                          Package azuread implements the OAuth2 protocol for authenticating users through AzureAD.
                          Package azuread implements the OAuth2 protocol for authenticating users through AzureAD.
                          battlenet
                          Package battlenet implements the OAuth2 protocol for authenticating users through Battle.net.
                          Package battlenet implements the OAuth2 protocol for authenticating users through Battle.net.
                          bitbucket
                          Package bitbucket implements the OAuth2 protocol for authenticating users through Bitbucket.
                          Package bitbucket implements the OAuth2 protocol for authenticating users through Bitbucket.
                          box
                          Package box implements the OAuth2 protocol for authenticating users through box.
                          Package box implements the OAuth2 protocol for authenticating users through box.
                          cloudfoundry
                          Package cloudfoundry implements the OAuth2 protocol for authenticating users through Cloud Foundry.
                          Package cloudfoundry implements the OAuth2 protocol for authenticating users through Cloud Foundry.
                          dailymotion
                          Package dailymotion implements the OAuth2 protocol for authenticating users through Dailymotion.
                          Package dailymotion implements the OAuth2 protocol for authenticating users through Dailymotion.
                          deezer
                          Package deezer implements the OAuth2 protocol for authenticating users through Deezer.
                          Package deezer implements the OAuth2 protocol for authenticating users through Deezer.
                          digitalocean
                          Package digitalocean implements the OAuth2 protocol for authenticating users through Digital Ocean.
                          Package digitalocean implements the OAuth2 protocol for authenticating users through Digital Ocean.
                          discord
                          Package discord implements the OAuth2 protocol for authenticating users through Discord.
                          Package discord implements the OAuth2 protocol for authenticating users through Discord.
                          dropbox
                          Package dropbox implements the OAuth2 protocol for authenticating users through Dropbox.
                          Package dropbox implements the OAuth2 protocol for authenticating users through Dropbox.
                          eveonline
                          Package eveonline implements the OAuth2 protocol for authenticating users through eveonline.
                          Package eveonline implements the OAuth2 protocol for authenticating users through eveonline.
                          facebook
                          Package facebook implements the OAuth2 protocol for authenticating users through Facebook.
                          Package facebook implements the OAuth2 protocol for authenticating users through Facebook.
                          faux
                          Package faux is used exclusively for testing purposes.
                          Package faux is used exclusively for testing purposes.
                          fitbit
                          Package fitbit implements the OAuth protocol for authenticating users through Fitbit.
                          Package fitbit implements the OAuth protocol for authenticating users through Fitbit.
                          gitea
                          Package gitea implements the OAuth2 protocol for authenticating users through gitea.
                          Package gitea implements the OAuth2 protocol for authenticating users through gitea.
                          github
                          Package github implements the OAuth2 protocol for authenticating users through Github.
                          Package github implements the OAuth2 protocol for authenticating users through Github.
                          gitlab
                          Package gitlab implements the OAuth2 protocol for authenticating users through gitlab.
                          Package gitlab implements the OAuth2 protocol for authenticating users through gitlab.
                          google
                          Package google implements the OAuth2 protocol for authenticating users through Google.
                          Package google implements the OAuth2 protocol for authenticating users through Google.
                          gplus
                          Package gplus implements the OAuth2 protocol for authenticating users through Google+.
                          Package gplus implements the OAuth2 protocol for authenticating users through Google+.
                          heroku
                          Package heroku implements the OAuth2 protocol for authenticating users through heroku.
                          Package heroku implements the OAuth2 protocol for authenticating users through heroku.
                          influxcloud
                          Package influxdata implements the OAuth2 protocol for authenticating users through InfluxCloud.
                          Package influxdata implements the OAuth2 protocol for authenticating users through InfluxCloud.
                          instagram
                          Package instagram implements the OAuth2 protocol for authenticating users through Instagram.
                          Package instagram implements the OAuth2 protocol for authenticating users through Instagram.
                          intercom
                          Package intercom implements the OAuth protocol for authenticating users through Intercom.
                          Package intercom implements the OAuth protocol for authenticating users through Intercom.
                          kakao
                          Package kakao implements the OAuth2 protocol for authenticating users through kakao.
                          Package kakao implements the OAuth2 protocol for authenticating users through kakao.
                          lastfm
                          Package lastfm implements the OAuth protocol for authenticating users through LastFM.
                          Package lastfm implements the OAuth protocol for authenticating users through LastFM.
                          line
                          Package line implements the OAuth2 protocol for authenticating users through line.
                          Package line implements the OAuth2 protocol for authenticating users through line.
                          linkedin
                          Package linkedin implements the OAuth2 protocol for authenticating users through Linkedin.
                          Package linkedin implements the OAuth2 protocol for authenticating users through Linkedin.
                          mailru
                          Package mailru implements the OAuth2 protocol for authenticating users through mailru.com.
                          Package mailru implements the OAuth2 protocol for authenticating users through mailru.com.
                          mastodon
                          Package mastodon implements the OAuth2 protocol for authenticating users through Mastodon.
                          Package mastodon implements the OAuth2 protocol for authenticating users through Mastodon.
                          meetup
                          Package meetup implements the OAuth2 protocol for authenticating users through meetup.com .
                          Package meetup implements the OAuth2 protocol for authenticating users through meetup.com .
                          microsoftonline
                          Package microsoftonline implements the OAuth2 protocol for authenticating users through microsoftonline.
                          Package microsoftonline implements the OAuth2 protocol for authenticating users through microsoftonline.
                          nextcloud
                          Package nextcloud implements the OAuth2 protocol for authenticating users through nextcloud.
                          Package nextcloud implements the OAuth2 protocol for authenticating users through nextcloud.
                          okta
                          Package okta implements the OAuth2 protocol for authenticating users through okta.
                          Package okta implements the OAuth2 protocol for authenticating users through okta.
                          onedrive
                          Package onedrive implements the OAuth2 protocol for authenticating users through onedrive.
                          Package onedrive implements the OAuth2 protocol for authenticating users through onedrive.
                          oura
                          Package oura implements the OAuth protocol for authenticating users through Oura API (for OuraRing).
                          Package oura implements the OAuth protocol for authenticating users through Oura API (for OuraRing).
                          paypal
                          Package paypal implements the OAuth2 protocol for authenticating users through paypal.
                          Package paypal implements the OAuth2 protocol for authenticating users through paypal.
                          salesforce
                          Package salesforce implements the OAuth2 protocol for authenticating users through salesforce.
                          Package salesforce implements the OAuth2 protocol for authenticating users through salesforce.
                          shopify
                          Package shopify implements the OAuth2 protocol for authenticating users through Shopify.
                          Package shopify implements the OAuth2 protocol for authenticating users through Shopify.
                          slack
                          Package slack implements the OAuth2 protocol for authenticating users through slack.
                          Package slack implements the OAuth2 protocol for authenticating users through slack.
                          soundcloud
                          Package soundcloud implements the OAuth2 protocol for authenticating users through soundcloud.
                          Package soundcloud implements the OAuth2 protocol for authenticating users through soundcloud.
                          spotify
                          Package spotify implements the OAuth protocol for authenticating users through Spotify.
                          Package spotify implements the OAuth protocol for authenticating users through Spotify.
                          steam
                          Package steam implements the OpenID protocol for authenticating users through Steam.
                          Package steam implements the OpenID protocol for authenticating users through Steam.
                          strava
                          Package strava implements the OAuth2 protocol for authenticating users through Strava.
                          Package strava implements the OAuth2 protocol for authenticating users through Strava.
                          stripe
                          Package stripe implements the OAuth2 protocol for authenticating users through stripe.
                          Package stripe implements the OAuth2 protocol for authenticating users through stripe.
                          tumblr
                          Package tumblr implements the OAuth protocol for authenticating users through Tumblr.
                          Package tumblr implements the OAuth protocol for authenticating users through Tumblr.
                          twitch
                          Package twitch implements the OAuth2 protocol for authenticating users through Twitch.
                          Package twitch implements the OAuth2 protocol for authenticating users through Twitch.
                          twitter
                          Package twitter implements the OAuth protocol for authenticating users through Twitter.
                          Package twitter implements the OAuth protocol for authenticating users through Twitter.
                          typetalk
                          Package typetalk implements the OAuth2 protocol for authenticating users through Typetalk.
                          Package typetalk implements the OAuth2 protocol for authenticating users through Typetalk.
                          uber
                          Package uber implements the OAuth2 protocol for authenticating users through uber.
                          Package uber implements the OAuth2 protocol for authenticating users through uber.
                          vk
                          Package vk implements the OAuth2 protocol for authenticating users through vk.com.
                          Package vk implements the OAuth2 protocol for authenticating users through vk.com.
                          wepay
                          Package wepay implements the OAuth2 protocol for authenticating users through wepay.
                          Package wepay implements the OAuth2 protocol for authenticating users through wepay.
                          xero
                          Package xero implements the OAuth protocol for authenticating users through Xero.
                          Package xero implements the OAuth protocol for authenticating users through Xero.
                          yahoo
                          Package yahoo implements the OAuth2 protocol for authenticating users through yahoo.
                          Package yahoo implements the OAuth2 protocol for authenticating users through yahoo.
                          yammer
                          Package yammer implements the OAuth2 protocol for authenticating users through yammer.
                          Package yammer implements the OAuth2 protocol for authenticating users through yammer.
                          yandex
                          package yandex implements the OAuth2 protocol for authenticating users through Yandex.
                          package yandex implements the OAuth2 protocol for authenticating users through Yandex.