embiam

README

embiam

Embedded identity and access management

-- WHAT IS embiam? The idea is to embed IAM directly in your API server. Since IAM doesn't require much CPU power or RAM, it's obvious to combine the primary tasks in your APIS and IAM. Use embiam to make your IAM simpler, easier to maintain, and more efficient. Efficiency doesn't only lead to cost reduction on your cloud infrastructure but also to greener IT because it's using less energy. With higher efficiency you also improve your user's expericence because the reponse times shrink and your user's have a smoother and more reactive experince using your applications. #CodeGreenIT

-- HOW TO USE IT?

-- Checking identities Just embed embiam in your API code and use it to check username (we call it nick) and password. If the validation was successful, you get an identity token. Send it back to the client application. With this identity token the client application can validate further calls - without sending passwords around.

identityToken, err := embiam.CheckIdentity(credentials.Nick, credentials.Password, clientHost)

see example 1

-- Secure APIs with identity tokens After the authentication (with nick and password) the client application gets an identity token. This is used to validate the calls to your APIs. Before the actual task of the API is started, the identity token is checked. When the check was successful the actual task can be done, e.g. the data is fechted from the db or the item is added to the shopping basket.

if !embiam.IsIdentityTokenValid(requestBody.IdentityToken, clientHost) {
	http.Error(w, "", http.StatusForbidden)
	return
}

see example 1

-- Creating new nicks We call it nick instead of user because a nick describes also a machine, not only person. Nicks are generated and can't be choosen. So is the password. The procedure to provide a new identity with a new nick is as follows: 1. A nick token is generated. The nick token is valid for a certain time (e.g. 3 days - this is configured in conf.json). Usually the admin generates the token and sends it to the new user. newNickToken := embiam.GetNickToken()

2. The new user receives the nick token and uses it to get a new nick, a new password and a secret (to restore passwords). At the same time embiam saves the new nick in db (for password and secret embiam only stores hashes). The nick token is deleted.
   newNick := embiam.GenerateNewNick(nickToken)

Documentation

Index

• func CheckAuthIdentity(authValue string, validFor string) (identityTokenStruct, error)
• func CheckIdentity(nick, password, validFor string) (identityTokenStruct, error)
• func GenerateEntityToken() string
• func GenerateIdentityToken() string
• func GenerateNick() string
• func GeneratePassword(length int) string
• func Hash(original string) string
• func Initialize(aDb DbInterface)
• func IsAuthIdentityTokenValid(authValue string, validFor string) bool
• func IsIdentityTokenValid(identityToken string, validFor string) bool
• type ConfigurationStruct
• type DbFile
  • func (m DbFile) DeleteEntityToken(token string) error
  • func (m DbFile) DeleteFilesFromDirectory(dir string) error
  • func (m DbFile) EntityExists(nick string) bool
  • func (m *DbFile) Initialize()
  • func (m DbFile) ReadEntityByNick(nick string) (*Entity, error)
  • func (m DbFile) ReadEntityToken(token string) (*EntityToken, error)
  • func (m DbFile) SaveEntity(e *Entity) error
  • func (m DbFile) SaveEntityToken(et *EntityToken) error
• type DbInterface
• type DbTransient
  • func (m DbTransient) DeleteEntityToken(token string) error
  • func (m DbTransient) EntityExists(nick string) bool
  • func (m *DbTransient) Initialize()
  • func (m DbTransient) ReadEntityByNick(nick string) (*Entity, error)
  • func (m DbTransient) ReadEntityToken(token string) (*EntityToken, error)
  • func (m DbTransient) SaveEntity(e *Entity) error
  • func (m DbTransient) SaveEntityToken(et *EntityToken) error
• type Entity
  • func NewEntity(entityToken string) (Entity, string, string, error)
  • func (e Entity) Save() error
• type EntityToken
  • func NewEntityToken() EntityToken
  • func (et EntityToken) Delete() error
  • func (et EntityToken) Save() error

Functions

func CheckAuthIdentity

func CheckAuthIdentity(authValue string, validFor string) (identityTokenStruct, error)

CheckAuthIdentity checks nick and password and provides and identity token (for validFor)

func CheckIdentity

func CheckIdentity(nick, password, validFor string) (identityTokenStruct, error)

CheckIdentity checks nick and password and provides and identity token (for validFor)

func GenerateEntityToken

func GenerateEntityToken() string

GenerateEntityToken generates a valid entity token

func GenerateIdentityToken

func GenerateIdentityToken() string

GenerateIdentityToken generates a identity token

func GenerateNick

func GenerateNick() string

GenerateNick generates a nick

func GeneratePassword

func GeneratePassword(length int) string

GeneratePassword generates a password

func Hash

func Hash(original string) string

Hash calculates 'hash' for 'original' using bcrypt

func Initialize

func Initialize(aDb DbInterface)

Initialize prepares embiam

func IsAuthIdentityTokenValid

func IsAuthIdentityTokenValid(authValue string, validFor string) bool

IsAuthIdentityTokenValid checks if the identity token is valid, validFor contains information about the client, e.g. the IP address

func IsIdentityTokenValid

func IsIdentityTokenValid(identityToken string, validFor string) bool

IsIdentityTokenValid checks if the identity token is valid, validFor contains information about the client, e.g. the IP address

Types

type ConfigurationStruct

type ConfigurationStruct struct {
	Port                         string `json:"port"`
	EntityTokenValidityHours     int    `json:"entityTokenValidityHours"`
	IdentityTokenValiditySeconds int    `json:"identityTokenValiditySeconds"`
	MaxSignInAttempts            int    `json:"maxSignInAttempts"`
}

var Configuration ConfigurationStruct

type DbFile

type DbFile struct {
	EntityFilePath      string
	EntityTokenFilePath string
	DBPath              string
}

func (DbFile) DeleteEntityToken

func (m DbFile) DeleteEntityToken(token string) error

func (DbFile) DeleteFilesFromDirectory

func (m DbFile) DeleteFilesFromDirectory(dir string) error

func (DbFile) EntityExists

func (m DbFile) EntityExists(nick string) bool

func (*DbFile) Initialize

func (m *DbFile) Initialize()

func (DbFile) ReadEntityByNick

func (m DbFile) ReadEntityByNick(nick string) (*Entity, error)

func (DbFile) ReadEntityToken

func (m DbFile) ReadEntityToken(token string) (*EntityToken, error)

func (DbFile) SaveEntity

func (m DbFile) SaveEntity(e *Entity) error

func (DbFile) SaveEntityToken

func (m DbFile) SaveEntityToken(et *EntityToken) error

type DbInterface

type DbInterface interface {
	Initialize()
	ReadEntityByNick(nick string) (*Entity, error)
	EntityExists(nick string) bool
	SaveEntity(entity *Entity) error
	SaveEntityToken(entityToken *EntityToken) error
	ReadEntityToken(tokenoken string) (*EntityToken, error)
	DeleteEntityToken(token string) error
}

var Db DbInterface

*******************************************************************

Database (persistent storage)

*******************************************************************

type DbTransient

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

DbTransient - non-persistent database for testing and demonstration

func (DbTransient) DeleteEntityToken

func (m DbTransient) DeleteEntityToken(token string) error

func (DbTransient) EntityExists

func (m DbTransient) EntityExists(nick string) bool

func (*DbTransient) Initialize

func (m *DbTransient) Initialize()

func (DbTransient) ReadEntityByNick

func (m DbTransient) ReadEntityByNick(nick string) (*Entity, error)

func (DbTransient) ReadEntityToken

func (m DbTransient) ReadEntityToken(token string) (*EntityToken, error)

func (DbTransient) SaveEntity

func (m DbTransient) SaveEntity(e *Entity) error

func (DbTransient) SaveEntityToken

func (m DbTransient) SaveEntityToken(et *EntityToken) error

type Entity

type Entity struct {
	Nick                 string    `json:"nick"`
	PasswordHash         string    `json:"passwordHash"`
	SecretHash           string    `json:"secretHash"`
	Active               bool      `json:"active"`
	WrongPasswordCounter int       `json:"WrongPasswordCounter"`
	LastSignInAttempt    time.Time `json:"lastSignInAttempt"`
	LastSignIn           time.Time `json:"lastSignIn"`
	CreateTimeStamp      time.Time `json:"createTimeStamp"`
	UpdateTimeStamp      time.Time `json:"updateTimeStamp"`
}

*******************************************************************
	ENTITY

	The entity describes a person or device that needs
	authentication (and authorization). The entity is identified
	by the so called 'nick', which is similar to a username.
	The Entity also contains the hash of the password and hash
	of the secret. The secret is a second, much more complex,
	password and it is used to chance the password or to
	unlock the entity, after it was disabled, e.g. after
	multiple unsuccessful password entries.
*******************************************************************

Entity describes a user or a device

func NewEntity

func NewEntity(entityToken string) (Entity, string, string, error)

NewEntity creates a new entity using an entityToken

func (Entity) Save

func (e Entity) Save() error

Save uses the entity model to save 'e' persistently

type EntityToken

type EntityToken struct {
	Token      string
	ValidUntil time.Time
}

*******************************************************************

ENTITY TOKEN

Entity Tokens are use to create new entities. The administrator
creates an entity token and sends it to the new user. The new
user uses the entity token to create an new entity. After the
entity was created, the entity token is deleted.

*******************************************************************

func NewEntityToken

func NewEntityToken() EntityToken

NewEntityToken creates a new entity token (token itself and validity, comming from configuration)

func (EntityToken) Delete

func (et EntityToken) Delete() error

Delete the entity token from database

func (EntityToken) Save

func (et EntityToken) Save() error

Save the entity token to database