README
¶
rex.auth
Package auth provides session-based authentication middleware for the Rex router. It uses secure cookie sessions to maintain authentication state and supports storing custom user state in the session.
Installation
go get -u github.com/abiiranathan/rex
Basic usage:
// First, register your user type for session storage
auth.Register(User{})
// Create the middleware with authentication key
authMiddleware := auth.Cookie(auth.CookieConfig{
KeyPairs: [][]byte{[]byte("your-32-byte-auth-key")},
ErrorHandler: func(c *rex.Context) error {
return c.Status(http.StatusUnauthorized).JSON(map[string]string{
"error": "Unauthorized",
})
},
})
// Use the middleware in your router
router := rex.NewRouter()
router.Use(authMiddleware)
Login example:
router.Post("/login", func(c *rex.Context) error {
user := &User{ID: 1, Name: "John"}
if err := auth.SetAuthState(c, user); err != nil {
return err
}
return c.JSON(user)
})
Access authenticated user:
router.Get("/me", func(c *rex.Context) error {
state, authenticated := auth.GetAuthState(c)
if !authenticated {
return c.Status(http.StatusUnauthorized)
}
user := state.(*User)
return c.JSON(user)
})
Logout example:
router.Post("/logout", func(c *rex.Context) error {
return auth.ClearAuthState(c)
})
Security Notes:
- Cookie sessions are encrypted and authenticated using the provided key pairs
- HttpOnly and SameSite=Strict are enforced for security
- Default session duration is 24 hours
- Use cryptographically secure random bytes for key pairs
- For production, use https://pkg.go.dev/crypto/rand to generate keys
Key Generation Example:
key := make([]byte, 32)
if _, err := rand.Read(key); err != nil {
panic(err)
}
For key rotation, you can provide multiple key pairs:
authMiddleware := auth.Cookie(auth.CookieConfig{
KeyPairs: [][]byte{
[]byte("new-32-byte-auth-key"),
[]byte("new-32-byte-encrypt-key"),
[]byte("old-32-byte-auth-key"),
[]byte("old-32-byte-encrypt-key"),
},
// ... other config
})
Custom cookie options:
authMiddleware := auth.Cookie(auth.CookieConfig{
KeyPairs: [][]byte{[]byte("your-32-byte-auth-key")},
Options: &sessions.Options{
Path: "/",
Domain: "example.com",
MaxAge: 3600,
Secure: true,
},
// ... other config
})
Skip authentication for specific routes:
authMiddleware := auth.Cookie(auth.CookieConfig{
KeyPairs: [][]byte{[]byte("your-32-or-64-byte-auth-key")},
SkipAuth: func(req *http.Request) bool {
return req.URL.Path == "/login" || req.URL.Path == "/signup"
},
// ... other config
})
It also provides middleware for BasicAuth, JWT auth. Oauth2 support is coming soon.
Documentation
¶
Overview ¶
Package auth provides session-based authentication middleware for the Rex router. It uses secure cookie sessions to maintain authentication state and supports storing custom user state in the session. It also provide JWT and BasicAuth middleware. View the README for more information.
Index ¶
- Variables
- func BasicAuth(username, password string, realm ...string) rex.Middleware
- func ClearAuthState(c *rex.Context) error
- func Cookie(sessionName string, config CookieConfig) rex.Middleware
- func CookieAuthSkipped(r *http.Request) bool
- func CookieValue(c *rex.Context) (state any)
- func CreateJWTToken(secret string, payload any, exp time.Duration) (string, error)
- func InitializeCookieStore(keyPairs [][]byte, userType any)
- func JWT(secret string, skipFunc func(c *rex.Context) bool) rex.Middleware
- func JWTAuthSkipped(r *http.Request) bool
- func JwtClaims(req *http.Request) (jwt.MapClaims, error)
- func SetAuthState(c *rex.Context, state any) error
- func VerifyJWToken(secret, tokenString string) (jwt.MapClaims, error)
- type CookieConfig
Constants ¶
This section is empty.
Variables ¶
var ErrNotInitialized = errors.New("auth: Store not initialized, call auth.InitializeCookieStore first")
Functions ¶
func BasicAuth ¶
func BasicAuth(username, password string, realm ...string) rex.Middleware
Basic Auth middleware. If the username and password are not correct, a 401 status code is sent. The realm is the realm to display in the login box. Default is "Restricted".
func ClearAuthState ¶
ClearAuthState deletes authentication state.
func Cookie ¶
func Cookie(sessionName string, config CookieConfig) rex.Middleware
Cookie creates a new authentication middleware with the given configuration. Keys are defined in pairs to allow key rotation, but the common case is to set a single authentication key and optionally an encryption key.
You MUST register the type of state you want to store in the session by calling auth.Register or gob.Register before using this middleware. Access the session with c.Get(auth.SessionKey). It will be nil if not logged in.
func CookieAuthSkipped ¶ added in v1.0.3
Returns true if JWT authentication was skipped.
func CookieValue ¶ added in v1.1.0
CookieValue returns the auth state for this request or nil if not logged in.
func CreateJWTToken ¶
CreateToken creates a new JWT token with the given payload and expiry duration. JWT is signed with the given secret key using the HMAC256 algorithm.
func InitializeCookieStore ¶ added in v1.0.0
InitializeCookieStore initializes cookie store with the provided secret/encryption key pairs. Keys are defined in pairs to allow key rotation, but the common case is to set a single authentication key and optionally an encryption key.
The first key in a pair is used for authentication and the second for encryption. The encryption key can be set to nil or omitted in the last pair, but the authentication key is required in all pairs.
It is recommended to use an authentication key with 32 or 64 bytes. The encryption key, if set, must be either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 modes.
userType is the struct instance that is registered with the gob encoder.
func JWT ¶
JWT creates a JWT middleware with the given secret and options. If skipFunc returns true, authentication is skipped.
func JWTAuthSkipped ¶ added in v1.0.3
Returns true if JWT authentication was skipped.
func JwtClaims ¶ added in v1.0.5
Returns the payload from the request or nil if non-exists. Should be called inside the handler when JWT verification is complete.
func SetAuthState ¶
SetAuthState stores user state for this request. It could be the user object, userId or anything serializable into a cookie. This is typically called following user login.
func VerifyJWToken ¶
VerifyJWToken verifies the given JWT token with the secret key. Returns the claims if the token is valid, otherwise an error. The token is verified using the HMAC256 algorithm. The default claims are stored in the "payload" key and the expiry time in the "exp" key.
Types ¶
type CookieConfig ¶
type CookieConfig struct {
// Cookie options.
// Default: HttpOnly=true, SameSite=Strict(always), MaxAge=24hrs, Domain=/,secure=false
Options *sessions.Options
// Skip authentication for certain requests
SkipAuth func(c *rex.Context) bool
// Called when authentication fails
ErrorHandler func(c *rex.Context) error
}
Source Files