auth

Documentation

Overview

Package auth deals with authentication and authorization against topics

Index

• Constants
• Variables
• func AllowedRole(role Role) bool
• func AllowedTopicPattern(username string) bool
• func AllowedUsername(username string) bool
• type Auther
• type Grant
• type Manager
• type Permission
• type Role
• type SQLiteAuth
  • func NewSQLiteAuth(filename string, defaultRead, defaultWrite bool) (*SQLiteAuth, error)
  • func (a *SQLiteAuth) AddUser(username, password string, role Role) error
  • func (a *SQLiteAuth) AllowAccess(username string, topicPattern string, read bool, write bool) error
  • func (a *SQLiteAuth) Authenticate(username, password string) (*User, error)
  • func (a *SQLiteAuth) Authorize(user *User, topic string, perm Permission) error
  • func (a *SQLiteAuth) ChangePassword(username, password string) error
  • func (a *SQLiteAuth) ChangeRole(username string, role Role) error
  • func (a *SQLiteAuth) DefaultAccess() (read bool, write bool)
  • func (a *SQLiteAuth) RemoveUser(username string) error
  • func (a *SQLiteAuth) ResetAccess(username string, topicPattern string) error
  • func (a *SQLiteAuth) User(username string) (*User, error)
  • func (a *SQLiteAuth) Users() ([]*User, error)
• type User

Constants

const (
	PermissionRead  = Permission(1)
	PermissionWrite = Permission(2)
)

Permissions to a topic

const (
	RoleAdmin     = Role("admin")
	RoleUser      = Role("user")
	RoleAnonymous = Role("anonymous")
)

User roles

const (
	Everyone = "*"
)

Everyone is a special username representing anonymous users

Variables

var (
	ErrUnauthenticated = errors.New("unauthenticated")
	ErrUnauthorized    = errors.New("unauthorized")
	ErrInvalidArgument = errors.New("invalid argument")
	ErrNotFound        = errors.New("not found")
)

Error constants used by the package

Functions

func AllowedRole

func AllowedRole(role Role) bool

AllowedRole returns true if the given role can be used for new users

func AllowedTopicPattern

func AllowedTopicPattern(username string) bool

AllowedTopicPattern returns true if the given topic pattern is valid; this includes the wildcard character (*)

func AllowedUsername

func AllowedUsername(username string) bool

AllowedUsername returns true if the given username is valid

Types

type Auther

type Auther interface {
	// Authenticate checks username and password and returns a user if correct. The method
	// returns in constant-ish time, regardless of whether the user exists or the password is
	// correct or incorrect.
	Authenticate(username, password string) (*User, error)

	// Authorize returns nil if the given user has access to the given topic using the desired
	// permission. The user param may be nil to signal an anonymous user.
	Authorize(user *User, topic string, perm Permission) error
}

Auther is a generic interface to implement password-based authentication and authorization

type Grant

type Grant struct {
	TopicPattern string // May include wildcard (*)
	AllowRead    bool
	AllowWrite   bool
}

Grant is a struct that represents an access control entry to a topic

type Manager

type Manager interface {
	// AddUser adds a user with the given username, password and role. The password should be hashed
	// before it is stored in a persistence layer.
	AddUser(username, password string, role Role) error

	// RemoveUser deletes the user with the given username. The function returns nil on success, even
	// if the user did not exist in the first place.
	RemoveUser(username string) error

	// Users returns a list of users. It always also returns the Everyone user ("*").
	Users() ([]*User, error)

	// User returns the user with the given username if it exists, or ErrNotFound otherwise.
	// You may also pass Everyone to retrieve the anonymous user and its Grant list.
	User(username string) (*User, error)

	// ChangePassword changes a user's password
	ChangePassword(username, password string) error

	// ChangeRole changes a user's role. When a role is changed from RoleUser to RoleAdmin,
	// all existing access control entries (Grant) are removed, since they are no longer needed.
	ChangeRole(username string, role Role) error

	// AllowAccess adds or updates an entry in th access control list for a specific user. It controls
	// read/write access to a topic. The parameter topicPattern may include wildcards (*).
	AllowAccess(username string, topicPattern string, read bool, write bool) error

	// ResetAccess removes an access control list entry for a specific username/topic, or (if topic is
	// empty) for an entire user. The parameter topicPattern may include wildcards (*).
	ResetAccess(username string, topicPattern string) error

	// DefaultAccess returns the default read/write access if no access control entry matches
	DefaultAccess() (read bool, write bool)
}

Manager is an interface representing user and access management

type Permission

type Permission int

Permission represents a read or write permission to a topic

type Role

type Role string

Role represents a user's role, either admin or regular user

type SQLiteAuth

type SQLiteAuth struct {
	// contains filtered or unexported fields
}

SQLiteAuth is an implementation of Auther and Manager. It stores users and access control list in a SQLite database.

func NewSQLiteAuth

func NewSQLiteAuth(filename string, defaultRead, defaultWrite bool) (*SQLiteAuth, error)

NewSQLiteAuth creates a new SQLiteAuth instance

func (*SQLiteAuth) AddUser

func (a *SQLiteAuth) AddUser(username, password string, role Role) error

AddUser adds a user with the given username, password and role. The password should be hashed before it is stored in a persistence layer.

func (*SQLiteAuth) AllowAccess

func (a *SQLiteAuth) AllowAccess(username string, topicPattern string, read bool, write bool) error

AllowAccess adds or updates an entry in th access control list for a specific user. It controls read/write access to a topic. The parameter topicPattern may include wildcards (*).

func (*SQLiteAuth) Authenticate

func (a *SQLiteAuth) Authenticate(username, password string) (*User, error)

Authenticate checks username and password and returns a user if correct. The method returns in constant-ish time, regardless of whether the user exists or the password is correct or incorrect.

func (*SQLiteAuth) Authorize

func (a *SQLiteAuth) Authorize(user *User, topic string, perm Permission) error

Authorize returns nil if the given user has access to the given topic using the desired permission. The user param may be nil to signal an anonymous user.

func (*SQLiteAuth) ChangePassword

func (a *SQLiteAuth) ChangePassword(username, password string) error

ChangePassword changes a user's password

func (*SQLiteAuth) ChangeRole

func (a *SQLiteAuth) ChangeRole(username string, role Role) error

ChangeRole changes a user's role. When a role is changed from RoleUser to RoleAdmin, all existing access control entries (Grant) are removed, since they are no longer needed.

func (*SQLiteAuth) DefaultAccess

func (a *SQLiteAuth) DefaultAccess() (read bool, write bool)

DefaultAccess returns the default read/write access if no access control entry matches

func (*SQLiteAuth) RemoveUser

func (a *SQLiteAuth) RemoveUser(username string) error

RemoveUser deletes the user with the given username. The function returns nil on success, even if the user did not exist in the first place.

func (*SQLiteAuth) ResetAccess

func (a *SQLiteAuth) ResetAccess(username string, topicPattern string) error

ResetAccess removes an access control list entry for a specific username/topic, or (if topic is empty) for an entire user. The parameter topicPattern may include wildcards (*).

func (*SQLiteAuth) User

func (a *SQLiteAuth) User(username string) (*User, error)

User returns the user with the given username if it exists, or ErrNotFound otherwise. You may also pass Everyone to retrieve the anonymous user and its Grant list.

func (*SQLiteAuth) Users

func (a *SQLiteAuth) Users() ([]*User, error)

Users returns a list of users. It always also returns the Everyone user ("*").

type User

type User struct {
	Name   string
	Hash   string // password hash (bcrypt)
	Role   Role
	Grants []Grant
}

User is a struct that represents a user