authgo

README

authgo

authgo is an authentication library that makes it easy to add authentication to your webserver.

authgo is simple to setup and offers complete control of the HTML templates and stylesheets so your website can match your existing style and brand.

Getting Started

1. Get the library

go get aletheiaware.com/authgo

1. Create the Database.

// In a test environment use an In-Memory Database.
db := database.NewInMemoryDatabase()

// In production implement the Database interface to connect to your own database.
db := NewSqlDatabase()

1. Create the Email Validator.

// In a test environment use a mock verifier (code is always authtest.TEST_CHALLENGE)
ev := authtest.NewEmailVerifier()

// In production use an SMTP service to send the verification code.
ev := email.NewSmtpEmailVerifier("smtp-relay.gmail.com:25", "example.com", "noreply@example.com", templates.Lookup("email-verification.go.html"))

1. Create the Authenticator.

auth := authgo.NewAuthenticator(db, ev)

1. Attach the HTTP Handlers with the HTML templates.

handler.AttachAuthenticationHandlers(mux, auth, templates)

1. Add Authentication Checks to your HTTP Handlers.

mux.Handle("/greeter", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    account := auth.CurrentAccount(w, r)
    if account == nil {
        redirect.SignIn(w, r, r.URL.String())
        return
    }
    // Request is authorized, greet the user
    fmt.Fprintf(w, "Hello %s!", account.Username)
}))

Documentation

Index

• Constants
• Variables
• func CheckPasswordHash(hash, password []byte) bool
• func GeneratePasswordHash(password []byte) ([]byte, error)
• func MatchPasswords(password, confirmation []byte) error
• func NewCookie(name, value string, timeout time.Duration) *http.Cookie
• func NewSessionToken() (string, error)
• func ValidateEmail(email string) error
• func ValidatePassword(password []byte) error
• func ValidateUsername(username string) error
• type Account
• type Authenticator
  • func NewAuthenticator(db Database, ev EmailVerifier) Authenticator
• type Database
• type EmailVerifier

Constants

const (
	COOKIE_SIGN_IN          = "sign-in"
	COOKIE_SIGN_UP          = "sign-up"
	COOKIE_ACCOUNT_PASSWORD = "account-password"
	COOKIE_ACCOUNT_RECOVERY = "account-recovery"
)

const (
	MAXIMUM_EMAIL_LENGTH     = 320
	VERIFICATION_CODE_LENGTH = 8
)

const (
	MINIMUM_PASSWORD_LENGTH = 12
	MAXIMUM_PASSWORD_LENGTH = 50
)

const (
	MINIMUM_USERNAME_LENGTH = 3
	MAXIMUM_USERNAME_LENGTH = 100
)

const SESSION_TOKEN_LENGTH = 16

Variables

var (
	ErrCredentialsIncorrect      = errors.New("Incorrect Credentials")
	ErrEmailAlreadyRegistered    = errors.New("Email Already Registered")
	ErrUsernameAlreadyRegistered = errors.New("Username Already Registered")
	ErrEmailNotRegistered        = errors.New("Email Not Registered")
	ErrUsernameNotRegistered     = errors.New("Username Not Registered")
	ErrInvalidReferrer           = errors.New("Invalid Referrer")
)

var (
	ErrEmailTooLong               = errors.New("Email Too Long")
	ErrEmailInvalid               = errors.New("Invalid Email Address")
	ErrEmailVerificationIncorrect = errors.New("Incorrect Verification Code")
)

var (
	ErrPasswordTooShort    = errors.New("Password Too Short")
	ErrPasswordTooLong     = errors.New("Password Too Long")
	ErrPasswordsDoNotMatch = errors.New("Passwords Do Not Match")
)

var (
	ErrUsernameTooShort = errors.New("Username Too Short")
	ErrUsernameTooLong  = errors.New("Username Too Long")
	ErrUsernameInvalid  = errors.New("Username Invalid")
)

Functions

func CheckPasswordHash

func CheckPasswordHash(hash, password []byte) bool

func GeneratePasswordHash

func GeneratePasswordHash(password []byte) ([]byte, error)

func MatchPasswords

func MatchPasswords(password, confirmation []byte) error

func NewCookie

func NewCookie(name, value string, timeout time.Duration) *http.Cookie

func NewSessionToken

func NewSessionToken() (string, error)

func ValidateEmail

func ValidateEmail(email string) error

func ValidatePassword

func ValidatePassword(password []byte) error

func ValidateUsername

func ValidateUsername(username string) error

Types

type Account

type Account struct {
	ID              int64
	Email, Username string
	Created         time.Time
}

type Authenticator

type Authenticator interface {
	CurrentAccount(w http.ResponseWriter, r *http.Request) *Account
	NewAccount(string, string, []byte) (*Account, error)
	LookupAccount(string) (*Account, error)
	AuthenticateAccount(string, []byte) (*Account, error)
	LookupUsernameForEmail(string) (string, error)
	ChangePassword(string, []byte) error
	DeactivateAccount(*Account) error

	IsEmailVerified(string) bool
	SetEmailVerified(string, bool) error
	EmailVerifier() EmailVerifier

	SignUpSessionTimeout() time.Duration
	SetSignUpSessionTimeout(time.Duration)
	NewSignUpSessionCookie(string) *http.Cookie
	CurrentSignUpSession(*http.Request) (string, string, string, string, string, string)
	NewSignUpSession() (string, error)
	LookupSignUpSession(string) (string, string, string, string, string, bool)
	SetSignUpSessionIdentity(string, string, string) error
	SetSignUpSessionChallenge(string, string) error
	SetSignUpSessionReferrer(string, string) error
	SetSignUpSessionError(string, string)

	SignInSessionTimeout() time.Duration
	SetSignInSessionTimeout(time.Duration)
	NewSignInSessionCookie(string) *http.Cookie
	CurrentSignInSession(*http.Request) (string, string, bool, time.Time, string)
	NewSignInSession(string, bool) (string, error)
	LookupSignInSession(string) (string, bool, time.Time, string, bool)
	SetSignInSessionUsername(string, string) error
	SetSignInSessionAuthenticated(string, bool) error
	SetSignInSessionError(string, string)

	AccountPasswordSessionTimeout() time.Duration
	SetAccountPasswordSessionTimeout(time.Duration)
	NewAccountPasswordSessionCookie(string) *http.Cookie
	CurrentAccountPasswordSession(*http.Request) (string, string, string)
	NewAccountPasswordSession(string) (string, error)
	LookupAccountPasswordSession(string) (string, string, bool)
	SetAccountPasswordSessionError(string, string)

	AccountRecoverySessionTimeout() time.Duration
	SetAccountRecoverySessionTimeout(time.Duration)
	NewAccountRecoverySessionCookie(string) *http.Cookie
	CurrentAccountRecoverySession(*http.Request) (string, string, string, string, string)
	NewAccountRecoverySession() (string, error)
	LookupAccountRecoverySession(string) (string, string, string, string, bool)
	SetAccountRecoverySessionEmail(string, string) error
	SetAccountRecoverySessionUsername(string, string) error
	SetAccountRecoverySessionChallenge(string, string) error
	SetAccountRecoverySessionError(string, string)
}

func NewAuthenticator

func NewAuthenticator(db Database, ev EmailVerifier) Authenticator

type Database

type Database interface {
	Close() error

	CreateUser(string, string, []byte, time.Time) (int64, error)
	SelectUser(string) (int64, string, []byte, time.Time, error)
	SelectUsernameByEmail(string) (string, error)
	ChangePassword(string, []byte) (int64, error)
	DeactivateUser(string, time.Time) (int64, error)

	IsEmailVerified(string) (bool, error)
	SetEmailVerified(string, bool) (int64, error)

	CreateSignUpSession(string, time.Time) (int64, error)
	SelectSignUpSession(string) (string, string, string, string, string, time.Time, error)
	UpdateSignUpSessionError(string, string) (int64, error)
	UpdateSignUpSessionIdentity(string, string, string) (int64, error)
	UpdateSignUpSessionReferrer(string, string) (int64, error)
	UpdateSignUpSessionChallenge(string, string) (int64, error)

	CreateSignInSession(string, string, bool, time.Time) (int64, error)
	SelectSignInSession(string) (string, string, time.Time, bool, error)
	UpdateSignInSessionError(string, string) (int64, error)
	UpdateSignInSessionUsername(string, string) (int64, error)
	UpdateSignInSessionAuthenticated(string, bool) (int64, error)

	CreateAccountPasswordSession(string, string, time.Time) (int64, error)
	SelectAccountPasswordSession(string) (string, string, time.Time, error)
	UpdateAccountPasswordSessionError(string, string) (int64, error)

	CreateAccountRecoverySession(string, time.Time) (int64, error)
	SelectAccountRecoverySession(string) (string, string, string, string, time.Time, error)
	UpdateAccountRecoverySessionError(string, string) (int64, error)
	UpdateAccountRecoverySessionEmail(string, string) (int64, error)
	UpdateAccountRecoverySessionUsername(string, string) (int64, error)
	UpdateAccountRecoverySessionChallenge(string, string) (int64, error)
}

type EmailVerifier

type EmailVerifier interface {
	Verify(email, username string) (string, error)
}