Documentation
¶
Overview ¶
Package ginmw provides Gin-compatible middleware for the api-security-sdk. It bridges the SDK's JWT, RBAC, and audit packages with the Gin web framework.
JWT authentication ¶
svc := jwt.New(jwt.WithHMAC(secret)) r.Use(ginmw.JWT(svc))
Verify-only (Auth0 / external IdP) ¶
src := jwks.Auth0("myapp.auth0.com")
svc := jwt.New(jwt.WithJWKS(src.KeyFunc))
r.Use(ginmw.JWT(svc))
RBAC middleware ¶
enforcer := rbac.New(store)
r.GET("/admin", ginmw.RequireRole(enforcer, "admin"), handler)
r.DELETE("/posts/:id", ginmw.RequirePermission(enforcer, "delete", "posts"), handler)
Scope checking (OAuth 2.0 / OIDC scopes) ¶
r.GET("/profile", ginmw.ScopeChecker("read:profile"), handler)
Index ¶
- func ClaimsFrom(c *gin.Context) *jwtpkg.Claims
- func JWT(svc *jwtpkg.Service) gin.HandlerFunc
- func RequirePermission(enforcer *rbac.Enforcer, action, resource string) gin.HandlerFunc
- func RequireRole(enforcer *rbac.Enforcer, roles ...string) gin.HandlerFunc
- func ScopeChecker(required ...string) gin.HandlerFunc
- func SubjectFrom(c *gin.Context) string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClaimsFrom ¶
ClaimsFrom retrieves the *jwt.Claims stored by the JWT middleware. Returns nil if JWT middleware has not run or the token was invalid.
func JWT ¶
func JWT(svc *jwtpkg.Service) gin.HandlerFunc
JWT returns a Gin middleware that:
- Extracts the Bearer token from the Authorization header.
- Validates it via svc.Verify (supports JWKS, HMAC, RSA, ECDSA).
- Stores the *jwt.Claims in the Gin context under "ginmw:claims".
Requests without a valid token are rejected with 401. To make auth optional, do not use this middleware globally — instead apply it only to protected groups.
func RequirePermission ¶
func RequirePermission(enforcer *rbac.Enforcer, action, resource string) gin.HandlerFunc
RequirePermission returns a middleware that rejects requests (403) unless the authenticated subject has permission to perform action on resource.
Must be used after ginmw.JWT.
func RequireRole ¶
func RequireRole(enforcer *rbac.Enforcer, roles ...string) gin.HandlerFunc
RequireRole returns a middleware that rejects requests (403) unless the authenticated subject has at least one of the provided roles.
Must be used after ginmw.JWT (or another middleware that sets the subject).
func ScopeChecker ¶
func ScopeChecker(required ...string) gin.HandlerFunc
ScopeChecker returns a middleware that verifies the JWT contains all of the required OAuth 2.0 / OIDC scopes. It inspects two standard claim shapes:
- "scope" — a single space-delimited string (e.g. "read:users write:posts")
- "scopes" — a JSON array of strings (e.g. ["read:users","write:posts"])
Both conventions are widely used; Auth0 uses "scope" (string), some OIDC providers use "scopes" (array). ScopeChecker handles either.
Must be used after ginmw.JWT.
func SubjectFrom ¶
SubjectFrom retrieves the authenticated subject (sub claim) stored by the JWT middleware. Returns "" if JWT middleware has not run.
Types ¶
This section is empty.
Source Files