ginAuth is a simple, sessionless, encrypted cookie based authentication middleware for the Gin Web Framework!
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.
A quick overview of the package. The package is very small and very documented so don't fear to read over it.
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
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.
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
There are three methods you need to be aware of in order to get stuff done:
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.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.ginAuth.Logout(ctx *gin.Context)
- simply pass in the current context and it'll remove the cookie from the user.