README
¶
Gomniauth
Authentication framework for Go applications.
- EDITOR NOTE: It is recommended that you transition to the Goth package.
Features
- OAuth2 today
- Supports other protocols too
- Multiple providers - Supports Google, GitHub and Facebook and more
- Easily extensible
- Example web app to copy
- Works beautifully with Goweb
- Fully TDD
Documentation
- Jump right into the API Documentation
Get started
Install Gomniauth by doing:
$ go get github.com/stretchr/gomniauth
Check out the example web app code to see how to use Gomniauth using Goweb.
Contributing
- If you add a provider that others could also make use of, please send us a Pull Request and we'll add it to the repo.
Implementing Gomniauth
Set up Gomniauth
First and only once for your application, you need to setup the security key and providers. The security key is used when hashing any data that gets transmitted to ensure its integrity.
You are free to use the signature package's RandomKey function to generate a unique code every time your application starts.
gomniauth.SetSecurityKey(signature.RandomKey(64))
A provider represents an authentication service that will be available to your users. Usually, you'll have to add some configuration of your own, such as your application key and secret (provided by the auth service), and the callback into your app where users will be sent following successful (or not) authentication.
gomniauth.WithProviders(
github.New("key", "secret", "callback"),
google.New("key", "secret", "callback"),
)
What kind of callback?
The callback should be an absolute URL to your application and should include the provider name in some way.
For example, in the example web app we used the following format for callbacks:
http://mydomain.com/auth/{provider}/callback
Are they logged in?
When a user tries to access a protected resource, or if you want to make third party authenticated API calls, you need a mechanism to decide whether a user is logged in or not. For web apps, cookies usually work, if you're building an API, then you should consider some kind of auth token.
Decide how to log in
If they are not logged in, you need to provide them with a list of providers from which they can choose.
You can access a list of the providers you are supporting by calling the gomniauth.Providers() function.
Redirecting them to the login page
Once a provider has been chosen, you must redirect them to be authenticated. You can do this by using the gomniauth.Provider function, that will return a Provider by name.
So if the user chooses to login using Github, you would do:
provider, err := gomniauth.Provider("github")
Once you have your provider, you can get the URL to redirect users to by calling:
authUrl, err := provider.GetBeginAuthURL(state, options)
You should then redirect the user to the authUrl.
State and options
The state parameter is a State object that contains information that will be hashed and passed (via the third party) through to your callback (see below). Usually, this object contains the URL to redirect to once authentication has completed, but you can store whatever you like in here.
The options parameter is an objx.Map containing additional query-string parameters that will be sent to the authentication service. For example, in OAuth2 implementations, you can specify a scope parameter to get additional access to other services you might need.
Handling the callback
Once the third party authentication service has finished processing the request, they will send the user back to your callback URL.
Remember, you specified the callback URL when you setup your providers.
For example, the user might hit:
http://yourdomain.com/auth/github/callback?code=abc123
You don't need to worry about the detail of the parameters passed back, because Gomniauth takes care of those for you. You just need to pass them into the CompleteAuth method of your provider:
provider, err := gomniauth.Provider("github")
creds, err := provider.CompleteAuth(queryParams)
NOTE: It's unlikely you'll hard-code the provider name, we have done it here to make it obvious what's going on.
The provider will then do the work in the background to complete the authentication and return the creds for that user. The creds are then used to make authenticated requests to the third party (in this case Github) on behalf of the user.
Getting the user information
If you then want some information about the user who just authenticated, you can call the GetUser method on the provider (passing in the creds from the CompleteAuth method.)
The User you get back will give you access to the common user data you will need (like name, email, avatar URL etc) and also an objx.Map of Data() that contains everything else.
Caching in
Once you had the credentials for a user for a given provider, you should cache them in your own datastore. This will mean that if the cookie hasn't expired, or if the client has stored the auth token, they can continue to use the service without having to log in again.
Documentation
¶
Overview ¶
General use authentication package for Go.
To get started, visit the Gomniauth GitHub project homepage: https://github.com/stretchr/gomniauth
Index ¶
- Variables
- func GetSecurityKey() string
- func NewState(keyAndValuePairs ...interface{}) *common.State
- func Provider(name string) (common.Provider, error)
- func ProviderPublicData(provider common.Provider, options map[string]interface{}) (interface{}, error)
- func SetSecurityKey(key string)
- func StateFromParam(paramValue string) (*common.State, error)
- type ProviderList
Constants ¶
This section is empty.
Variables ¶
SharedProviderList keeps track of the last created ProviderList. It is useful for using shortcut methods directly on gomniauth package rather than having to refer to the list.
Functions ¶
func NewState ¶
NewState creates a new object that can be used to persist state across authentication requests.
func Provider ¶
Provider gets a provider by name from the SharedProviderList, or returns a common.MissingProviderError if no provider with that name is registered.
func ProviderPublicData ¶
func ProviderPublicData(provider common.Provider, options map[string]interface{}) (interface{}, error)
ProviderPublicData gets the public data for the specified provider.
The options should contain the `loginpathFormat`, which will determine how the loginpath value is created.
func SetSecurityKey ¶
func SetSecurityKey(key string)
SetSecurityKey sets the global security key to be used for signing the state variable in the auth request. This allows gomniauth to detect if the data in the state variable has been changed.
Types ¶
type ProviderList ¶
type ProviderList struct {
// contains filtered or unexported fields
}
ProviderList represents a simple common.ProviderList that holds an array of providers, and allows access to them.
func WithProviders ¶
func WithProviders(providers ...common.Provider) *ProviderList
WithProviders generates a new ProviderList which should be used to interact with Gomniauth services.
func (*ProviderList) Add ¶
func (l *ProviderList) Add(provider common.Provider) *ProviderList
Add adds a provider to this list.
func (*ProviderList) Provider ¶
func (l *ProviderList) Provider(name string) (common.Provider, error)
Provider gets a provider by name, or returns a common.MissingProviderError if no provider with that name is registered.
func (*ProviderList) Providers ¶
func (l *ProviderList) Providers() []common.Provider
Providers gets all registered Provider objects.
Source Files
Directories