echo basic auth
Basic Auth middleware with constant time equality checks and optional IP whitelisting for Echo v5.
CIDRs are supported for IP whitelisting as well
import echobasicauth "github.com/etkecc/go-echo-basic-auth/v2"
The v2 module targets Echo v5 (github.com/labstack/echo/v5); the v1 line stays on Echo v4.
Usage
plaintext:
auth := &echobasicauth.Auth{Login: "test", Password: "test", IPs: []string{"127.0.0.1", "10.0.0.0/24"}}
e.Use(echobasicauth.NewMiddleware(auth))
// or you can use echobasicauth.NewValidator(auth) if you want to define the middleware yourself
bcrypt:
auth := &echobasicauth.Auth{Login: "test", Password: "$2a$10$XajjQvNhvvRt5GSeFk1xFeyqRrsxkhBkUiQeg0dt.wU1qD4aFDcga", IPs: []string{"127.0.0.1", "10.0.0.0/24"}}
(and bcrypted Login supported as well, just in case)
With several Auth values, a request passes when any one of them accepts the credentials; an entry
with an empty IPs list accepts its login from any IP.
NewMiddleware() with an empty auth list returns a middleware that rejects every request.
IP whitelist
Plain IP entries are normalized before matching, so ::1 and 0:0:0:0:0:0:0:1 (and upper/lowercase hex)
are equivalent. CIDRs are supported as well.
By default, IP rules match the transport peer and client headers are ignored:
// no e.IPExtractor set (the default)
e.Use(echobasicauth.NewMiddleware(auth))
Proxied deployments can opt in to checking the original client instead of the proxy address:
e.IPExtractor = echo.ExtractIPFromXFFHeader()
Security note: this puts the IP gate on X-Forwarded-For. Echo's default extractor trusts
loopback, link-local, and private peers, so any client that reaches the app directly from a private
IP (office, VPN, same-host proxy) can set X-Forwarded-For to an allowlisted IP and pass the IP
check; with the bare extractor the IP gate provides no protection against such clients. When
combining the IP allowlist with an extractor, restrict the trust to your proxy range and disable
the broad defaults:
proxyRange, _ := net.ParseCIDR("10.0.0.0/8") // your proxy range
e.IPExtractor = echo.ExtractIPFromXFFHeader(
echo.TrustPrivateNet(false),
echo.TrustLinkLocal(false),
echo.TrustIPRange(proxyRange),
)
// keep the default TrustLoopback(true) only when your proxy sits on 127.0.0.1
SetIPs applies a new allowlist atomically for concurrent request processing; the exported IPs
field is for config-time population, and reassigning it from another goroutine is a data race.
Invalid entries never open the whitelist: an all-invalid list denies everybody, and Validate
reports the typos, so they can fail the boot instead of the check:
if err := auth.Validate(); err != nil {
return err
}
Failed attempts are logged at WARN with the anonymized client address through Echo's *slog.Logger;
the default handler prints INFO and above, so they show up without configuration. Swap the logger to change
the format or raise the threshold:
e.Logger = slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelError}))
IP validation without credentials
auth := &echobasicauth.Auth{IPs: []string{"127.0.0.1", "10.0.0.0/24"}}
if auth.AllowedIP(echobasicauth.ClientIP(c)) {
// IP is allowed
}
Use ClientIP when feeding the allowlist: it canonicalizes the address and returns an empty string for
unparseable ones, which the allowlist denies.