|
|
|
|
@@ -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/go-authboss/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/go-authboss/authboss/auth](https://github.com/go-authboss/authboss/tree/master/auth) | Provides database password authentication for users.
|
|
|
|
|
Confirm | [github.com/go-authboss/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/go-authboss/authboss/lock](https://github.com/go-authboss/authboss/tree/master/lock) | Locks user accounts after N authentication failures in M time.
|
|
|
|
|
OAuth2 | [github.com/go-authboss/authboss/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2) | Provides oauth2 authentication for users.
|
|
|
|
|
Recover | [github.com/go-authboss/authboss/recover](https://github.com/go-authboss/authboss/tree/master/recover) | Allows for password resets via e-mail.
|
|
|
|
|
Register | [github.com/go-authboss/authboss/register](https://github.com/go-authboss/authboss/tree/master/register) | User-initiated account creation.
|
|
|
|
|
Remember | [github.com/go-authboss/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/go-authboss/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/go-authboss/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/go-authboss/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/go-authboss/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/go-authboss/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/go-authboss/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/go-authboss/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/go-authboss/authboss/register](https://github.com/go-authboss/authboss/tree/master/register))
|
|
|
|
|
- Confirm module ([github.com/go-authboss/authboss/confirm](https://github.com/go-authboss/authboss/tree/master/confirm))
|
|
|
|
|
- [RegisterStorer](#storers)
|
|
|
|
|
- [Session and Cookie Storers](#client_storers)
|
|
|
|
|
- [Views](#views)
|
|
|
|
|
@@ -255,7 +255,7 @@ provided in the e-mail and their account becomes confirmed, they will automatica
|
|
|
|
|
|
|
|
|
|
## <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/go-authboss/authboss/recover](https://github.com/go-authboss/authboss/tree/master/recover))
|
|
|
|
|
- [RecoverStorer](#storers)
|
|
|
|
|
- [Session Storer](#client_storers)
|
|
|
|
|
- [Views](#views)
|
|
|
|
|
@@ -271,7 +271,7 @@ their new password is stored, they are logged in and redirected to the RecoverOK
|
|
|
|
|
|
|
|
|
|
## <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/go-authboss/authboss/remember](https://github.com/go-authboss/authboss/tree/master/remember))
|
|
|
|
|
- [RememberStorer](#storers)
|
|
|
|
|
- [Session and Cookie Storers](#client_storers)
|
|
|
|
|
|
|
|
|
|
@@ -299,7 +299,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/go-authboss/authboss/lock](https://github.com/go-authboss/authboss/tree/master/lock))
|
|
|
|
|
- [Storer](#storers)
|
|
|
|
|
|
|
|
|
|
**Storage Requirements:**
|
|
|
|
|
@@ -314,7 +314,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/go-authboss/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.
|
|
|
|
|
@@ -329,7 +329,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/go-authboss/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.
|
|
|
|
|
|
|
|
|
|
@@ -377,8 +377,8 @@ 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)
|
|
|
|
|
- [Storer](http://godoc.org/github.com/go-authboss/authboss#Storer)
|
|
|
|
|
- [OAuth2Storer](http://godoc.org/github.com/go-authboss/authboss#OAuth2Storer)
|
|
|
|
|
- [ConfirmStorer](http://godoc.org/gopkg.in/confirm/authboss.v1#ConfirmStorer)
|
|
|
|
|
- [RecoverStorer](http://godoc.org/gopkg.in/recover/authboss.v1#RecoverStorer)
|
|
|
|
|
- [RegisterStorer](http://godoc.org/gopkg.in/register/authboss.v1#RegisterStorer)
|
|
|
|
|
|
Aaron L