Documentation
¶
Overview ¶
Package authkitgin bridges AuthKit's net/http middleware to Gin. Mount registers AuthKit's routes directly on the engine; verification policy stays in verify.
Index ¶
- func Fallback(h http.Handler) gin.HandlerFuncdeprecated
- func Mount(router *gin.Engine, svc *authhttp.Service, options ...authhttp.MountOptions) error
- func Optional(v *verify.Verifier) gin.HandlerFunc
- func OptionalLive(v *verify.Verifier) (gin.HandlerFunc, error)
- func Principal(c *gin.Context) (authkit.Principal, bool)
- func RequirePermission(checker verify.PermissionChecker, perm authkit.Perm, ...) gin.HandlerFunc
- func Required(v *verify.Verifier) gin.HandlerFunc
- func RequiredLive(v *verify.Verifier) (gin.HandlerFunc, error)
- func Use(mw ...func(http.Handler) http.Handler) gin.HandlerFunc
- type Bundle
- type UserClaimsData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Fallback
deprecated
added in
v0.84.0
func Fallback(h http.Handler) gin.HandlerFunc
Fallback adapts a neutral handler (authhttp.MountHandler) for use as a gin NoRoute fallback. gin pre-sets 404 on the response before running NoRoute handlers, which silently overrides any handler that relies on the implicit 200-on-first-write; this clears the pending status so the mounted handler's own status wins (its 404s still 404).
router.NoRoute(authkitgin.Fallback(mount))
For explicit wildcard mounts (r.Any("/oidc/*path", …)) plain gin.WrapH is fine — gin only pre-sets 404 on the NoRoute path.
Deprecated: use Mount to register ordinary routes visible to router.Routes(). Fallback remains available for hosts adapting a custom HTTP handler.
func Mount ¶ added in v0.128.0
Mount registers AuthKit's configured routes directly on router. Each route, including HEAD, appears in router.Routes(). Call Mount during application setup, before serving requests.
The optional MountOptions selects route groups, exclusions, the API prefix, wrappers, and refresh-cookie policy. JWKS, documents, and browser OIDC keep their standard root paths. Handlers use AuthKit's canonical HTTP pipeline, preserving authentication, JSON guards, cookies, and request context. Host middleware applies normally; unmatched paths and methods use Gin's routing.
Conflicting routes and unsupported patterns return an error before any route is registered. Use MountOptions.ExcludeRoutes for host-owned replacements.
func Optional ¶ added in v0.78.0
func Optional(v *verify.Verifier) gin.HandlerFunc
Optional is the gin-native form of verify.Optional (#209): passes through anonymously when Authorization is absent and otherwise validates it. A present invalid credential is rejected. See Required for usage.
func OptionalLive ¶ added in v0.128.0
func OptionalLive(v *verify.Verifier) (gin.HandlerFunc, error)
OptionalLive admits anonymous requests and checks the liveness of presented native-user credentials. It returns verify.ErrLivenessUnconfigured at startup when no source is wired. Use on routes, groups, or as application middleware.
func RequirePermission ¶ added in v0.72.0
func RequirePermission(checker verify.PermissionChecker, perm authkit.Perm, resolve func(*gin.Context) verify.PermissionScope) gin.HandlerFunc
func Required ¶ added in v0.78.0
func Required(v *verify.Verifier) gin.HandlerFunc
Required is the gin-native form of verify.Required (#209): validates the Bearer token and stores claims in the request context, aborting with the verifier's 401 on failure. Use it directly on gin routes/groups instead of hand-writing an http.Handler↔gin.HandlerFunc shim:
api := r.Group("/api", authkitgin.Required(verifier))
func RequiredLive ¶ added in v0.92.0
func RequiredLive(v *verify.Verifier) (gin.HandlerFunc, error)
RequiredLive is the gin-native form of verify.RequiredLive (#267): Required plus a per-request account-liveness gate, so a banned or deleted user is rejected on their next request and the handler reads fresh identity claims. Returns verify.ErrLivenessUnconfigured when the verifier has no LivenessSource wired.
Types ¶
type Bundle ¶ added in v0.128.0
type Bundle struct {
// contains filtered or unexported fields
}
Bundle contains the runtime's already configured route inventory.
type UserClaimsData ¶ added in v0.72.0
type UserClaimsData = verify.UserClaimsData
UserClaimsData is the shared local-user view. See verify.UserClaimsData for optional fields and the token-time versus live-profile freshness contract.
func UserClaims ¶ added in v0.72.0
func UserClaims(c *gin.Context) (UserClaimsData, bool)
UserClaims reads a verified local user without performing a database lookup. Profile availability depends on Required/Optional versus RequiredLive.
Source Files