steranko

README

Steranko 🔐

Website Authentication/Authorization for Go

This project is a work-in-progress, and should NOT be used by ANYONE, for ANY PURPOSE, under ANY CIRCUMSTANCES. It is GUARANTEED to blow up your computer, send your cat into an infinite loop, and combine your hot and cold laundry into a single cycle.

Steranko is an embeddable library that manages user authentication, and authorization. You can configure it at run time (or compile time) to meet your specific project needs.

To use Steranko, you have to implement two tiny interfaces in your code, then wire Steranko's handlers into your HTTP server.

s := steranko.New(userService, steranko.Conig{
    Tokens: "cookie:auth",
    PasswordSchema: `{"type":"string", "minLength":20}`
})

s.Register(echo)

Project Goals

• Create a configurable, open source authentication/authorization system in Go.

• Hashed passwords using bcrypt

• Automatically upgrade password encryption cost on signin.

• Lock out user accounts after N failed attempts.

• Maintain security with JWT tokens

• Password strength checking (via JSON-Schema extensions)

• Password vulnerability via HaveIBeenPwned API.

Possible future additions

• Middleware tracks and blocks malicious users

  • Errors (like 404, and 500) have an associated number of points.
  • Track points per user/ip address with leaky bucket algorithm
  • Block users with a certain number of points
  • Ban users/ip addresses for repeated policy violations
  • Admin console allows tweaking of rules, reinstatement of banned accounts.

• Identify malicious users with a (relatively) invisible CAPTCHA system

  • Track javascript events during signup (keyup, keydown, mousemove, click)
  • Track timing of events. They must not be too fast, or too consistent.
  • Something to prevent requests from being forwarded to an actual human.
  • Math problems?
  • Geolocation.

Pull Requests Welcome

Steranko is a work in progress, and will benefit from your experience reports, use cases, and contributions. If you have an idea for making this library better, send in a pull request. We're all in this together! 🔐

Documentation

Index

• Constants
• func Middleware(factory Factory) echo.MiddlewareFunc
• type Config
• type Context
  • func (ctx *Context) Authorization() (jwt.Claims, error)
• type Factory
• type KeyService
• type RequestPasswordResetResponse
• type RequestPasswordResetTransaction
• type SigninResponse
• type SigninTransaction
• type Steranko
  • func New(userService UserService, keyService KeyService, config Config) *Steranko
  • func (s *Steranko) ApproveRequest(ctx echo.Context) error
  • func (s *Steranko) Authenticate(username string, password string, user User) error
  • func (s *Steranko) CreateCertificate(ctx echo.Context, user User) error
  • func (s *Steranko) Middleware(next echo.HandlerFunc) echo.HandlerFunc
  • func (s *Steranko) PasswordSchema() *schema.Schema
  • func (s *Steranko) PostPasswordToken(ctx echo.Context) error
  • func (s *Steranko) PostPasswordUpdate(ctx echo.Context) error
  • func (s *Steranko) SignIn(ctx echo.Context) error
  • func (s *Steranko) SignOut(ctx echo.Context) error
  • func (s *Steranko) ValidatePassword(password string) error
• type UpdatePasswordResponse
• type UpdatePasswordTransaction
• type User
• type UserService

Constants

const CodeForbidden = 403

CodeForbidden is the HTTP status code of an unaccepted authentication.

const CodeUnauthorized = 401

CodeUnauthorized is the HTTP status code for an authentication failure error.

Functions

func Middleware

func Middleware(factory Factory) echo.MiddlewareFunc

Middleware is a standalone middleware that works for multi-tenant environments, where you may need to use a factory to load the specific steranko settings depending on the domain being called.

Types

type Config

type Config struct {
	Token          string        `json:"token"`          // Where to store authentication tokens.  Valid values are HEADER (default value) or COOKIE
	PasswordSchema schema.Schema `json:"passwordSchema"` // JSON-encoded schema for password validation rules.
}

type Context

type Context struct {
	echo.Context
	// contains filtered or unexported fields
}

Context extends the echo context with an authenticated JWT Token.

func (*Context) Authorization

func (ctx *Context) Authorization() (jwt.Claims, error)

type Factory

type Factory interface {

	// Steranko retrieves the correct instance to use
	// for this domain or returns an error
	Steranko(ctx echo.Context) (*Steranko, error)
}

Factory is used in multi-tenant environments to locate the steranko instance that will be used (based on the context)

type KeyService

type KeyService interface {
	NewJWTKey() (string, any)
	FindJWTKey(*jwt.Token) (any, error)
}

type RequestPasswordResetResponse

type RequestPasswordResetResponse struct {
}

type RequestPasswordResetTransaction

type RequestPasswordResetTransaction struct {
	Username string `json:"username" form:"userame"` // public username of the person requesting the reset.
}

type SigninResponse

type SigninResponse struct {
	Username     string
	JWT          string
	ErrorMessage string
	Error        error
}

SigninResponse includes all the information returned by Steranko after a signin request.

type SigninTransaction

type SigninTransaction struct {
	Username      string `json:"username"      form:"username"`      // public username for this person
	Password      string `json:"password"      form:"password"`      // private (hashed?) password for this person
	TwoFactorCode string `json:"twoFactorCode" form:"twoFactorCode"` // [Optional] 2FA code to send to the 2FA plugin
}

SigninTransaction includes all of the information that MUST be posted to Sterenko in order to sign in to the system.

type Steranko

type Steranko struct {
	UserService    UserService           // Service that provides CRUD operations on Users
	KeyService     KeyService            // Service that generates/retrieves encryption keys used in JWT signatures.
	Config         Config                // Configuration options for this library
	PasswordHasher plugin.PasswordHasher // PasswordHasher uses a one-way encryption to obscure stored passwords.
	PasswordRules  []plugin.PasswordRule // PasswordRules provide rules for enforcing password complexity
	// contains filtered or unexported fields
}

Steranko contains all required configuration information for this library.

func New

func New(userService UserService, keyService KeyService, config Config) *Steranko

New returns a fully initialized Steranko instance, with HandlerFuncs that support all of your user authentication and authorization needs.

func (*Steranko) ApproveRequest

func (s *Steranko) ApproveRequest(ctx echo.Context) error

ApproveRequest applies filtering rules to requests and blocks any that should not be allowed.

func (*Steranko) Authenticate

func (s *Steranko) Authenticate(username string, password string, user User) error

Authenticate verifies a username/password combination.

func (*Steranko) CreateCertificate

func (s *Steranko) CreateCertificate(ctx echo.Context, user User) error

CreateCertificate creates a new JWT token for the provided user.

func (*Steranko) Middleware

func (s *Steranko) Middleware(next echo.HandlerFunc) echo.HandlerFunc

Middleware wraps the original echo context with the Steranko context.

func (*Steranko) PasswordSchema

func (s *Steranko) PasswordSchema() *schema.Schema

PasswordSchema returns the schema.Schema for validating passwords

func (*Steranko) PostPasswordToken

func (s *Steranko) PostPasswordToken(ctx echo.Context) error

PostPasswordToken implements the http.HandlerFunc signature, and should be wired in to your REST API to allow users to tell the server that they forgot their password. This should initiate some way for the system to send them a one time token to create a new password.

func (*Steranko) PostPasswordUpdate

func (s *Steranko) PostPasswordUpdate(ctx echo.Context) error

PostPasswordUpdate implements the http.HandlerFunc signature, and should be wired in to your REST API to allow users to update their passwords.

func (*Steranko) SignIn

func (s *Steranko) SignIn(ctx echo.Context) error

SigniI implements the echo.HandlerFunc, and can be used directly in your REST API, or can be wrapped by your own custom function if you want to extend its functionality. If the signin is successful it automatically sets the "Authorization" cookie in the user's browser.

func (*Steranko) SignOut

func (s *Steranko) SignOut(ctx echo.Context) error

SignOut implements the echo.HandlerFunc, and can be used directly in your REST API, or can be wrapped by your own custom function.

func (*Steranko) ValidatePassword

func (s *Steranko) ValidatePassword(password string) error

ValidatePassword checks a password against the requirements in the Config structure.

type UpdatePasswordResponse

type UpdatePasswordResponse struct {
}

type UpdatePasswordTransaction

type UpdatePasswordTransaction struct {
	Username    string `json:"username"    form:"username"`
	OldPassword string `json:"oldPassword" form:"oldPassword"`
	NewPassword string `json:"newPassword" form:"newPassword"`
}

type User

type User interface {
	GetUsername() string // Returns the username of the User
	GetPassword() string // Returns the password of the User

	SetUsername(username string)   // Sets the username of the User
	SetPassword(ciphertext string) // Sets the password of the User
	Claims() jwt.Claims            // Returns all claims (permissions) that this user has.
}

User interface wraps all of the functions that Steranko needs to authorize a user of the system. This is done so that Steranko can be retrofitted on to your existing data objects. Just implement this interface, and a CRUD service, and you're all set.

type UserService

type UserService interface {

	// New creates a newly initialized User that is ready to use
	New() User

	// Load retrieves a single User from the database
	Load(username string, user User) error

	// Save inserts/updates a single User in the database
	Save(user User, comment string) error

	// Delete removes a single User from the database
	Delete(user User, comment string) error

	// RequestPasswordReset handles the application-specific details of
	// delivering a password reset message to the user.
	RequestPasswordReset(user User) error

	// NewClaims generates an empty object that meets the jwt.Claims any
	NewClaims() jwt.Claims

	// Close cleans up any connections opened by the service.
	Close()
}

UserService wraps all of the functions that must be provided to Steranko by your application. This API matches the presto.Service API very closely, so it should be possible to wrap an existing presto service to serve Steranko, too.