Categorygithub.com/fabianwe/goauth
modulepackage
0.0.0-20170411162114-cd6c9c4ade81
Repository: https://github.com/fabianwe/goauth.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
20
Dependents
0
Files
1.8k SLOC

# README

goauth

Package goauth provides convinient functions to authenticate users, encrypt their passwords and create and check login sessions (via tokens).

The documentation of this package can be found on GoDoc.

License: MIT License

What is this package for

This package may help you if:

  • You wish to manage user sessions: A user logs in and stays logged in until his login session expires. This package creates a database and stores session keys in it. It helps you with the generation and validation of such keys. You can store them in a secure cookie for example. Currently supported for user sessions: MySQL, postgres, sqlite3 and redis.
  • Manage user accounts in a database: There are different ways to accomplish this, either by using a default scheme that is defined in this package our with your own scheme. This package takes care that user passwords are stored in a secure way using bcrypt or with onre more line of code scrypt. Supported storages: MySQL, postgres, sqlite3 and redis.

I wanted to develop some small Go web applications without a big framework or something like that but with user authentication and couldn't find a suitable and small library. So I've written this one by myself.

Current Version and Safety

User authentication and session management is very important and needs to be absolutely safe. I've written this package by myself and until now no one revised the code. If someone would do that I would be very happy!

The current release is version v0.5, I haven't really tested it in any project yet, but I'm going to do so. I will develop in a new branch v0.6 from now on and the master branch stays at version v0.5 for now. But I think there may be some changes I'll have to make once I really use this project, so I will merge v0.6 in the master pretty soon.

Please not that this package comes without any warranty: If you use it do it on your own risk.

Quickstart

Installation

Installation with go get github.com/FabianWe/goauth/ should do the trick. One important notice though: The bcrypt package still uses the old "golang.org/x/net/context" package. I tried to install it inside a docker container (so a "fresh" installation of Go) and it didn't work because the import can't be resolved in newer versions of Go. I tried even go tool fix -force context /go/src/golang.org/x/crypto/ (here is the problem). But the acme package uses a package from context that go fix can't fix... So in my docker installation I ended up simply removing the file (see Dockerfile). Of course this is not a suitable option. So you may have to install the old context package by checking out the project our something. I hope this issue resolves itself once the old imports are gone.

If you're planning to you sqlite (support for that should be out very soon) take care of the installation notice, I quote: "This package can be installed with the go get command

go get github.com/mattn/go-sqlite3

go-sqlite3 is cgo package. If you want to build your app using go-sqlite3, you need gcc. However, if you install go-sqlite3 with go install github.com/mattn/go-sqlite3, you don't need gcc to build your app anymore."

Where Do I Start?

The wiki of this project is a good starting point. It explains most of the basics. Also you should read the entation on GoDoc.

In order to work properly you need a good backend for your storage. There is an in memory implementation for user sessions, but this is not very efficient and also you loose all your data once you stop your program.

You should really use a database, such as MariadDB (or any other MySQL) or postgres. We also support sqlite3, but this is very slow for this stuff and so not a good choice. There is also a cached version with memcached with another backend (from v0.2 on). Since version v0.3 there is also a session handler using redis.

One important note: Since we use gorilla sessions you should take care of the advice in their docs: If you aren't using gorilla/mux, you need to wrap your handlers with context.ClearHandler as or else you will leak memory!

For example use

http.ListenAndServe(":8080", context.ClearHandler(http.DefaultServeMux))

Copyright Notices

Please find the copyright information on the wiki. goauth is distributed under the MIT License.

# Functions

CurrentTime returns the current type.
CurrentTimeKeyData creates a new SessionKeyData object with the current time.
DefaultTimeFromScanType is the default function to return database entries to a time.Time.
GenRandomBase64 returns a random base64 encoded string based on a random byte sequence of size n.
KeyInvalid checks if a key is invalid.
KeyValid checks if a key is still valid.
MySQLUserQueries provides queries to use with MySQL.
NewBcryptHandler creates a new PasswordHandler that uses bcrypt.
No description provided by the author
No description provided by the author
NewMemcachedSessionHandler returns a new MemcachedSessionHandler that uses parent as the main handler to query when a memcached lookup fails.
NewMySQLSessionController returns a new SessionController that uses a MySQL database.
NewMYSQLSessionHandler returns a new SQLSessionHandler that uses MySQL.
NewMySQLSessionTemplate returns a new MySQLSessionTemplate.
NewMySQLUserHandler returns a new handler that uses MySQL.
NewPostgresSessionController returns a new SessionController using postgres.
NewPostgresSessionHandler returns a new SQLSessionHandler using postgres.
NewPostgresSessionTemplate returns a new PostgresSessionTemplate.
NewPostgresUserHandler returns a new handler that uses postgres.
NewRedisSessionHandler creates a new RedisSessionHandler.
NewRedisUserHandler returns a new RedisUserHandler.
NewScryptHandler returns a new ScryptHandler that uses the defined parameters.
NewSessionController creates a new session controller given a SessionHandler, the size of the random byte slice If you use another key length or session name set the values after calling NewSessionController, i.e.
NewSessionKeyData creates a new SessionKeyData instance with the given values.
NewSQLite3SessionController returns a SessionController that uses sqlite3.
NewSQLite3SessionHandler returns a new SQLSessionHandler that uses sqlite3.
NewSQLite3SessionTemplate returns a new SQLite3SessionTemplate.
NewSQLite3UserHandler returns a new handler that uses sqlite3.
NewSQLSessionHandler compiles the query template with the given information.
NewSQLUserHandler returns a new SQLUserHandler given the queries and all the other information required.
PostgresUserQueries provides queries to use with postgres.
SQLite3UserQueries provides queries to use with sqlite3.

# Constants

DefaultCost is the default cost parameter for bcrypt.
DefaultKeyLength is the length of the random base 64 strings, it should be set in accordance with DefaultRandomByteLength.
DefaultPWLength is he default length of encrypted passwords.
DefaultRandomByteLength is the default length for random bytes array, this creates random base64 strings of length 64.
NoUserID is an user id that is returned if the user was not found or some error occurred.
RedisDateFormat is the format string that is used to format / parse date strings in redis.
SessionKey is the key to store the auth-key in a gorilla session.

# Variables

DefaultPWHandler is the default handler for password encryption / decription.
ErrInvalidKey is the error that will be returned if a key was found in the storage but the key is not valid anymore.
ErrKeyNotFound is the error that is returned whenever you try to lookup the information stored for a certain key but that key does not exist.
ErrNotAuthSession is the error that will be returned if a gorialla session does not have the SessionKey in session.Values.
ErrUserNotFound is an error that is used in the Validate function to signal that the user with the given username was not found.

# Structs

DefaultUserInformation is used to wrap the the information for a user in the default scheme.
BcryptHandler is a PasswordHandler that uses bcrypt.
This type implements the SessionHandler interface using an in memory map.
MemcachedSessionHandler is a SessionHandler that wraps another handler and queries memcached first and only performs a query on the wrapper handler when the memcached lookup failed.
MySQLSessionTemplate implements SQLSessionTemplate with MySQL queries.
PostgresSessionTemplate ist an implementation of SQLSessionTemplate for psotgres.
RedisSessionHandler is a session Handler using redis.
RedisUserHandler is a UserHandler that uses redis.
ScryptHandler is a PasswordHandler that uses scrypt.
SessionController uses a SessionHandler to query the storage and add additional functionality.
SessionKeyData type is used as a result in a key lookup.
SQLite3SessionTemplate is an implementation of SQLSessionTemplate using sqlite3 queries.
SQLSessionHandler is an implementation of SessionHandler that uses a predinfed set of SQL queries.
SQLUserHandler implements the UserHandler by executing queries as defined in an instance of SQLUserQueries.
SQLUserQueries stores several queries for working with users on SQL databases.

# Interfaces

PasswordHandler is an interface that knows three methods: Create a hash from a given (plaintext) password Compare a previously by this method generated hash and compare it to plaintext password.
SessionHandler is the interface to store and retrieve session keys and the associated SessionKeyData objects.
SQLSessionTemplate to generate queries for different SQL flavours such as MySQL or postgres.
UserHandler is an interface to deal with the management of users.
UserKeyType is a special type that is used for user keys.