basicauth

Documentation

Overview

Package basicauth provides HTTP Basic Authentication middleware for celeris.

The middleware parses the Authorization header, validates credentials via a user-supplied function, and stores the authenticated username in the context store under UsernameKey ("basicauth_username"). Failed authentication returns 401 with a WWW-Authenticate header.

One of Config.Validator, Config.ValidatorWithContext, or Config.Users is required; omitting all three panics at initialization.

Simple usage with a Users map (auto-generates a constant-time validator):

server.Use(basicauth.New(basicauth.Config{
    Users: map[string]string{
        "admin": "secret",
        "user":  "pass",
    },
}))

Custom validator with context access:

server.Use(basicauth.New(basicauth.Config{
    ValidatorWithContext: func(c *celeris.Context, user, pass string) bool {
        return checkDB(c, user, pass)
    },
    Realm: "API",
}))

Retrieving the Username

Use UsernameFromContext to retrieve the authenticated username from downstream handlers:

name := basicauth.UsernameFromContext(c) // reads UsernameKey from context store

ErrUnauthorized is the exported sentinel error (401) returned on authentication failure, usable with errors.Is for error handling in upstream middleware.

Index

• Constants
• Variables
• func New(config ...Config) celeris.HandlerFunc
• func UsernameFromContext(c *celeris.Context) string
• type Config

Examples

• New
• New (ContextValidator)
• New (Validator)

Constants

const UsernameKey = "basicauth_username"

UsernameKey is the context store key for the authenticated username.

Variables

var DefaultConfig = Config{
	Realm: "Restricted",
}

DefaultConfig is the default basic auth configuration.

var ErrUnauthorized = celeris.NewHTTPError(401, "Unauthorized")

ErrUnauthorized is returned when authentication fails.

Functions

func New

func New(config ...Config) celeris.HandlerFunc

New creates a basic auth middleware with the given config.

Example

package main

import (
	"github.com/goceleris/middlewares/basicauth"
)

func main() {
	// Simple static credentials with the Users map.
	_ = basicauth.New(basicauth.Config{
		Users: map[string]string{
			"admin": "secret",
			"user":  "password",
		},
	})
}

Example (ContextValidator)

package main

import (
	"github.com/goceleris/celeris"

	"github.com/goceleris/middlewares/basicauth"
)

func main() {
	// Context-aware validator for per-request auth decisions.
	_ = basicauth.New(basicauth.Config{
		ValidatorWithContext: func(c *celeris.Context, user, _ string) bool {
			tenant := c.Header("x-tenant")
			return tenant == "acme" && user == "admin"
		},
	})
}

Example (Validator)

package main

import (
	"github.com/goceleris/middlewares/basicauth"
)

func main() {
	// Custom validator for dynamic credential checking.
	_ = basicauth.New(basicauth.Config{
		Validator: func(user, pass string) bool {
			// Check against a database or external service.
			return user == "admin" && pass == "secret"
		},
	})
}

func UsernameFromContext

func UsernameFromContext(c *celeris.Context) string

UsernameFromContext returns the authenticated username from the context store. Returns an empty string if no username was stored (e.g., no auth or skipped).

Types

type Config

type Config struct {
	// Skip defines a function to skip this middleware for certain requests.
	Skip func(c *celeris.Context) bool

	// Validator checks credentials. Required if Users is nil -- panics if both are nil.
	Validator func(user, pass string) bool

	// ValidatorWithContext checks credentials with access to the request context.
	// Takes precedence over Validator when set. Useful for per-request auth decisions
	// (e.g., tenant-based authentication, IP-aware rate limiting within auth).
	ValidatorWithContext func(c *celeris.Context, user, pass string) bool

	// Users maps usernames to passwords. When set and Validator is nil,
	// a constant-time validator is auto-generated from this map.
	Users map[string]string

	// Realm is the authentication realm. Default: "Restricted".
	Realm string

	// ErrorHandler handles authentication failures.
	// Default: 401 with WWW-Authenticate header.
	ErrorHandler func(c *celeris.Context) error

	// SkipPaths lists paths to skip (exact match).
	SkipPaths []string
}

Config defines the basic auth middleware configuration.