auth

README

auth

A simple (but opinionated) Golang authentication library with a very simple interface (below). You can use this library to pull in core authentication functionality (minting tokens, validating tokens, & registering) to your application quickly and easily.

type Auth interface {
	Register(user User, password string) error
	GetToken(email string, password string, reqPermissions Permissions) (token string, err error)
	Validate(token string) (*Claims, error)
}

A gRPC microservice wrapping this interface is in progress and can be found at suyashkumar/auth-grpc.

You only need to provide a database connectionString and signingKey, and everything else is taken care of for you including:

• table and database setup (including uniqueness constraints and useful indicies)
• hashing passwords using bcrypt on register
• comparing hashed passwords on login
• validation of new user fields like "Email" (TBD)
• encoding and extraction of key fields stored in the JSON Web Token (JWT)
• ensuring that a token's requested permissions does not exceed the user's maximum permission level

A minimal example is below:

a, _ := auth.NewAuthenticator(db_string, signing_key)

u := auth.User{
	UUID:               uuid.NewV4(),
	Email:              "test@test.com",
	MaxPermissionLevel: auth.PERMISSIONS_USER,
}

// Register a new user
a.Register(u, "password")

// Login as user
token, err := a.GetToken(u.Email, "password", auth.PERMISSIONS_USER)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("JWT Token: %s\n\n", token)

// Validate the user's token
claims, _ := a.Validate(token)
fmt.Printf("%+v", claims)

Documentation

Index

• Constants
• Variables
• type Authenticator
  • func NewAuthenticator(dbConnection string, signingKey []byte) (Authenticator, error)
  • func NewAuthenticatorFromGORM(db *gorm.DB, signingKey []byte) (Authenticator, error)
• type Claims
• type DatabaseHandler
  • func NewDatabaseHandler(dbConnection string) (DatabaseHandler, error)
  • func NewDatabaseHandlerFromGORM(db *gorm.DB) (DatabaseHandler, error)
• type GetTokenOpts
• type Permissions
  • func (p *Permissions) Scan(value interface{}) error
  • func (p Permissions) Value() (driver.Value, error)
• type TokenData
• type User

Constants

const (
	PERMISSIONS_API   = 0
	PERMISSIONS_USER  = 1
	PERMISSIONS_ADMIN = 2
)

These permission levels are ORDERED lowest to highest

const DefaultMaxIdleConns = 5

DefaultMaxIdleConns represents the default maximum idle connections to the db

const DefaultTTL = time.Duration(2.88e13)

DefaultTTL represents the default time to live for a newly issued token in nanoseconds, in this case 8 hours

Variables

var ErrorExceededMaxPermissionLevel = errors.New(
	"you're requesting a token permission level that exceeds this user's maximum permission level",
)

ErrorExceededMaxPermissionLevel indicates that a requested op exceeded the maximum permission level

var ErrorNoConnectionString = errors.New("A connection string must be specified on the first call to Get")

ErrorNoConnectionString indicates no connection string was provided

var ErrorValidatingToken = errors.New("problem validating token")

ErrorValidatingToken indicates issues validating the provided token

Types

type Authenticator

type Authenticator interface {
	Register(user *User, password string) error
	GetToken(email string, password string, opts *GetTokenOpts) (token string, err error)
	Validate(token string) (*Claims, error)
}

Authenticator exposes the minimal set of operations needed for authentication

func NewAuthenticator

func NewAuthenticator(dbConnection string, signingKey []byte) (Authenticator, error)

NewAuthenticator returns a newly initialized Authenticator

func NewAuthenticatorFromGORM

func NewAuthenticatorFromGORM(db *gorm.DB, signingKey []byte) (Authenticator, error)

NewAuthenticatorFromGORM returns a newly init'd Authenticator from a *gorm.DB

type Claims

type Claims struct {
	UserUUID    string    `json:"user_uuid"`
	Permissions int64     `json:"permissions"`
	Email       string    `json:"email"`
	Data        TokenData `json:"data"`
	jwt.StandardClaims
}

Claims represents data that are encoded into an authentication token

type DatabaseHandler

type DatabaseHandler interface {
	// GetUser gets a user from the database that matches constraints on the input user
	GetUser(u User) (User, error)
	// UpsertUser updates a user (if input user UUID matches one in the db) or inserts a user
	UpsertUser(u User) error
	// GetDB returns the *gorm.DB instance used by this handler
	GetDB() *gorm.DB
}

DatabaseHandler abstracts away common persistence operations needed for this package

func NewDatabaseHandler

func NewDatabaseHandler(dbConnection string) (DatabaseHandler, error)

NewDatabaseHandler initializes and returns a new DatabaseHandler

func NewDatabaseHandlerFromGORM

func NewDatabaseHandlerFromGORM(db *gorm.DB) (DatabaseHandler, error)

NewDatabaseHandlerFromGORM initializes and returns a DatabaseHandler from a supplied *gorm.DB connection

type GetTokenOpts

type GetTokenOpts struct {
	RequestedPermissions Permissions
	TimeToLive           time.Duration
	Data                 TokenData
}

type Permissions

type Permissions int64

Permissions represents different permission levels that can be encoded in a token or attached to a user

func (*Permissions) Scan

func (p *Permissions) Scan(value interface{}) error

Scan assigns a value from a database driver

func (Permissions) Value

func (p Permissions) Value() (driver.Value, error)

Value returns a driver value to be used in a db

type TokenData

type TokenData map[string]string

type User

type User struct {
	UUID               uuid.UUID `sql:"type:uuid;"`
	Email              string    `gorm:"unique_index"`
	HashedPassword     string
	FirstName          string
	LastName           string
	MaxPermissionLevel Permissions
	CreatedAt          time.Time
	UpdatedAt          time.Time
	DeletedAt          time.Time `sql:"default:NULL"`
}

User represents a generic User that Suyash expects in his projects. TODO: generalize