Skip to content

Commit

Permalink
Update readme with project information
Browse files Browse the repository at this point in the history
  • Loading branch information
@aarondl
aarondl committed Dec 20, 2016
1 parent d07283b commit 97be009
Showing 1 changed file with 50 additions and 29 deletions.
79 changes: 50 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,34 @@
Authboss
========

[![GoDoc](https://godoc.org/gopkg.in/authboss.v0?status.svg)](https://godoc.org/gopkg.in/authboss.v0) [![Build Status](https://circleci.com/gh/go-authboss/authboss.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/go-authboss/authboss) [![Coverage Status](https://coveralls.io/repos/go-authboss/authboss/badge.svg?branch=master)](https://coveralls.io/r/go-authboss/authboss?branch=master) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/go-authboss/authboss?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[![GoDoc](https://godoc.org/gopkg.in/authboss.v1?status.svg)](https://godoc.org/gopkg.in/authboss.v1) [![Build Status](https://circleci.com/gh/go-authboss/authboss.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/go-authboss/authboss) [![Coverage Status](https://coveralls.io/repos/go-authboss/authboss/badge.svg?branch=master)](https://coveralls.io/r/go-authboss/authboss?branch=master) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](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
Expand All @@ -18,24 +39,24 @@ 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
===============

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.
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)

Expand Down Expand Up @@ -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:**
Expand All @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).
Expand Down

0 comments on commit 97be009

Please sign in to comment.