|
|
|
|
@ -3,7 +3,7 @@
|
|
|
|
|
Authboss
|
|
|
|
|
========
|
|
|
|
|
|
|
|
|
|
[](https://godoc.org/gopkg.in/authboss.v1) [](https://circleci.com/gh/go-authboss/authboss) [](https://coveralls.io/r/go-authboss/authboss?branch=master) [](https://gitter.im/go-authboss/authboss?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
|
|
|
|
[](https://godoc.org/github.com/volatiletech/authboss) [](https://circleci.com/gh/go-authboss/authboss) [](https://coveralls.io/r/go-authboss/authboss?branch=master) [](https://gitter.im/go-authboss/authboss?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
|
|
|
|
|
|
|
|
|
Authboss is a modular authentication system for the web. It tries to remove as much boilerplate and "hard things" as possible so that
|
|
|
|
|
each time you start a new web project in Go, you can plug it in, configure, and start building your app without having to build an
|
|
|
|
|
@ -39,13 +39,13 @@ use them in your app.
|
|
|
|
|
|
|
|
|
|
Name | Import Path | Description
|
|
|
|
|
---------------|-----------------------------------------------------------------------------------------------------|------------
|
|
|
|
|
Auth | [gopkg.in/authboss.v1/auth](https://github.com/go-authboss/authboss/tree/master/auth) | Provides database password authentication for users.
|
|
|
|
|
Confirm | [gopkg.in/authboss.v1/confirm](https://github.com/go-authboss/authboss/tree/master/confirm) | Sends an e-mail verification before allowing users to log in.
|
|
|
|
|
Lock | [gopkg.in/authboss.v1/lock](https://github.com/go-authboss/authboss/tree/master/lock) | Locks user accounts after N authentication failures in M time.
|
|
|
|
|
OAuth2 | [gopkg.in/authboss.v1/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2) | Provides oauth2 authentication for users.
|
|
|
|
|
Recover | [gopkg.in/authboss.v1/recover](https://github.com/go-authboss/authboss/tree/master/recover) | Allows for password resets via e-mail.
|
|
|
|
|
Register | [gopkg.in/authboss.v1/register](https://github.com/go-authboss/authboss/tree/master/register) | User-initiated account creation.
|
|
|
|
|
Remember | [gopkg.in/authboss.v1/remember](https://github.com/go-authboss/authboss/tree/master/remember) | Persisting login sessions past session cookie expiry.
|
|
|
|
|
Auth | [github.com/volatiletech/authboss/auth](https://github.com/go-authboss/authboss/tree/master/auth) | Provides database password authentication for users.
|
|
|
|
|
Confirm | [github.com/volatiletech/authboss/confirm](https://github.com/go-authboss/authboss/tree/master/confirm) | Sends an e-mail verification before allowing users to log in.
|
|
|
|
|
Lock | [github.com/volatiletech/authboss/lock](https://github.com/go-authboss/authboss/tree/master/lock) | Locks user accounts after N authentication failures in M time.
|
|
|
|
|
OAuth2 | [github.com/volatiletech/authboss/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2) | Provides oauth2 authentication for users.
|
|
|
|
|
Recover | [github.com/volatiletech/authboss/recover](https://github.com/go-authboss/authboss/tree/master/recover) | Allows for password resets via e-mail.
|
|
|
|
|
Register | [github.com/volatiletech/authboss/register](https://github.com/go-authboss/authboss/tree/master/register) | User-initiated account creation.
|
|
|
|
|
Remember | [github.com/volatiletech/authboss/remember](https://github.com/go-authboss/authboss/tree/master/remember) | Persisting login sessions past session cookie expiry.
|
|
|
|
|
|
|
|
|
|
Getting Started
|
|
|
|
|
===============
|
|
|
|
|
@ -53,10 +53,10 @@ Getting Started
|
|
|
|
|
Install the library and import it:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
go get gopkg.in/authboss.v1
|
|
|
|
|
go get github.com/volatiletech/authboss
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
After that a good place to start in any Authboss implementation is the [configuration struct](http://godoc.org/gopkg.in/authboss.v1#Config).
|
|
|
|
|
After that a good place to start in any Authboss implementation is the [configuration struct](http://godoc.org/github.com/volatiletech/authboss#Config).
|
|
|
|
|
There are many defaults setup for you but there are some elements that must be provided.
|
|
|
|
|
to find out what is configurable view the documentation linked to above, each struct element
|
|
|
|
|
is documented.
|
|
|
|
|
@ -141,7 +141,7 @@ user struct, nil | The user is logged in.
|
|
|
|
|
Because on password reset various cleanings need to happen (for example Remember Me tokens
|
|
|
|
|
should all be deleted) setting the user's password yourself is not a good idea.
|
|
|
|
|
|
|
|
|
|
Authboss has the [UpdatePassword](http://godoc.org/gopkg.in/authboss.v1#Authboss.UpdatePassword) method for you to use. Please consult it's documentation
|
|
|
|
|
Authboss has the [UpdatePassword](http://godoc.org/github.com/volatiletech/authboss#Authboss.UpdatePassword) method for you to use. Please consult it's documentation
|
|
|
|
|
for a thorough explanation of each parameter and usage.
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
@ -166,7 +166,7 @@ if err != nil {
|
|
|
|
|
|
|
|
|
|
## <a name="auth"></a>User Authentication via Password
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- Auth module ([gopkg.in/authboss.v1/auth](https://github.com/go-authboss/authboss/tree/master/auth))
|
|
|
|
|
- Auth module ([github.com/volatiletech/authboss/auth](https://github.com/go-authboss/authboss/tree/master/auth))
|
|
|
|
|
- [Storer](#storers)
|
|
|
|
|
- [Session Storer](#client_storers)
|
|
|
|
|
- [Views](#views)
|
|
|
|
|
@ -183,7 +183,7 @@ Another link is created for a logout. Simply link/redirect the user to this page
|
|
|
|
|
|
|
|
|
|
## <a name="oauth2"></a> User Authentication via OAuth2
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- OAuth2 module ([gopkg.in/authboss.v1/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2))
|
|
|
|
|
- OAuth2 module ([github.com/volatiletech/authboss/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2))
|
|
|
|
|
- [OAuth2Storer](#storers)
|
|
|
|
|
- OAuth2Providers
|
|
|
|
|
- [Session and Cookie Storers](#client_storers)
|
|
|
|
|
@ -198,7 +198,7 @@ Another link is created for a logout. Simply link/redirect the user to this page
|
|
|
|
|
**How it works:** Routes are registered for each oauth2 provider you specify in the OAuth2Providers configuration.
|
|
|
|
|
You redirect the user to one of these initial routes (/mount_path/oauth2/providername) and the oauth2 module
|
|
|
|
|
will ensure the user logs in and receives a token. It then calls the Callback you specify in your OAuth2Provider
|
|
|
|
|
inside the config, this is responsible for returning various information, please see the docs for [OAuth2Provider](http://godoc.org/gopkg.in/authboss.v1#OAuth2Provider).
|
|
|
|
|
inside the config, this is responsible for returning various information, please see the docs for [OAuth2Provider](http://godoc.org/github.com/volatiletech/authboss#OAuth2Provider).
|
|
|
|
|
Once the callback is complete, the user is saved in the database, and logged in using the session.
|
|
|
|
|
|
|
|
|
|
Please note that in order to redirect to specific URLs or have the user use the remember module for oauth2 logins you must pass
|
|
|
|
|
@ -220,7 +220,7 @@ uri := `/authboss_mount_path/oauth2/google?` + params.Encode()
|
|
|
|
|
|
|
|
|
|
## <a name="register"></a> User Registration
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- Register module ([gopkg.in/authboss.v1/register](https://github.com/go-authboss/authboss/tree/master/register))
|
|
|
|
|
- Register module ([github.com/volatiletech/authboss/register](https://github.com/go-authboss/authboss/tree/master/register))
|
|
|
|
|
- [RegisterStorer](#storers)
|
|
|
|
|
- [Session Storer](#client_storers)
|
|
|
|
|
- [Views](#views)
|
|
|
|
|
@ -239,8 +239,8 @@ See also: [Validation](#validation)
|
|
|
|
|
|
|
|
|
|
## <a name="confirm"></a> Confirming Registrations
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- Register module ([gopkg.in/authboss.v1/register](https://github.com/go-authboss/authboss/tree/master/register))
|
|
|
|
|
- Confirm module ([gopkg.in/authboss.v1/confirm](https://github.com/go-authboss/authboss/tree/master/confirm))
|
|
|
|
|
- Register module ([github.com/volatiletech/authboss/register](https://github.com/go-authboss/authboss/tree/master/register))
|
|
|
|
|
- Confirm module ([github.com/volatiletech/authboss/confirm](https://github.com/go-authboss/authboss/tree/master/confirm))
|
|
|
|
|
- [RegisterStorer](#storers)
|
|
|
|
|
- [Session and Cookie Storers](#client_storers)
|
|
|
|
|
- [Views](#views)
|
|
|
|
|
@ -258,7 +258,7 @@ logged in. The default for this property is set to false.
|
|
|
|
|
|
|
|
|
|
## <a name="recover"></a> Password Recovery
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- Recover module ([gopkg.in/authboss.v1/recover](https://github.com/go-authboss/authboss/tree/master/recover))
|
|
|
|
|
- Recover module ([github.com/volatiletech/authboss/recover](https://github.com/go-authboss/authboss/tree/master/recover))
|
|
|
|
|
- [RecoverStorer](#storers)
|
|
|
|
|
- [Session Storer](#client_storers)
|
|
|
|
|
- [Views](#views)
|
|
|
|
|
@ -275,7 +275,7 @@ to true, the user will also be automatically logged in. The default for this pro
|
|
|
|
|
|
|
|
|
|
## <a name="remember"></a> Remember Me (persistent login)
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- Remember module ([gopkg.in/authboss.v1/remember](https://github.com/go-authboss/authboss/tree/master/remember))
|
|
|
|
|
- Remember module ([github.com/volatiletech/authboss/remember](https://github.com/go-authboss/authboss/tree/master/remember))
|
|
|
|
|
- [RememberStorer](#storers)
|
|
|
|
|
- [Session and Cookie Storers](#client_storers)
|
|
|
|
|
|
|
|
|
|
@ -303,7 +303,7 @@ to pages with sensitive information if this value is true in the session, and fo
|
|
|
|
|
|
|
|
|
|
## <a name="lock"></a> Locking Accounts for Authentication Failures
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- Lock module ([gopkg.in/authboss.v1/lock](https://github.com/go-authboss/authboss/tree/master/lock))
|
|
|
|
|
- Lock module ([github.com/volatiletech/authboss/lock](https://github.com/go-authboss/authboss/tree/master/lock))
|
|
|
|
|
- [Storer](#storers)
|
|
|
|
|
|
|
|
|
|
**Storage Requirements:**
|
|
|
|
|
@ -318,7 +318,7 @@ locked for the configured LockDuration. After this duration the user will be abl
|
|
|
|
|
|
|
|
|
|
## <a name="expire"></a> Expiring Inactive User Sessions
|
|
|
|
|
**Requirements:**
|
|
|
|
|
- [ExpireMiddleware](http://godoc.org/gopkg.in/authboss.v1#Authboss.ExpireMiddleware)
|
|
|
|
|
- [ExpireMiddleware](http://godoc.org/github.com/volatiletech/authboss#Authboss.ExpireMiddleware)
|
|
|
|
|
- [Session Storer](#client_storers)
|
|
|
|
|
|
|
|
|
|
**How it works:** A middleware is installed into the stack. This middleware uses the session to log the last action time of the user.
|
|
|
|
|
@ -333,7 +333,7 @@ http.ListenAndServe(":8080", ab.ExpireMiddleware(mux)) // Install the middleware
|
|
|
|
|
|
|
|
|
|
**Field validation:** Validation is achieved through the use of policies. These policies are in the configuration. They can be added for any field.
|
|
|
|
|
Any type can be used for validation that implements the Validator interface. Authboss supplies a quite flexible field validator called
|
|
|
|
|
[Rules](http://godoc.org/gopkg.in/authboss.v1#Rules) that you can use instead of writing your own. Validation errors are reported and
|
|
|
|
|
[Rules](http://godoc.org/github.com/volatiletech/authboss#Rules) that you can use instead of writing your own. Validation errors are reported and
|
|
|
|
|
handled all in the same way, and the view decides how to display these to the user. See the examples or the authboss default view files to see
|
|
|
|
|
how to display errors.
|
|
|
|
|
|
|
|
|
|
@ -381,12 +381,12 @@ There are three parts to storage: Storer interfaces, User Struct, Binding/Unbind
|
|
|
|
|
|
|
|
|
|
#### Storer Interfaces
|
|
|
|
|
|
|
|
|
|
- [Storer](http://godoc.org/gopkg.in/authboss.v1#Storer)
|
|
|
|
|
- [OAuth2Storer](http://godoc.org/gopkg.in/authboss.v1#OAuth2Storer)
|
|
|
|
|
- [ConfirmStorer](http://godoc.org/gopkg.in/authboss.v1/confirm#ConfirmStorer)
|
|
|
|
|
- [RecoverStorer](http://godoc.org/gopkg.in/authboss.v1/recover#RecoverStorer)
|
|
|
|
|
- [RegisterStorer](http://godoc.org/gopkg.in/authboss.v1/register#RegisterStorer)
|
|
|
|
|
- [RememberStorer](http://godoc.org/gopkg.in/authboss.v1/remember#RememberStorer)
|
|
|
|
|
- [Storer](http://godoc.org/github.com/volatiletech/authboss#Storer)
|
|
|
|
|
- [OAuth2Storer](http://godoc.org/github.com/volatiletech/authboss#OAuth2Storer)
|
|
|
|
|
- [ConfirmStorer](http://godoc.org/github.com/volatiletech/authboss/confirm#ConfirmStorer)
|
|
|
|
|
- [RecoverStorer](http://godoc.org/github.com/volatiletech/authboss/recover#RecoverStorer)
|
|
|
|
|
- [RegisterStorer](http://godoc.org/github.com/volatiletech/authboss/register#RegisterStorer)
|
|
|
|
|
- [RememberStorer](http://godoc.org/github.com/volatiletech/authboss/remember#RememberStorer)
|
|
|
|
|
|
|
|
|
|
Each of the store interfaces provides some amount of functionality to a module. Without the appropriate storer type the module cannot function.
|
|
|
|
|
Most of these interfaces simply do look ups on the user based on different field. Some of them like the RememberStorer are more special in their
|
|
|
|
|
@ -428,7 +428,7 @@ extract it's data into authboss.Attributes, which is used for all authboss opera
|
|
|
|
|
|
|
|
|
|
## <a name="client_storers"></a> Implementing Client Storers
|
|
|
|
|
|
|
|
|
|
[ClientStorer Interface](http://godoc.org/gopkg.in/authboss.v1#ClientStorer)
|
|
|
|
|
[ClientStorer Interface](http://godoc.org/github.com/volatiletech/authboss#ClientStorer)
|
|
|
|
|
|
|
|
|
|
ClientStorer's encapsulate the functionality of cookies for the web application. The session storer is for session data, the cookie storer is actually
|
|
|
|
|
only used for the remember tokens so it should create cookies of very long durations (however long you want your users remembered for).
|
|
|
|
|
|
Aaron L