Documentation
¶
Overview ¶
Package auth provides JWT-based authentication and authorization middleware for vatel HTTP endpoints.
It is the recommended starting point for green-field projects. Wire it once globally (token decode) and per-endpoint (permission check):
cfg := &auth.Config{
Decoder: myJWTDecoder,
Authorizer: myAuthorizer,
}
v := vatel.NewVatel()
v.AddMiddleware(vatel.OnAuthentication, cfg.Middleware())
v.Add(
vatel.GET("/orders", ordersCtrl, cfg.RequirePerms(map[string]uint{"orders:read": 0})),
vatel.POST("/orders", createCtrl, cfg.RequirePerms(map[string]uint{"orders:write": 1})),
vatel.GET("/healthcheck", healthCtrl), // public — no RequirePerms
)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Authorizer ¶
Authorizer checks whether a token's permission bytes satisfy the required bit positions. This is the bitset-based permission model used by this package. Implement it via github.com/axkit/bitset or any compatible library.
type Config ¶
type Config struct {
// Decoder decodes the Authorization header value into a Tokener. It is
// required when Middleware is used. It receives the raw header value:
// nothing strips a "Bearer " prefix, so strip it in the decoder if your
// clients send one. If Decoder is nil, a request carrying an
// Authorization header is treated like one with a bad token: public
// endpoints serve it as unauthenticated, RequireAuth and RequirePerms
// reject it with vatel.ErrInternalError (500).
Decoder vatel.TokenDecoder
// Authorizer checks whether the token's permission bytes satisfy the
// endpoint's required permissions. It is required by RequirePerms; a nil
// Authorizer fails RequirePerms endpoints with vatel.ErrInternalError (500).
Authorizer Authorizer
// RevokeCheck optionally verifies that the token has not been revoked
// (omit it for stateless JWTs). Like Decoder, it receives the raw
// Authorization header value. If it returns an error, RequireAuth and
// RequirePerms endpoints fail with vatel.ErrInternalError (500); public
// endpoints serve the request as unauthenticated.
RevokeCheck vatel.RevokeTokenChecker
// Disabled skips all auth checks. Useful for tests and local development.
// Set it before the server starts serving; it is read on every request
// without synchronisation, so changing it while requests are served is a
// data race.
Disabled bool
}
Config holds the auth dependencies for HTTP endpoints.
func (*Config) Middleware ¶
Middleware returns a OnAuthentication middleware that:
- Reads the Authorization header.
- Optionally checks token revocation (if RevokeCheck is set).
- Decodes the token and stores the payload on ctx via SetTokenPayload.
- If the payload's Debug() is true, calls ctx.SetVerboseError(true) to enable detailed error responses for this request.
A bad token (invalid, expired, revoked) does not fail the request here: public endpoints ignore it and serve the request as unauthenticated. RequireAuth and RequirePerms reject the request with the token error (401). A failed revocation check or an unset Decoder is handled the same way, except that RequireAuth and RequirePerms reject with 500.
Endpoints that require authentication or specific permissions should add RequirePerms (or RequireAuth) as an additional EndpointOption.
func (*Config) RequireAuth ¶
func (c *Config) RequireAuth() vatel.EndpointOption
RequireAuth returns an EndpointOption that adds an OnAuthorization middleware rejecting requests that carry no token payload. Use this for endpoints that require any valid authenticated user but no specific permission.
func (*Config) RequirePerms ¶
func (c *Config) RequirePerms(perms map[string]uint) vatel.EndpointOption
RequirePerms returns an EndpointOption that adds an OnAuthorization middleware verifying the token holds all of the named permissions.
perms maps each permission name to its bit position in the token's permission bytes. Bit positions are passed directly to Authorizer.IsAllowed; names are used for error reporting and are appended, sorted, to the endpoint's Perms, so middleware sees them in EndpointMeta.Perms.
Config.Disabled is checked on every request, so it may be set after the option is created, but before the server starts serving (see Config.Disabled). A nil Config.Authorizer fails the request with vatel.ErrInternalError (500).
Source Files