auth

Documentation

Overview

Package auth is a database wrapper used to permitt, defining a db interface, avoiding integration tests using a real mongodb instance. A mockdb struct is defined in the database_test.go file to implement offline tests. In production this file is a simple wrapper around mgo package.

Index

• func CloseGlobalDbClient()
• func SetGlobalDbClient(database Database)
• type AuthenticateRequestArg
• type AuthenticateResponseArg
• type Database
• type DbArgs
• type Level
• type Login
  • func (t *Login) Login(args *LoginRequestArg, response *LoginResponseArg) error
  • func (t *Login) Logout(args *LogoutRequestArg, response *LogoutResponseArg) error
• type LoginRequestArg
• type LoginResponseArg
• type LogoutRequestArg
• type LogoutResponseArg
• type Mongodb
  • func MgoSession(args *DbArgs) (*Mongodb, error)
  • func (d *Mongodb) Close()
  • func (d *Mongodb) Copy() Database
  • func (d *Mongodb) EnsureMongodbIndexes() error
  • func (d *Mongodb) GetSession(token []byte) (*Session, error)
  • func (d *Mongodb) GetUser(username string) (*User, error)
  • func (d *Mongodb) RemoveAllSessions() error
  • func (d *Mongodb) RemoveSession(token []byte) error
  • func (d *Mongodb) RemoveUser(username string) error
  • func (d *Mongodb) SetSession(session *Session) error
  • func (d *Mongodb) SetUser(user *User) error
• type Permissions
• type RemoveUserRequestArg
• type Session
• type SessionAuth
  • func (s *SessionAuth) Authenticate(args *AuthenticateRequestArg, response *AuthenticateResponseArg) error
  • func (s *SessionAuth) KickOutAllSessions(args *AuthenticateRequestArg, response *VoidResponseArg) error
  • func (s *SessionAuth) RemoveUser(args *RemoveUserRequestArg, response *VoidResponseArg) error
  • func (s *SessionAuth) UpsertUser(args *UpserUserRequestArg, response *VoidResponseArg) error
  • func (s *SessionAuth) UserInfo(args *AuthenticateRequestArg, response *UserInfoResponseArg) error
• type UpserUserRequestArg
• type User
• type UserInfoResponseArg
• type VoidResponseArg

Functions

func CloseGlobalDbClient

func CloseGlobalDbClient()

CloseGlobalDbClient closes the global assigned client.

func SetGlobalDbClient

func SetGlobalDbClient(database Database)

SetGlobalDbClient must be called to set the global db client, that implements the Database interface, to be used by RPC exposed functions. This function must be always invoked before proceeding registering other fucntions.

Types

type AuthenticateRequestArg

type AuthenticateRequestArg struct {
	Token []byte // the authentication token.
}

AuthenticateRequestArg define the RPC request struct

type AuthenticateResponseArg

type AuthenticateResponseArg struct {
	Username     string    // the session related username;
	LastSeenTime time.Time // last connection from the user.
}

AuthenticateResponseArg the returned auth structure.

type Database

type Database interface {
	// db client related functions
	Copy() Database // retain the db client in a multi-coroutine environment;
	Close()         // release the client;
	// user behaviour
	GetUser(string) (*User, error) // gets a user struct from an argument username;
	SetUser(*User) error           // creates a new user in the db;
	RemoveUser(string) error       // remove an user from the db;
	// session behaviour
	GetSession([]byte) (*Session, error) // search for a session in the db;
	SetSession(*Session) error           // insert a session in the db;
	RemoveSession([]byte) error          // remove an existing session;
	RemoveAllSessions() error            // remove all sessions in the db.
}

Database an interface defining a generic db, package targeting, implementation.

type DbArgs

type DbArgs struct {
	Addresses []string // cluster addresses in form <addr>:<port>;
	User      string   // authentication username;
	Password  string   // authentication password;
	AuthDb    string   // the auth db.
}

DbArgs is the exposed arguments required by each database interface implementing structs.

type Level

type Level uint

Level type describe available user's permission levels.

const (
	LevelUser  Level = iota // common user, will not be able to administer a service;
	LevelAdmin Level = iota // administrator will be able to perform maintainance tasks.
)

Common levels used to identify tipical figures that can access a service, this list can be expanded.

type Login

type Login int

Login the RPC required custom type.

func (*Login) Login

func (t *Login) Login(args *LoginRequestArg, response *LoginResponseArg) error

Login RPC exposed functions it's create a session token after verifying that the username and password are already registered in the system.

func (*Login) Logout

func (t *Login) Logout(args *LogoutRequestArg, response *LogoutResponseArg) error

Logout RPC exposed function logout a user, starting from a valid active session and remove all opened session related to that user.

type LoginRequestArg

type LoginRequestArg struct {
	Username string // the authenticating username;
	Password string // plaintext password.
}

LoginRequestArg define the RPC request struct

type LoginResponseArg

type LoginResponseArg struct {
	Token []byte // the session token to be used, from now on, to communicate with server.
}

LoginResponseArg the returned login structure having the user assigned session token.

type LogoutRequestArg

type LogoutRequestArg struct {
	Token []byte // the session token used to identify the user.
}

LogoutRequestArg is the request passed to logout the user's sessions.

type LogoutResponseArg

type LogoutResponseArg struct {
	Invalidated []byte
}

LogoutResponseArg is the structure used to return the list of invalidated sessions.

type Mongodb

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

Mongodb database, wrapping mgo session structure.

func MgoSession

func MgoSession(args *DbArgs) (*Mongodb, error)

MgoSession get a new session starting from the standard args structure.

func (*Mongodb) Close

func (d *Mongodb) Close()

Close releases the session client.

func (*Mongodb) Copy

func (d *Mongodb) Copy() Database

Copy the internal session to permitt multi corutine usage.

func (*Mongodb) EnsureMongodbIndexes

func (d *Mongodb) EnsureMongodbIndexes() error

EnsureMongodbIndexes assign mongodb indexes to the right collections, this should be done only the first time the collection is created.

func (*Mongodb) GetSession

func (d *Mongodb) GetSession(token []byte) (*Session, error)

GetSession check if a session is available and still valid veryfing time of last seen contact against pre-defined timeout value.

func (*Mongodb) GetUser

func (d *Mongodb) GetUser(username string) (*User, error)

GetUser get user strucutre from a given username, if something wrong returns an error.

func (*Mongodb) RemoveAllSessions

func (d *Mongodb) RemoveAllSessions() error

RemoveAllSessions remove all active and not active sessions from the database instance.

func (*Mongodb) RemoveSession

func (d *Mongodb) RemoveSession(token []byte) error

RemoveSession remove a session from the db.

func (*Mongodb) RemoveUser

func (d *Mongodb) RemoveUser(username string) error

RemoveUser remove an existing user from the db.

func (*Mongodb) SetSession

func (d *Mongodb) SetSession(session *Session) error

SetSession add a session data to the database.

func (*Mongodb) SetUser

func (d *Mongodb) SetUser(user *User) error

SetUser adds an argument User struct to the database, returns an error if something went wrong.

type Permissions

type Permissions struct {
	SuperAdmin bool             `bson:"superadmin,omitempty"` // special user that have all permissions on all services;
	Services   map[string]Level `bson:"services"`             // permissions organised per service, the "all" can be used for generalised behaviour.
}

Permissions struct describe user's permisisons on a service basis, if the user is a sper-admin a special bool flag will be setted.

type RemoveUserRequestArg

type RemoveUserRequestArg struct {
	Token    []byte // the authentication token;
	Username string // the user to be removed.
}

RemoveUserRequestArg request for remove an existing user.

type Session

type Session struct {
	Token        []byte        `bson:"token"`       // token for the session;
	Username     string        `bson:"username"`    // username associated to session;
	LoginTime    time.Time     `bson:"login_ts"`    // timestamp of login time for this session;
	LastSeenTime time.Time     `bson:"lastseen_ts"` // last call to an API done by the user;
	TimeToLive   time.Duration `bson:"timetolive"`  // time of validity of the session.
}

Session contains information about loggedin for authenticated users.

type SessionAuth

type SessionAuth int

SessionAuth RPC required custom type (using int arbitrarely).

func (*SessionAuth) Authenticate

func (s *SessionAuth) Authenticate(args *AuthenticateRequestArg, response *AuthenticateResponseArg) error

Authenticate RPC exposed functions verify a session token and returns the userid to authenticate user required operations.

func (*SessionAuth) KickOutAllSessions

func (s *SessionAuth) KickOutAllSessions(args *AuthenticateRequestArg, response *VoidResponseArg) error

KickOutAllSessions is an RPC exposed function that remove all active sessions from the authentication database.

func (*SessionAuth) RemoveUser

func (s *SessionAuth) RemoveUser(args *RemoveUserRequestArg, response *VoidResponseArg) error

RemoveUser is an RPC exposed function that removes an existing user from the authentication db.

func (*SessionAuth) UpsertUser

func (s *SessionAuth) UpsertUser(args *UpserUserRequestArg, response *VoidResponseArg) error

UpsertUser is an RPC exposed function used to add or update a user in the authentication database. If the user is not already present it'll be added, otherwise it will be updated. Only Super-Admins will be able to use this function.

func (*SessionAuth) UserInfo

func (s *SessionAuth) UserInfo(args *AuthenticateRequestArg, response *UserInfoResponseArg) error

UserInfo RPC exposed function verify a session token and returns the user associated data (from the User struct). Notice that this function will update the "last seen" time stamp as the Authenticate do.

type UpserUserRequestArg

type UpserUserRequestArg struct {
	Token []byte // the authentication token;
	User  User   // the user record to be updated.
}

UpserUserRequestArg request to upsert user data.

type User

type User struct {
	Username       string      `bson:"username"`           // user name;
	FullName       string      `bson:"fullname,omitempty"` // complete full name;
	HashedPassword []byte      `bson:"pwdhash"`            // hashed password;
	Email          string      `bson:"email,omitempty"`    // user's verified email;
	Permissions    Permissions `bson:"permissions"`        // the permissions associated to the user;
	IsDisabled     bool        `bson:"disabled"`           // user active (true) or not (false).
}

User struct identify a registered user to the service.

type UserInfoResponseArg

type UserInfoResponseArg struct {
	Username    string       // the session related username;
	FullName    string       // the user full name;
	Email       string       // the user email address;
	Permissions *Permissions // user associated permissions;
	LastSeen    time.Time    // last seen info.
}

UserInfoResponseArg the returned authenticated user data.

type VoidResponseArg

type VoidResponseArg struct{}

VoidResponseArg empty return value.