README
¶
auth/rbac/http
auth/rbac/http adapts auth/rbac.Service to JSON bearer routes.
Use it for applications that need multiple users, role checks, scope checks, or opaque API tokens. auth/rbac owns the authentication flow; the application owns user storage, password hashing, role assignment, and token persistence.
Default HTTP paths:
| Route | Purpose |
|---|---|
POST /auth/login |
returns access_token, refresh_token, and user |
POST /auth/refresh |
rotates refresh_token from JSON body |
POST /auth/logout |
revokes refresh_token from JSON body |
GET /auth/me |
returns the current principal |
POST /auth/login accepts username, password, and optional persistence. Missing persistence defaults to persistent tokens; session returns session-only token metadata.
Mount and generate the contract from the same route values:
routeList := authHandler.Routes()
err := routes.Mount(r, "", routeList)
spec, err := openapi.Generate(routeList, openapi.Options{
Title: "Application RBAC API",
Version: "1.0.0",
})
Options.BasePath is a *string route prefix: nil defaults to "/auth", new("") selects the root, and new("/api/auth") selects /api/auth. Non-empty prefixes require a single leading slash; trailing slashes and surrounding whitespace are rejected.
Recommended Stack
auth/rbac.Servicewith applicationUserStoreandPasswordVerifierauth/jwt.Managerwithauth/store/redissessionfor multi-instance session stateauth/rbac.Lockout;auth/rbac.Servicedefaults to in-memory lockout, so pass Redis or SQL-backed lockout for multi-instance deploymentsauth/rbac.APITokenStorewhen API tokens should authenticate through the same Bearer middlewareOptions.RolePolicyfor role hierarchy, or the default exact-role policy for simple projects
Middleware helpers are available from Handler.Middleware() or NewMiddleware:
authz := authHandler.Middleware()
r.Use(authz.RequireAuth())
r.With(authz.RequireRole("admin")).Get("/admin", adminHandler)
r.With(authz.RequireScope("vm:read")).Get("/vms", listVMs)
Configure role hierarchy with Options.RolePolicy or NewMiddleware(service, policy).
Use auth/http instead for admin-only applications that only need one shared credential and cookie-backed refresh sessions.
Documentation
¶
Index ¶
- type Authenticator
- type Handler
- type Middleware
- func (m Middleware) RequireAnyRole(roles ...string) func(http.Handler) http.Handler
- func (m Middleware) RequireAuth() func(http.Handler) http.Handler
- func (m Middleware) RequireRole(role string) func(http.Handler) http.Handler
- func (m Middleware) RequireRoleAndScope(role, scope string) func(http.Handler) http.Handler
- func (m Middleware) RequireScope(scope string) func(http.Handler) http.Handler
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Authenticator ¶
type Authenticator interface {
AuthenticateBearer(ctx context.Context, token string) (authcore.Principal, bool, error)
}
Authenticator authenticates bearer tokens. Authenticator 校验 bearer token。
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler serves JSON bearer RBAC auth endpoints. Handler 提供 JSON bearer RBAC 认证端点。
func NewHandler ¶
NewHandler returns a Handler. NewHandler 返回 Handler。
func (*Handler) Middleware ¶
func (h *Handler) Middleware() Middleware
Middleware returns route middleware helpers for this Handler. Middleware 返回该 Handler 的路由 middleware 辅助工具。
type Middleware ¶
type Middleware struct {
Auth Authenticator
Roles corerbac.RolePolicy
}
Middleware builds RBAC route middleware. Middleware 构造 RBAC 路由中间件。
func NewMiddleware ¶
func NewMiddleware(auth Authenticator, roles corerbac.RolePolicy) Middleware
NewMiddleware returns RBAC middleware helpers. NewMiddleware 返回 RBAC middleware 辅助工具。
func (Middleware) RequireAnyRole ¶
RequireAnyRole requires at least one allowed role. RequireAnyRole 要求至少一个被允许的角色。
func (Middleware) RequireAuth ¶
func (m Middleware) RequireAuth() func(http.Handler) http.Handler
RequireAuth requires any authenticated principal. RequireAuth 要求任意已认证主体。
func (Middleware) RequireRole ¶
RequireRole requires a role allowed by the configured RolePolicy. RequireRole 要求配置的 RolePolicy 允许该角色。
func (Middleware) RequireRoleAndScope ¶
RequireRoleAndScope requires both a role and a scope. RequireRoleAndScope 同时要求角色与 scope。
func (Middleware) RequireScope ¶
RequireScope requires a scope. RequireScope 要求指定 scope。
type Options ¶
type Options struct {
// BasePath is a route prefix. Nil defaults to "/auth"; new("") selects the root.
// BasePath 是路由前缀；nil 默认使用 "/auth"，new("") 选择根目录。
BasePath *string
MaxBodyBytes int64
TrustedProxies []netip.Prefix
RolePolicy corerbac.RolePolicy
}
Options configures NewHandler. Options 配置 NewHandler。
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns default handler options. DefaultOptions 返回默认 handler 选项。
Source Files