README
¶
Go Session Authentication
This package uses the Gorilla web toolkit's sessions package to implement a user authentication and authorization system for Go web servers.
Multiple user data storage backends are available, and new ones can be implemented relatively easily.
- File based (gob)
- Various SQL Databases (tested with MySQL, PostgresSQL, SQLite)
- MongoDB (mgo)
Access can be restricted by a users' role.
Uses bcrypt for password hashing.
Run go run server.go from the examples directory and visit localhost:8009
for an example. You can login with the username and password "admin".
Tests can be run by simulating Travis CI's build environment. There's a very
unsafe script --- start-test-env.sh that will do this for you.
You should follow me on Twitter.
TODO
- User roles - modification
- SMTP email validation (key based)
- More backends
- Possible remove dependance on bcrypt
Documentation
¶
Overview ¶
Package httpauth implements cookie/session based authentication and authorization. Intended for use with the net/http or github.com/gorilla/mux packages, but may work with github.com/codegangsta/martini as well. Credentials are stored as a username + password hash, computed with bcrypt.
Three user storage systems are currently implemented: file based (encoding/gob), sql databases (database/sql), and MongoDB databases.
Access can be restricted by a users' role. A higher role will give more access.
Users can be redirected to the page that triggered an authentication error.
Messages describing the reason a user could not authenticate are saved in a cookie, and can be accessed with the Messages function.
Example source can be found at https://github.com/apexskier/httpauth/blob/master/examples/server.go
Index ¶
- Variables
- type AuthBackend
- type Authorizer
- func (a Authorizer) Authorize(rw http.ResponseWriter, req *http.Request) (*UserData, error)
- func (a Authorizer) ChangeRole(user *UserData, role string) error
- func (a Authorizer) DeleteUser(username string) error
- func (a Authorizer) Login(rw http.ResponseWriter, req *http.Request, u string, p string, dest string) error
- func (a Authorizer) Logout(rw http.ResponseWriter, req *http.Request) error
- func (a Authorizer) Messages(rw http.ResponseWriter, req *http.Request) []string
- func (a Authorizer) Register(rw http.ResponseWriter, req *http.Request, user UserData, password string) error
- func (a Authorizer) Satisfy(user *UserData, role string) bool
- func (a Authorizer) Update(rw http.ResponseWriter, req *http.Request, p string, e string) error
- type GobFileAuthBackend
- type MemAuthBackend
- type MongodbAuthBackend
- type Role
- type SQLAuthBackend
- type UserData
Constants ¶
This section is empty.
Variables ¶
var ( ErrDeleteNull = mkerror("deleting non-existant user") ErrMissingUser = mkerror("can't find user") )
ErrDeleteNull is returned by DeleteUser when that user didn't exist at the time of call. ErrMissingUser is returned by Users when a user is not found.
var (
ErrMissingBackend = errors.New("gobfilebackend: missing backend")
)
ErrMissingBackend is returned by NewGobFileAuthBackend when the file doesn't exist. Be sure to create (or touch) it if using brand new backend or resetting backend.
Functions ¶
This section is empty.
Types ¶
type AuthBackend ¶
type AuthBackend interface {
SaveUser(u UserData) error
User(username string) (user UserData, e error)
Users() (users []UserData, e error)
DeleteUser(username string) error
Close()
}
The AuthBackend interface defines a set of methods an AuthBackend must implement.
type Authorizer ¶
type Authorizer struct {
// contains filtered or unexported fields
}
Authorizer structures contain the store of user session cookies a reference to a backend storage system.
func NewAuthorizer ¶
func NewAuthorizer(backend AuthBackend, key []byte, defaultRole string, roles map[string]Role) (Authorizer, error)
NewAuthorizer returns a new Authorizer given an AuthBackend, a cookie store key, a default user role, and a map of roles. If the key changes, logged in users will need to reauthenticate.
Roles are a map of string to httpauth.Role values (integers). Higher Role values have more access.
Example roles:
var roles map[string]httpauth.Role roles["user"] = 2 roles["admin"] = 4 roles["moderator"] = 3
func (Authorizer) Authorize ¶
func (a Authorizer) Authorize(rw http.ResponseWriter, req *http.Request) (*UserData, error)
Authorize checks if a user is logged in and returns an error on failed authentication. If redirectWithMessage is set, the page being authorized will be saved and a "Login to do that." message will be saved to the messages list. The next time the user logs in, they will be redirected back to the saved page.
func (Authorizer) ChangeRole ¶
func (a Authorizer) ChangeRole(user *UserData, role string) error
ChangeRole changes the role for an existing user.
func (Authorizer) DeleteUser ¶
func (a Authorizer) DeleteUser(username string) error
DeleteUser removes a user from the Authorize. ErrMissingUser is returned if the user to be deleted isn't found.
func (Authorizer) Login ¶
func (a Authorizer) Login(rw http.ResponseWriter, req *http.Request, u string, p string, dest string) error
Login logs a user in. They will be redirected to dest or to the last location an authorization redirect was triggered (if found) on success. A message will be added to the session on failure with the reason.
func (Authorizer) Logout ¶
func (a Authorizer) Logout(rw http.ResponseWriter, req *http.Request) error
Logout clears an authentication session and add a logged out message.
func (Authorizer) Messages ¶
func (a Authorizer) Messages(rw http.ResponseWriter, req *http.Request) []string
Messages fetches a list of saved messages. Use this to get a nice message to print to the user on a login page or registration page in case something happened (username taken, invalid credentials, successful logout, etc).
func (Authorizer) Register ¶
func (a Authorizer) Register(rw http.ResponseWriter, req *http.Request, user UserData, password string) error
Register and save a new user. Returns an error and adds a message if the username is in use.
Pass in a instance of UserData with at least a username and email specified. If no role is given, the default one is used.
func (Authorizer) Satisfy ¶
func (a Authorizer) Satisfy(user *UserData, role string) bool
AuthorizeRole runs Authorize on a user, then makes sure their role is at least as high as the specified one, failing if not.
func (Authorizer) Update ¶
func (a Authorizer) Update(rw http.ResponseWriter, req *http.Request, p string, e string) error
Update changes data for an existing user. Needs thought...
type GobFileAuthBackend ¶
type GobFileAuthBackend struct {
// contains filtered or unexported fields
}
GobFileAuthBackend stores user data and the location of the gob file.
func NewGobFileAuthBackend ¶
func NewGobFileAuthBackend(filepath string) (b GobFileAuthBackend, e error)
NewGobFileAuthBackend initializes a new backend by loading a map of users from a file. If the file doesn't exist, returns an error.
func (GobFileAuthBackend) Close ¶
func (b GobFileAuthBackend) Close()
Close cleans up the backend. Currently a no-op for gobfiles.
func (GobFileAuthBackend) DeleteUser ¶
func (b GobFileAuthBackend) DeleteUser(username string) error
DeleteUser removes a user, raising ErrDeleteNull if that user was missing.
func (GobFileAuthBackend) SaveUser ¶
func (b GobFileAuthBackend) SaveUser(user UserData) error
SaveUser adds a new user, replacing one with the same username, and saves a gob file.
func (GobFileAuthBackend) User ¶
func (b GobFileAuthBackend) User(username string) (user UserData, e error)
User returns the user with the given username. Error is set to ErrMissingUser if user is not found.
func (GobFileAuthBackend) Users ¶
func (b GobFileAuthBackend) Users() (us []UserData, e error)
Users returns a slice of all users.
type MemAuthBackend ¶
type MemAuthBackend struct {
// contains filtered or unexported fields
}
MemAuthBackend stores user data and the location of the gob file.
func NewMemAuthBackend ¶
func NewMemAuthBackend() (b MemAuthBackend, e error)
NewMemAuthBackend initializes a new backend by loading a map of users from a file. If the file doesn't exist, returns an error.
func (MemAuthBackend) Close ¶
func (b MemAuthBackend) Close()
Close cleans up the backend. Currently a no-op for gobfiles.
func (MemAuthBackend) DeleteUser ¶
func (b MemAuthBackend) DeleteUser(username string) error
DeleteUser removes a user, raising ErrDeleteNull if that user was missing.
func (MemAuthBackend) SaveUser ¶
func (b MemAuthBackend) SaveUser(user UserData) error
SaveUser adds a new user, replacing one with the same username, and saves a gob file.
func (MemAuthBackend) User ¶
func (b MemAuthBackend) User(username string) (user UserData, e error)
User returns the user with the given username. Error is set to ErrMissingUser if user is not found.
func (MemAuthBackend) Users ¶
func (b MemAuthBackend) Users() (us []UserData, e error)
Users returns a slice of all users.
type MongodbAuthBackend ¶
type MongodbAuthBackend struct {
// contains filtered or unexported fields
}
MongodbAuthBackend stores database connection information.
func NewMongoAuthBackend ¶
func NewMongoAuthBackend(mongoURL string, database string) (b MongodbAuthBackend, e error)
NewMongodbBackend initializes a new backend. Be sure to call Close() on this to clean up the mongodb connection. Example:
backend = httpauth.MongodbAuthBackend("mongodb://127.0.0.1/", "auth")
defer backend.Close()
func (MongodbAuthBackend) Close ¶
func (b MongodbAuthBackend) Close()
Close cleans up the backend once done with. This should be called before program exit.
func (MongodbAuthBackend) DeleteUser ¶
func (b MongodbAuthBackend) DeleteUser(username string) error
DeleteUser removes a user. ErrNotFound is returned if the user isn't found.
func (MongodbAuthBackend) SaveUser ¶
func (b MongodbAuthBackend) SaveUser(user UserData) error
SaveUser adds a new user, replacing if the same username is in use.
func (MongodbAuthBackend) User ¶
func (b MongodbAuthBackend) User(username string) (user UserData, e error)
User returns the user with the given username. Error is set to ErrMissingUser if user is not found.
func (MongodbAuthBackend) Users ¶
func (b MongodbAuthBackend) Users() (us []UserData, e error)
Users returns a slice of all users.
type Role ¶
type Role int
Role represents an interal role. Roles are essentially a string mapped to an integer. Roles must be greater than zero.
type SQLAuthBackend ¶
type SQLAuthBackend struct {
// contains filtered or unexported fields
}
SQLAuthBackend database and database connection information.
func NewSQLAuthBackend ¶
func NewSQLAuthBackend(driverName, dataSourceName string) (b SQLAuthBackend, e error)
NewSQLAuthBackend initializes a new backend by testing the database connection and making sure the storage table exists. The table is called goauth.
Returns an error if connecting to the database fails, pinging the database fails, or creating the table fails.
This uses the databases/sql package to open a connection. Its parameters should match the sql.Open function. See http://golang.org/pkg/database/sql/#Open for more information.
Be sure to import "database/sql" and your driver of choice. If you're not using sql for your own purposes, you'll need to use the underscore to import for side effects; see http://golang.org/doc/effective_go.html#blank_import.
func (SQLAuthBackend) Close ¶
func (b SQLAuthBackend) Close()
Close cleans up the backend by terminating the database connection.
func (SQLAuthBackend) DeleteUser ¶
func (b SQLAuthBackend) DeleteUser(username string) error
DeleteUser removes a user, raising ErrDeleteNull if that user was missing.
func (SQLAuthBackend) SaveUser ¶
func (b SQLAuthBackend) SaveUser(user UserData) (err error)
SaveUser adds a new user, replacing one with the same username.
func (SQLAuthBackend) User ¶
func (b SQLAuthBackend) User(username string) (user UserData, e error)
User returns the user with the given username. Error is set to ErrMissingUser if user is not found.
func (SQLAuthBackend) Users ¶
func (b SQLAuthBackend) Users() (us []UserData, e error)
Users returns a slice of all users.
type UserData ¶
type UserData struct {
Name string `bson:"Name"`
Email string `bson:"Email"`
Hash []byte `bson:"Hash"`
Role string `bson:"Role"`
}
UserData represents a single user. It contains the users username, email, and role as well as a hash of their username and password. When creating users, you should not specify a hash; it will be generated in the Register and Update functions.
Source Files
Directories