Overview
The Basic Authentication middleware provides a robust and flexible way to secure your Iris web applications. It supports various user storage methods, including in-memory lists, files, and databases, and offers advanced features such as password encryption, custom error handling, and session expiration.
Installation
To use the basicauth middleware, you need to import it in your Iris application:
import "github.com/kataras/iris/v12/middleware/basicauth"
Features
Authentication Function
The core of the middleware is the Allow field, which is a function with the following signature:
func(ctx iris.Context, username, password string) (any, bool)
This function is responsible for validating the username and password. It returns a user object (or any other type) and a boolean indicating whether the authentication was successful.
User Structure (Helper)
While the middleware does not require a specific user structure, you can use a helper structure to manage user data more conveniently. Here is an example of a user structure:
type User struct {
Username string `json:"username"`
Password string `json:"password"`
Roles []string `json:"roles"`
}
In-Memory User Storage
You can store users in memory using a slice of user structures. This is useful for small applications or testing purposes.
var users = []User{
{"admin", "admin", []string{"admin"}},
{"kataras", "kataras_pass", []string{"manager", "author"}},
{"george", "george_pass", []string{"member"}},
{"john", "john_pass", []string{}},
}
Basic Setup
To set up the middleware, create an instance of basicauth.Options and pass it to basicauth.New.
opts := basicauth.Options{
Realm: basicauth.DefaultRealm,
MaxAge: 10 * time.Minute,
GC: basicauth.GC{
Every: 2 * time.Hour,
},
Allow: basicauth.AllowUsers(users),
}
auth := basicauth.New(opts)
Using a File for User Storage
You can load users from a file (JSON or YAML). This is useful for applications where user data changes frequently.
auth := basicauth.Load("users.yml")
BCRYPT Option
The BCRYPT option allows you to use bcrypt for password hashing. Bcrypt is a password hashing function designed to be computationally intensive to resist brute-force attacks. It is widely used for securely storing passwords.
auth := basicauth.Load("users.yml", basicauth.BCRYPT)
You can also use the BCRYPT option with other user fetching methods, such as in-memory or database storage.
Using a Database for User Storage
For more dynamic user management, you can validate users against a database. Here is an example of how to set up the middleware using a MySQL database:
package main
import (
"context"
"database/sql"
"fmt"
"os"
"github.com/kataras/iris/v12"
"github.com/kataras/iris/v12/middleware/basicauth"
_ "github.com/go-sql-driver/mysql"
)
type User struct {
ID int64 `db:"id" json:"id"`
Username string `db:"username" json:"username"`
Password string `db:"password" json:"password"`
Email string `db:"email" json:"email"`
}
func (u User) GetUsername() string {
return u.Username
}
func (u User) GetPassword() string {
return u.Password
}
func main() {
dsn := fmt.Sprintf("%s:%s@tcp(%s:3306)/%s?parseTime=true&charset=utf8mb4&collation=utf8mb4_unicode_ci",
getenv("MYSQL_USER", "user_myapp"),
getenv("MYSQL_PASSWORD", "dbpassword"),
get
env("MYSQL_HOST", "localhost"),
getenv("MYSQL_DATABASE", "myapp"),
)
db, err := connect(dsn)
if err != nil {
panic(err)
}
// Validate a user from database.
allowFunc := func(ctx iris.Context, username, password string) (any, bool) {
user, err := db.getUserByUsernameAndPassword(context.Background(), username, password)
return user, err == nil
}
opts := basicauth.Options{
Realm: basicauth.DefaultRealm,
ErrorHandler: basicauth.DefaultErrorHandler,
Allow: allowFunc,
}
auth := basicauth.New(opts)
app := iris.New()
app.Use(auth)
app.Get("/", index)
app.Listen(":8080")
}
func index(ctx iris.Context) {
user, _ := ctx.User().GetRaw()
// user is a type of main.User
ctx.JSON(user)
}
Custom Error Handling
You can customize the error handling behavior by setting the ErrorHandler field in the basicauth.Options.
opts := basicauth.Options{
ErrorHandler: func(ctx iris.Context, err error) {
ctx.StatusCode(iris.StatusUnauthorized)
ctx.JSON(iris.Map{"error": "Unauthorized"})
},
}
Session Expiration
The middleware supports session expiration. You can set the MaxAge field to specify the duration after which the user must re-authenticate.
opts := basicauth.Options{
MaxAge: 10 * time.Minute,
}
Garbage Collection
To clear expired users from memory, you can set the GC field.
opts := basicauth.Options{
GC: basicauth.GC{
Every: 2 * time.Hour,
},
}
Testing Handlers with BasicAuth Middleware
To test handlers that use the BasicAuth middleware, you can use the
httptest
package provided by Iris. Here is an example of how to test a handler:
package main_test
import (
"testing"
"github.com/kataras/iris/v12"
"github.com/kataras/iris/v12/httptest"
"github.com/kataras/iris/v12/middleware/basicauth"
)
func TestIndexHandler(t *testing.T) {
opts := basicauth.Options{
Realm: basicauth.DefaultRealm,
Allow: basicauth.AllowUsers(users),
}
auth := basicauth.New(opts)
app := iris.New()
app.Use(auth)
app.Get("/", index)
e := httptest.New(t, app)
// Test with valid credentials
e.GET("/").WithBasicAuth("admin", "admin").Expect().Status(httptest.StatusOK).JSON().Object().Value("username").Equal("admin")
// Test with invalid credentials
e.GET("/").WithBasicAuth("admin", "wrongpassword").Expect().Status(httptest.StatusUnauthorized)
}
Example
Here is a complete example that demonstrates how to set up the middleware with in-memory user storage:
package main
import (
"time"
"github.com/kataras/iris/v12"
"github.com/kataras/iris/v12/middleware/basicauth"
)
type User struct {
Username string `json:"username"`
Password string `json:"password"`
Roles []string `json:"roles"`
}
var users = []User{
{"admin", "admin", []string{"admin"}},
{"kataras", "kataras_pass", []string{"manager", "author"}},
{"george", "george_pass", []string{"member"}},
{"john", "john_pass", []string{}},
}
func main() {
opts := basicauth.Options{
Realm: basicauth.DefaultRealm,
MaxAge: 10 * time.Minute,
GC: basicauth.GC{
Every: 2 * time.Hour,
},
Allow: basicauth.AllowUsers(users),
}
auth := basicauth.New(opts)
app := iris.New()
app.Use(auth)
app.Get("/", index)
app.Listen(":8080")
}
func index(ctx iris.Context) {
user, _ := ctx.User().GetRaw()
ctx.JSON(user)
}
Conclusion
The Basic Authentication middleware provides a comprehensive solution for securing your Iris web applications. With support for various user storage methods, advanced features like password encryption and custom error handling, and easy integration, it is a powerful tool for developers.
Top comments (0)