ginAuth

README

ginAuth

ginAuth is a simple, sessionless, encrypted cookie based authentication middleware for the Gin Web Framework!

External Packages

ginAuth uses a few external packages to accomplish it's goal:

• Beego - Configuration - this package is used to load values from config files.
• Gorilla Web Toolkit - Secure Cookie - we use the secure cookie package to encode and decode the cookie data.

Getting Started

A quick overview of the package. The package is very small and very documented so don't fear to read over it.

Global Values

These values can be set:

	CookieName string                       // the name of the cookie that will be used, default: "token"
	ConfigPath string                       // path to config file, default: ""
	ConfigType string                       // type of config file, default: "ini"
	Prefix string                           // the key in ctx.Keys[] to use, default: ""
	HashKey []byte                          // hash key for securecookie
	BlockKey []byte                         // block key for securecookie
	Expiration int64                        // time until the cookie expires in seconds, default: 604800
	Unauthorized func(ctx *gin.Context)     // function called if user is not authorized
	Authorized func(ctx *gin.Context)       // function called if user is authorized
	SecureCookie *securecookie.SecureCookie // global secure cookie object

Creating Encryption Keys

The package is mostly ready to go out of the box except for the fact that you must include a HashKey and a BlockKey.

From the Gorilla docs:

The hashKey is required, used to authenticate the cookie value using HMAC. It is recommended to use a key with 32 or 64 bytes.

The blockKey is optional, used to encrypt the cookie value -- set it to nil to not use encryption. If set, the length must correspond to the block size of the encryption algorithm. For AES, used by default, valid lengths are 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.

Luckily Gorilla provides a function to easily deal with this:

HashKey = securecookie.GenerateRandomKey(64)
BlockKey = securecookie.GenerateRandomKey(32)

Of course you will not want to random new keys every time you run your server.

Configuration File Attributes

There are two ways to change the values of the module, one is to to simply set them as you would any other global. The other is to load values from a config file. The following fields are recognized:

• cookiename - loads to the CookieName global
• prefix - loads to the Prefix global
• hashkey - loads to the HashKey global - expected to be a hexideciamal representation of a byte array.
• blockkey - loads to the BlockKey global - expected to be a hexideciamal representation of a byte array.
• expiration - loads to the Expiration global

Methods

There are three methods you need to be aware of in order to get stuff done:

1. ginAuth.Use() - this method is used whenever you use the Gin's Use() when setting up routes and groups, and you want it to use authentication.
2. ginAuth.Login(ctx *gin.Context, extra map[string]string) - this method is used to log in the user. The first parameter is the current context, and the second is a map of strings of data to set on the cookie. There are a few reserved indexes: ip, hash, and expiration. It will return an error if you try to use any of those indexes.
3. ginAuth.Logout(ctx *gin.Context) - simply pass in the current context and it'll remove the cookie from the user.

Documentation

Index

• Variables
• func Check(ctx *gin.Context) error
• func Login(ctx *gin.Context, extra map[string]string) error
• func Logout(ctx *gin.Context)
• func Use(ctx *gin.Context)

Variables

var (
	CookieName   string                     // the name of the cookie that will be used, default: "token"
	ConfigPath   string                     // path to config file, default: ""
	ConfigType   string                     // type of config file, default: "ini"
	Prefix       string                     // the key in ctx.Keys[] to use, default: ""
	HashKey      []byte                     // hash key for securecookie
	BlockKey     []byte                     // block key for securecookie
	Expiration   int64                      // time until the cookie expires in seconds, default: 604800
	Unauthorized func(ctx *gin.Context)     // function called if user is not authorized
	Authorized   func(ctx *gin.Context)     // function called if user is authorized
	SecureCookie *securecookie.SecureCookie // global secure cookie object
)

set our global package variables

Functions

func Check

func Check(ctx *gin.Context) error

checks for our token cookie, decodes it, and determines if it is valid the encrypted cookie data set in Login() will be set to the current context as well

func Login

func Login(ctx *gin.Context, extra map[string]string) error

handles the login process the first param is a map of strings that will be added to the cookie data before encryption and will be able to be recovered when Check() is called

func Logout

func Logout(ctx *gin.Context)

removes our token cookie, sets the context to: not logged in

func Use

func Use(ctx *gin.Context)

gin middleware handler call this on your groups that require authentication