oauth2

Documentation

Overview

Copyright 2016 Wenhui Shen <www.webx.top>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2016 Wenhui Shen <www.webx.top>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2016 Wenhui Shen <www.webx.top>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• Variables
• func BeginAuthHandler(ctx echo.Context) error
• func GetAuthURL(ctx echo.Context) (string, error)
• type Config
  • func DefaultConfig() Config
  • func (c Config) GenerateProviders(vhost string) (providers []goth.Provider)
  • func (c Config) MergeSingle(cfg Config) (config Config)
• type GothParams
  • func (g GothParams) Get(key string) string
• type OAuth
  • func New(hostURL string, cfg Config) *OAuth
  • func (p *OAuth) Fail(handler echo.HTTPErrorHandler)
  • func (p *OAuth) Success(handlersFn ...interface{})
  • func (p *OAuth) User(ctx echo.Context) (u goth.User)
  • func (p *OAuth) Wrapper(e *echo.Echo)

Constants

const (
	// DefaultPath /oauth
	DefaultPath = "/oauth"
	// DefaultRouteName oauth
	DefaultRouteName = "oauth"
	// DefaultContextKey oauth_user
	DefaultContextKey = "oauth_user"
)

const SessionName = "EchoGothSession"

SessionName is the key used to access the session store. we could use the echo's sessions default, but this session should be not confict with the cookie session name defined by the sessions manager

Variables

var CompleteUserAuth = func(ctx echo.Context) (goth.User, error) {

	if ctx.Session() == nil {
		fmt.Println("You have to enable sessions")
	}

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

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

	sv := ctx.Session().Get(SessionName)
	if sv == nil {
		return goth.User{}, errors.New("could not find a matching session for this request")
	}

	sess, err := provider.UnmarshalSession(sv.(string))
	if err != nil {
		return goth.User{}, err
	}
	_, err = sess.Authorize(provider, GothParams(ctx.Queries()))

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

	return provider.FetchUser(sess)
}

CompleteUserAuth does what it says on the tin. It completes the authentication process and fetches all of the basic information about the user from the provider. It expects to be able to get the name of the provider from the named parameters as either "provider" or url query parameter ":provider".

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(ctx echo.Context) string {
	return ctx.Query("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(ctx echo.Context) string {
	state := ctx.Query("state")
	if len(state) > 0 {
		return state
	}

	return "state"

}

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.

Functions

func BeginAuthHandler

func BeginAuthHandler(ctx echo.Context) error

BeginAuthHandler is a convienence handler for starting the authentication process. It expects to be able to get the name of the provider from the named parameters as either "provider" or url query parameter ":provider". BeginAuthHandler will redirect the user to the appropriate authentication end-point for the requested provider.

func GetAuthURL

func GetAuthURL(ctx echo.Context) (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 url query parameter ":provider". I would recommend using the BeginAuthHandler instead of doing all of these steps yourself, but that's entirely up to you.

Types

type Config

type Config struct {
	Path                                                  string
	TwitterKey, TwitterSecret, TwitterName                string
	FacebookKey, FacebookSecret, FacebookName             string
	GplusKey, GplusSecret, GplusName                      string
	GithubKey, GithubSecret, GithubName                   string
	SpotifyKey, SpotifySecret, SpotifyName                string
	LinkedinKey, LinkedinSecret, LinkedinName             string
	LastfmKey, LastfmSecret, LastfmName                   string
	TwitchKey, TwitchSecret, TwitchName                   string
	DropboxKey, DropboxSecret, DropboxName                string
	DigitaloceanKey, DigitaloceanSecret, DigitaloceanName string
	BitbucketKey, BitbucketSecret, BitbucketName          string
	InstagramKey, InstagramSecret, InstagramName          string
	BoxKey, BoxSecret, BoxName                            string
	SalesforceKey, SalesforceSecret, SalesforceName       string
	AmazonKey, AmazonSecret, AmazonName                   string
	YammerKey, YammerSecret, YammerName                   string
	OneDriveKey, OneDriveSecret, OneDriveName             string
	YahooKey, YahooSecret, YahooName                      string
	SlackKey, SlackSecret, SlackName                      string
	StripeKey, StripeSecret, StripeName                   string
	WepayKey, WepaySecret, WepayName                      string
	PaypalKey, PaypalSecret, PaypalName                   string
	SteamKey, SteamName                                   string
	HerokuKey, HerokuSecret, HerokuName                   string
	UberKey, UberSecret, UberName                         string
	SoundcloudKey, SoundcloudSecret, SoundcloudName       string
	GitlabKey, GitlabSecret, GitlabName                   string

	//RouteName is the registered route's name, using to help you render a link using templates or iris.URL("RouteName","Providername")
	// defaults to 'oauth'
	RouteName string
	// defaults to 'oauth_user' used by plugin to give you the goth.User, but you can take this manually also by `context.Get(ContextKey).(goth.User)`
	ContextKey string
}

Config the configs for the gothic oauth/oauth2 authentication for third-party websites All Key and Secret values are empty by default strings. Non-empty will be registered as Goth Provider automatically, by Iris the users can still register their own providers using goth.UseProviders contains the providers' keys (& secrets) and the relative auth callback url path(ex: "/auth" will be registered as /auth/:provider/callback)

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns OAuth config, the fields of the iteral are zero-values ( empty strings)

func (Config) GenerateProviders

func (c Config) GenerateProviders(vhost string) (providers []goth.Provider)

GenerateProviders returns the valid goth providers and the relative url paths (because the goth.Provider doesn't have a public method to get the Auth path...) we do the hard-core/hand checking here at the configs.

receives one parameter which is the host from the server,ex: http://localhost:3000, will be used as prefix for the oauth callback

func (Config) MergeSingle

func (c Config) MergeSingle(cfg Config) (config Config)

MergeSingle merges the default with the given config and returns the result

type GothParams

type GothParams map[string][]string

GothParams used to convert the context.URLParams to goth's params

func (GothParams) Get

func (g GothParams) Get(key string) string

Get returns the value of

type OAuth

type OAuth struct {
	Config  Config
	HostURL string
	// contains filtered or unexported fields
}

OAuth is a plugin which helps you to use OAuth/OAuth2 apis from famous websites

func New

func New(hostURL string, cfg Config) *OAuth

New returns a new OAuth plugin receives one parameter of type 'Config'

func (*OAuth) Fail

func (p *OAuth) Fail(handler echo.HTTPErrorHandler)

Fail registers handler which fires when the user failed to logged in underhood it justs registers an error handler to the StatusUnauthorized(400 status code), same as 'iris.OnError(400,handler)'

func (*OAuth) Success

func (p *OAuth) Success(handlersFn ...interface{})

Success registers handler(s) which fires when the user logged in successfully

func (*OAuth) User

func (p *OAuth) User(ctx echo.Context) (u goth.User)

User returns the user for the particular client if user is not validated or not found it returns nil same as 'ctx.Get(config's ContextKey field).(goth.User)'

func (*OAuth) Wrapper

func (p *OAuth) Wrapper(e *echo.Echo)

Wrapper register the oauth route