mirror of
https://github.com/volatiletech/authboss.git
synced 2024-11-28 08:58:38 +02:00
Update readme with project information
This commit is contained in:
Aaron L
parent
2009133d45
commit
7ccb973d79
79
README.md
79
README.md
@ -3,13 +3,34 @@
|
||||
Authboss
|
||||
========
|
||||
|
||||
[](https://godoc.org/gopkg.in/authboss.v0) [](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/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)
|
||||
|
||||
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
|
||||
authentication system each time. This reduces the potential for mistakes since authentication is not exactly trivial and should hopefully
|
||||
be generic enough to be plugged into all sorts of different web applications.
|
||||
|
||||
Note on Roadmap (v2)
|
||||
========
|
||||
|
||||
It's been a long time since Authboss has been released, and there have been a lot of developments in Go as well as the community
|
||||
and package management we'd like to take advantage of. There are several large refactorings that we think will make authboss
|
||||
much cleaner and as a result easier to maintain as well (and maybe get some higher test coverage). So with that we're beginning
|
||||
the v2 effort. Here's some of the things you can expect in terms of features and areas of concentration:
|
||||
|
||||
- JWT style auth for JS-based pages
|
||||
- Cleaner separation of view from logic
|
||||
- Storer rewrite
|
||||
- Go 1.7 context usage
|
||||
|
||||
As far as the project goes this is how it will be managed:
|
||||
|
||||
- The current master HEAD will be available as v1.0.0
|
||||
- No new features will be put in v1 branch, only critical bugfixes (life support only)
|
||||
- v1 will be removed 6 months after the release of v2
|
||||
- v2 will leave gopkg.in for proper Semantic versioning + vendoring
|
||||
- This change means that everyone should start using govendor/glide/godep to manage authboss v2
|
||||
|
||||
Modules
|
||||
========
|
||||
Each module can be turned on simply by importing it and the side-effects take care of the rest. Not all the capabilities
|
||||
@ -18,13 +39,13 @@ use them in your app.
|
||||
|
||||
Name | Import Path | Description
|
||||
---------------|-----------------------------------------------------------------------------------------------------|------------
|
||||
Auth | [gopkg.in/authboss.v0/auth](https://github.com/go-authboss/authboss/tree/master/auth) | Provides database password authentication for users.
|
||||
Confirm | [gopkg.in/authboss.v0/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.v0/lock](https://github.com/go-authboss/authboss/tree/master/lock) | Locks user accounts after N authentication failures in M time.
|
||||
OAuth2 | [gopkg.in/authboss.v0/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2) | Provides oauth2 authentication for users.
|
||||
Recover | [gopkg.in/authboss.v0/recover](https://github.com/go-authboss/authboss/tree/master/recover) | Allows for password resets via e-mail.
|
||||
Register | [gopkg.in/authboss.v0/register](https://github.com/go-authboss/authboss/tree/master/register) | User-initiated account creation.
|
||||
Remember | [gopkg.in/authboss.v0/remember](https://github.com/go-authboss/authboss/tree/master/remember) | Persisting login sessions past session cookie expiry.
|
||||
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.
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
@ -32,10 +53,10 @@ Getting Started
|
||||
Install the library and import it:
|
||||
|
||||
```
|
||||
go get gopkg.in/authboss.v0
|
||||
go get gopkg.in/authboss.v1
|
||||
```
|
||||
|
||||
After that a good place to start in any Authboss implementation is the [configuration struct](http://godoc.org/gopkg.in/authboss.v0#Config).
|
||||
After that a good place to start in any Authboss implementation is the [configuration struct](http://godoc.org/gopkg.in/authboss.v1#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.
|
||||
@ -120,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.v0#Authboss.UpdatePassword) method for you to use. Please consult it's documentation
|
||||
Authboss has the [UpdatePassword](http://godoc.org/gopkg.in/authboss.v1#Authboss.UpdatePassword) method for you to use. Please consult it's documentation
|
||||
for a thorough explanation of each parameter and usage.
|
||||
|
||||
```go
|
||||
@ -145,7 +166,7 @@ if err != nil {
|
||||
|
||||
## <a name="auth"></a>User Authentication via Password
|
||||
**Requirements:**
|
||||
- Auth module ([gopkg.in/authboss.v0/auth](https://github.com/go-authboss/authboss/tree/master/auth))
|
||||
- Auth module ([gopkg.in/authboss.v1/auth](https://github.com/go-authboss/authboss/tree/master/auth))
|
||||
- [Storer](#storers)
|
||||
- [Session Storer](#client_storers)
|
||||
- [Views](#views)
|
||||
@ -162,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.v0/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2))
|
||||
- OAuth2 module ([gopkg.in/authboss.v1/oauth2](https://github.com/go-authboss/authboss/tree/master/oauth2))
|
||||
- [OAuth2Storer](#storers)
|
||||
- OAuth2Providers
|
||||
- [Session and Cookie Storers](#client_storers)
|
||||
@ -177,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.v0#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).
|
||||
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
|
||||
@ -199,7 +220,7 @@ uri := `/authboss_mount_path/oauth2/google?` + params.Encode()
|
||||
|
||||
## <a name="register"></a> User Registration
|
||||
**Requirements:**
|
||||
- Register module ([gopkg.in/authboss.v0/register](https://github.com/go-authboss/authboss/tree/master/register))
|
||||
- Register module ([gopkg.in/authboss.v1/register](https://github.com/go-authboss/authboss/tree/master/register))
|
||||
- [RegisterStorer](#storers)
|
||||
- [Session Storer](#client_storers)
|
||||
- [Views](#views)
|
||||
@ -218,8 +239,8 @@ See also: [Validation](#validation)
|
||||
|
||||
## <a name="confirm"></a> Confirming Registrations
|
||||
**Requirements:**
|
||||
- Register module ([gopkg.in/authboss.v0/register](https://github.com/go-authboss/authboss/tree/master/register))
|
||||
- Confirm module ([gopkg.in/authboss.v0/confirm](https://github.com/go-authboss/authboss/tree/master/confirm))
|
||||
- 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))
|
||||
- [RegisterStorer](#storers)
|
||||
- [Session and Cookie Storers](#client_storers)
|
||||
- [Views](#views)
|
||||
@ -234,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.v0/recover](https://github.com/go-authboss/authboss/tree/master/recover))
|
||||
- Recover module ([gopkg.in/authboss.v1/recover](https://github.com/go-authboss/authboss/tree/master/recover))
|
||||
- [RecoverStorer](#storers)
|
||||
- [Session Storer](#client_storers)
|
||||
- [Views](#views)
|
||||
@ -250,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.v0/remember](https://github.com/go-authboss/authboss/tree/master/remember))
|
||||
- Remember module ([gopkg.in/authboss.v1/remember](https://github.com/go-authboss/authboss/tree/master/remember))
|
||||
- [RememberStorer](#storers)
|
||||
- [Session and Cookie Storers](#client_storers)
|
||||
|
||||
@ -278,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.v0/lock](https://github.com/go-authboss/authboss/tree/master/lock))
|
||||
- Lock module ([gopkg.in/authboss.v1/lock](https://github.com/go-authboss/authboss/tree/master/lock))
|
||||
- [Storer](#storers)
|
||||
|
||||
**Storage Requirements:**
|
||||
@ -293,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.v0#Authboss.ExpireMiddleware)
|
||||
- [ExpireMiddleware](http://godoc.org/gopkg.in/authboss.v1#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.
|
||||
@ -308,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.v0#Rules) that you can use instead of writing your own. Validation errors are reported and
|
||||
[Rules](http://godoc.org/gopkg.in/authboss.v1#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.
|
||||
|
||||
@ -356,12 +377,12 @@ There are three parts to storage: Storer interfaces, User Struct, Binding/Unbind
|
||||
|
||||
#### Storer Interfaces
|
||||
|
||||
- [Storer](http://godoc.org/gopkg.in/authboss.v0#Storer)
|
||||
- [OAuth2Storer](http://godoc.org/gopkg.in/authboss.v0#OAuth2Storer)
|
||||
- [ConfirmStorer](http://godoc.org/gopkg.in/confirm/authboss.v0#ConfirmStorer)
|
||||
- [RecoverStorer](http://godoc.org/gopkg.in/recover/authboss.v0#RecoverStorer)
|
||||
- [RegisterStorer](http://godoc.org/gopkg.in/register/authboss.v0#RegisterStorer)
|
||||
- [RememberStorer](http://godoc.org/gopkg.in/remember/authboss.v0#RememberStorer)
|
||||
- [Storer](http://godoc.org/gopkg.in/authboss.v1#Storer)
|
||||
- [OAuth2Storer](http://godoc.org/gopkg.in/authboss.v1#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)
|
||||
- [RememberStorer](http://godoc.org/gopkg.in/remember/authboss.v1#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
|
||||
@ -403,7 +424,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/remember/authboss.v0#ClientStorer)
|
||||
[ClientStorer Interface](http://godoc.org/gopkg.in/remember/authboss.v1#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).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user