Documentation
¶
Overview ¶
Package auth provides authentication and authorization building blocks: a transport-neutral Principal carried in context, credential extraction from HTTP requests, a pluggable Verifier (token -> Principal), a built-in JWT verifier, and net/http middleware for authentication and role-based access control.
The Verifier seam keeps the middleware independent of the token format: the bundled JWTVerifier covers HMAC and RSA/ECDSA (and JWKS via a custom Keyfunc), but any Verifier — an opaque-token introspection client, a test stub — plugs in the same way.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BearerToken ¶
BearerToken extracts a token from an "Authorization: Bearer <token>" header. The scheme match is case-insensitive.
Types ¶
type JWTConfig ¶
type JWTConfig struct {
HMACSecret []byte
RSAPublicKeyPEM []byte
ECPublicKeyPEM []byte
// Keyfunc overrides the key sources above (e.g. JWKS). When set, ValidMethods
// should list the algorithms you accept.
Keyfunc jwt.Keyfunc
// ValidMethods restricts accepted "alg" values. Defaults are derived from the
// configured key source (HS*/RS*/ES*); set explicitly when using Keyfunc.
ValidMethods []string
// Issuer / Audience, when set, are validated against the token claims.
Issuer string
Audience string
// Leeway tolerates small clock skew on time-based claims.
Leeway time.Duration
// SubjectClaim names the principal-id claim (default "sub").
SubjectClaim string
// RolesClaim names the roles claim (default "roles"). Accepts a JSON array of
// strings or a single space-separated string.
RolesClaim string
}
JWTConfig configures the built-in JWT verifier. Exactly one key source must be set: HMACSecret, RSAPublicKeyPEM, ECPublicKeyPEM, or a custom Keyfunc (use the latter for JWKS — e.g. a keyfunc backed by a remote key set).
type JWTVerifier ¶
type JWTVerifier struct {
// contains filtered or unexported fields
}
JWTVerifier verifies JWTs and maps their claims to a Principal.
func NewJWTVerifier ¶
func NewJWTVerifier(cfg JWTConfig) (*JWTVerifier, error)
NewJWTVerifier builds a JWTVerifier from cfg.
type Middleware ¶
Middleware is standard net/http middleware (composes with router.Use).
func Authenticate ¶
func Authenticate(v Verifier, log *logger.Logger) Middleware
Authenticate extracts a bearer token, verifies it, and stores the resulting Principal in the request context. Requests without a valid token are rejected with 401. log may be nil.
func Optional ¶
func Optional(v Verifier) Middleware
Optional verifies a bearer token when present and stores the Principal, but never rejects the request. Downstream handlers use PrincipalFromContext (or RequireAuthenticated) to enforce access. An invalid token is ignored.
func RequireAuthenticated ¶
func RequireAuthenticated() Middleware
RequireAuthenticated rejects requests that carry no Principal with 401. Place it after Optional, or use Authenticate which both verifies and requires.
func RequireRole ¶
func RequireRole(roles ...string) Middleware
RequireRole rejects requests whose Principal lacks at least one of roles: 401 when unauthenticated, 403 when authenticated without a required role.
type Principal ¶
type Principal struct {
// Subject is the unique principal id (JWT "sub").
Subject string
// Roles are the principal's authorization roles.
Roles []string
// Claims carries the full, verified claim set for application use.
Claims map[string]any
}
Principal is the authenticated identity attached to a request context.
func PrincipalFromContext ¶
PrincipalFromContext returns the principal stored by the middleware, if any.
func (*Principal) HasAnyRole ¶
HasAnyRole reports whether the principal has at least one of roles. With no roles given it returns true (authentication alone suffices).
Source Files