gocialite

README

Gocialite

Copyright

Forked from great repository danilopolani/gocialite which is no longer maintained.

Reason for this fork

Original module is simple and easy to use, but lacks some features, for example, a way to store the dispatcher state permanently, in cookies or in redis store. This repository should fix that. Initially should add support for redis storage.

---

Original Readme

This readme will be updated once permanent storage solution is added to the module

Gocialite is a Socialite inspired package to manage social oAuth authentication without problems. The idea was born when I discovered that Goth is not so flexible: I was using Revel and it was impossible to connect them properly.

Installation

To install it, just run go get gopkg.in/danilopolani/gocialite.v1 and include it in your app: import "gopkg.in/danilopolani/gocialite.v1".

Available drivers

• Amazon
• Asana
• Bitbucket
• Facebook
• Foursquare
• Github
• Google
• LinkedIn
• Slack

Create new driver

Please see Contributing page to learn how to create new driver and test it.

Set scopes

Note: Gocialite set some default scopes for the user profile, for example for Facebook it specify email and for Google profile, email.
When you use the following method, you don't have to rewrite them.

Use the Scopes([]string) method of your Gocial instance. Example:

gocial.Scopes([]string{"public_repo"})

Set driver

Use the Driver(string) method of your Gocial instance. Example:

gocial.Driver("facebook")

The driver name will be the provider name in lowercase.

How to use it

Note: All Gocialite methods are chainable.

Declare a "global" variable outside your main func:

import (
	...
)

var gocial = gocialite.NewDispatcher()

func main() {

Then create a route to use as redirect bridge, for example /auth/github. With this route, the user will be redirected to the provider oAuth login. In this case we use Gin Tonic as router. You have to specify the provider with the Driver() method. Then, with Scopes(), you can set a list of scopes as slice of strings. It's optional.
Finally, with Redirect() you can obtain the redirect URL. In this method you have to pass three parameters:

1. Client ID
2. Client Secret
3. Redirect URL

func main() {
	router := gin.Default()

	router.GET("/auth/github", redirectHandler)

	router.Run("127.0.0.1:9090")
}

// Redirect to correct oAuth URL
func redirectHandler(c *gin.Context) {
	authURL, err := gocial.New().
		Driver("github"). // Set provider
		Scopes([]string{"public_repo"}). // Set optional scope(s)
		Redirect( // 
			"xxxxxxxxxxxxxx", // Client ID
			"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // Client Secret
			"http://localhost:9090/auth/github/callback", // Redirect URL
		)

	// Check for errors (usually driver not valid)
	if err != nil {
		c.Writer.Write([]byte("Error: " + err.Error()))
		return
	}

	// Redirect with authURL
	c.Redirect(http.StatusFound, authURL) // Redirect with 302 HTTP code
}

Now create a callback handler route, where we'll receive the content from the provider.
In order to validate the oAuth and retrieve the data, you have to invoke the Handle() method with two query parameters: state and code. In your URL, they will look like this: http://localhost:9090/auth/github/callback?state=xxxxxxxx&code=xxxxxxxx.
The Handle() method returns the user info, the token and error if there's one or nil.
If there are no errors, in the user variable you will find the logged in user information and in the token one, the token info (it's a oauth2.Token struct). The data of the user - which is a gocialite.User struct - are the following:

• ID
• FirstName
• LastName
• FullName
• Email
• Avatar (URL)
• Raw (the full JSON returned by the provider)

Note that they can be empty.

func main() {
	router := gin.Default()

	router.GET("/auth/github", redirectHandler)
	router.GET("/auth/github/callback", callbackHandler)

	router.Run("127.0.0.1:9090")
}

// Redirect to correct oAuth URL
// Handle callback of provider
func callbackHandler(c *gin.Context) {
	// Retrieve query params for code and state
	code := c.Query("code")
	state := c.Query("state")

	// Handle callback and check for errors
	user, token, err := gocial.Handle(state, code)
	if err != nil {
		c.Writer.Write([]byte("Error: " + err.Error()))
		return
	}

	// Print in terminal user information
	fmt.Printf("%#v", token)
	fmt.Printf("%#v", user)

	// If no errors, show provider name
	c.Writer.Write([]byte("Hi, " + user.FullName))
}

Please take a look to multi provider example for a full working code with Gin Tonic and variable provider handler.

Contributors

• Danilo Polani
• Joseph Buchma
• Mark Beznos
• Davor Kapsa

Documentation

Index

• func Marshal(g *Gocial) ([]byte, error)
• func RegisterNewDriver(driver string, defaultscopes []string, ...)
• type Dispatcher
  • func NewDispatcher(storage GocialStorage) *Dispatcher
  • func (d *Dispatcher) GenerateRedirectURL(sc StateConf) (string, error)
  • func (d *Dispatcher) Handle(state, code string) (*structs.User, *oauth2.Token, error)
  • func (d *Dispatcher) New() *Gocial
  • func (d *Dispatcher) Update(g *Gocial) error
• type Gocial
  • func NewGocial(driver, state string, scopes []string, user structs.User, conf *oauth2.Config, ...) *Gocial
  • func Unmarshal(data []byte) (*Gocial, error)
  • func (g *Gocial) Driver(driver string) *Gocial
  • func (g *Gocial) Equals(g2 *Gocial) bool
  • func (g *Gocial) Handle(state, code string) error
  • func (g *Gocial) Redirect(clientID, clientSecret, redirectURL string) (string, error)
  • func (g *Gocial) Scopes(scopes []string) *Gocial
• type GocialStorage
• type StateConf

Functions

func Marshal

func Marshal(g *Gocial) ([]byte, error)

Marshal marshals Gocial struct to JSON

func RegisterNewDriver

func RegisterNewDriver(driver string, defaultscopes []string, callback func(client *http.Client, u *structs.User), endpoint oauth2.Endpoint, apimap, usermap map[string]string)

RegisterNewDriver adds a new driver to the existing set

Types

type Dispatcher

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

Dispatcher allows to safely issue concurrent Gocials

func NewDispatcher

func NewDispatcher(storage GocialStorage) *Dispatcher

NewDispatcher creates new Dispatcher

func (*Dispatcher) GenerateRedirectURL

func (d *Dispatcher) GenerateRedirectURL(sc StateConf) (string, error)

GenerateRedirectURL creates url for authorization with new state. basically shorthand for New().Driver().Scopes().Redirect()

func (*Dispatcher) Handle

func (d *Dispatcher) Handle(state, code string) (*structs.User, *oauth2.Token, error)

Handle callback. Can be called only once for given state.

func (*Dispatcher) New

func (d *Dispatcher) New() *Gocial

New Gocial instance

func (*Dispatcher) Update

func (d *Dispatcher) Update(g *Gocial) error

Update Gocial instance, should be called after every update on gocial instance

type Gocial

type Gocial struct {
	User  structs.User
	Token *oauth2.Token
	// contains filtered or unexported fields
}

Gocial is the main struct of the package with json tags

func NewGocial

func NewGocial(driver, state string, scopes []string, user structs.User, conf *oauth2.Config, token *oauth2.Token) *Gocial

NewGocial Create Gocial instance from passed arguments

func Unmarshal

func Unmarshal(data []byte) (*Gocial, error)

Unmarshal the JSON to Gocial

func (*Gocial) Driver

func (g *Gocial) Driver(driver string) *Gocial

Driver is needed to choose the correct social

func (*Gocial) Equals

func (g *Gocial) Equals(g2 *Gocial) bool

Equals compares two Gocial instances

func (*Gocial) Handle

func (g *Gocial) Handle(state, code string) error

Handle callback from provider

func (*Gocial) Redirect

func (g *Gocial) Redirect(clientID, clientSecret, redirectURL string) (string, error)

Redirect returns an URL for the selected social oAuth login

func (*Gocial) Scopes

func (g *Gocial) Scopes(scopes []string) *Gocial

Scopes is used to set the oAuth scopes, for example "user", "calendar"

type GocialStorage

type GocialStorage interface {
	Get(key string) (*Gocial, error)
	Set(key string, value *Gocial) error
	Delete(key string) error
}

Interface for structs to provide state saving of Dispatcher

type StateConf

type StateConf struct {
	Driver      string
	ClientID    string
	Secret      string
	RedirectURL string
	Scopes      []string
}