Skip to main content
Version: Next

BasicAuth

Basic Authentication middleware for Fiber that provides HTTP basic auth. It calls the next handler for valid credentials and returns 401 Unauthorized or a custom response for missing or invalid credentials.

The default unauthorized response includes the header WWW-Authenticate: Basic realm="Restricted", charset="UTF-8", sets Cache-Control: no-store, and adds a Vary: Authorization header.

Signatures

func New(config Config) fiber.Handler
func UsernameFromContext(c fiber.Ctx) string

Examples

Import the middleware package:

import (
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/middleware/basicauth"
)

Once your Fiber app is initialized, choose one of the following approaches:

// Provide a minimal config
app.Use(basicauth.New(basicauth.Config{
Users: map[string]string{
// "doe" hashed using SHA-256
"john": "{SHA256}eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=",
// "123456" hashed using bcrypt
"admin": "$2a$10$gTYwCN66/tBRoCr3.TXa1.v1iyvwIF7GRBqxzv7G.AHLMt/owXrp.",
},
}))

// Or extend your config for customization
app.Use(basicauth.New(basicauth.Config{
Users: map[string]string{
// "doe" hashed using SHA-256
"john": "{SHA256}eZ75KhGvkY4/t0HfQpNPO1aO0tk6wd908bjUGieTKm8=",
// "123456" hashed using bcrypt
"admin": "$2a$10$gTYwCN66/tBRoCr3.TXa1.v1iyvwIF7GRBqxzv7G.AHLMt/owXrp.",
},
Realm: "Forbidden",
Authorizer: func(user, pass string, c fiber.Ctx) bool {
// custom validation logic
return (user == "john" || user == "admin")
},
Unauthorized: func(c fiber.Ctx) error {
return c.SendFile("./unauthorized.html")
},
}))

Password hashes

Passwords must be supplied in pre-hashed form. The middleware detects the hashing algorithm from a prefix:

  • "{SHA512}" or "{SHA256}" followed by a base64-encoded digest
  • standard bcrypt strings beginning with $2

If no prefix is present, the value is interpreted as a SHA-256 digest encoded in hex or base64. Plaintext passwords are rejected.

Generating SHA-256 and SHA-512 passwords

Create a digest, encode it in base64, and prefix it with {SHA256} or {SHA512} before adding it to Users:

# SHA-256
printf 'secret' | openssl dgst -binary -sha256 | base64

# SHA-512
printf 'secret' | openssl dgst -binary -sha512 | base64

Include the prefix in your config:

Users: map[string]string{
"john": "{SHA256}K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=",
"admin": "{SHA512}vSsar3708Jvp9Szi2NWZZ02Bqp1qRCFpbcTZPdBhnWgs5WtNZKnvCXdhztmeD2cmW192CF5bDufKRpayrW/isg==",
}

Config

PropertyTypeDescriptionDefault
Nextfunc(fiber.Ctx) boolNext defines a function to skip this middleware when it returns true.nil
Usersmap[string]stringUsers maps usernames to hashed passwords (e.g. bcrypt, {SHA256}).map[string]string{}
RealmstringRealm is a string to define the realm attribute of BasicAuth. The realm identifies the system to authenticate against and can be used by clients to save credentials."Restricted"
CharsetstringCharset sent in the WWW-Authenticate header, so clients know how credentials are encoded."UTF-8"
HeaderLimitintMaximum allowed length of the Authorization header. Requests exceeding this limit are rejected.8192
Authorizerfunc(string, string, fiber.Ctx) boolAuthorizer defines a function to check the credentials. It will be called with a username, password, and the current context and is expected to return true or false to indicate approval.nil
Unauthorizedfiber.HandlerUnauthorized defines the response body for unauthorized responses.nil

Default Config

var ConfigDefault = Config{
Next: nil,
Users: map[string]string{},
Realm: "Restricted",
Charset: "UTF-8",
HeaderLimit: 8192,
Authorizer: nil,
Unauthorized: nil,
}