Documentation
¶
Overview ¶
Package jwt provides a self-contained JWT authentication wrapper for the engine-agnostic authn dispatcher. It owns its credential I/O end-to-end:
- Server is a Kratos server middleware that extracts the Bearer token from the inbound Authorization header, stores it into the jwt-private ctx channel, and delegates to authn.Server with method "jwt".
- Client is a Kratos client middleware that propagates the token from the ctx into the outbound Authorization header.
- WithToken / TokenFromContext are the jwt-package-private ctx channel; they are the ONLY supported way to read or write the raw bearer token in flight.
- NewAuthenticator exposes the bare engine for power users who want to compose their own wrapper (e.g. read the token from a non-HTTP carrier).
Typical business usage:
import authjwt "github.com/Servora-Kit/servora/security/authn/jwt" mw = append(mw, authjwt.Server(authjwt.WithVerifier(km.Verifier())))
The general transport middleware package MUST NOT host equivalents of WithToken / TokenFromContext / Bearer extraction — those are jwt-engine concerns, not framework-wide concerns. See design.md Decisions 4 / 5 / 6.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Client ¶ added in v0.4.7
func Client() middleware.Middleware
Client returns a Kratos client middleware that propagates the jwt token previously stored in the ctx (by Server on the inbound side, or by an explicit WithToken call) into the outbound Authorization header as `Bearer <token>`.
If no token is present in the ctx or no client transport is attached, the middleware passes through without modification — never errors.
Business callers must opt in explicitly: the framework's default client chain does NOT include this middleware, because not every outbound call wants to forward an inbound credential (cross-realm calls, third-party integrations, etc.). See design.md Decision 5.
Typical usage:
conn, err := grpc.Dial(grpc.WithMiddleware(jwt.Client()))
func NewAuthenticator ¶
func NewAuthenticator(opts ...Option) authn.Authenticator
NewAuthenticator creates a JWT-based authn.Authenticator without the surrounding wrapper. Power users who need to compose their own wrapper (e.g. read the token from a non-HTTP carrier) can pair this with authn.Server directly:
auth := jwt.NewAuthenticator(jwt.WithVerifier(v))
mw := authn.Server(auth, authn.WithMethod("jwt"))
Most callers should use Server instead, which assembles the complete wrapper (Bearer extraction + dispatcher + chain short-circuit).
The token is read from the jwt-private ctx channel via TokenFromContext. If no token is present, or no Verifier is configured, an anonymous actor is returned with nil error.
func Server ¶ added in v0.4.7
func Server(opts ...Option) middleware.Middleware
Server returns a Kratos server middleware that authenticates incoming requests with the JWT engine. It wraps authn.Server, adding jwt-specific credential I/O before delegation:
- Chain short-circuit: if the ctx already carries a non-anonymous actor (a previous engine in a multi-mechanism chain authenticated successfully), pass through without invoking the engine — zero-cost hook used by the P0-4b "auth chain" composition path. The pass-through branch does NOT write an AuthnDetail (the prior engine already did) and does NOT touch the actor.
- Extract Bearer token from the inbound Authorization header and stash it into the jwt-private ctx channel via WithToken.
- Delegate to authn.Server(engine, authn.WithMethod("jwt")) which calls Authenticate, writes the AuthnDetail, and injects the resulting actor.
Use this in business code instead of calling authn.Server directly:
mw = append(mw, jwt.Server(jwt.WithVerifier(km.Verifier())))
func TokenFromContext ¶ added in v0.4.7
TokenFromContext reads the raw bearer token previously stored by WithToken. It is used by the engine [Authenticate] (server side) and by Client for outbound propagation. Returns ("", false) if no token is present.
func WithToken ¶ added in v0.4.7
WithToken stores the raw bearer token into a jwt-package-private ctx channel. It is invoked by Server after parsing the inbound Authorization header, and may also be called directly by upstream code that obtained a token via some other path (e.g., re-injection during a retry).
The channel is intentionally jwt-private. The general transport middleware package MUST NOT host equivalent helpers — credential carrier shape (the Bearer token format) is jwt-engine concern, not framework-wide concern. See design.md Decisions 4 / 5.
Types ¶
type ClaimsMapper ¶
ClaimsMapper converts parsed JWT MapClaims into an actor.Actor.
func DefaultClaimsMapper ¶
func DefaultClaimsMapper() ClaimsMapper
DefaultClaimsMapper maps standard OIDC claims (sub, name, email, azp, scope). It does not contain any IdP-specific fields (no issuer→Realm mapping).
func KeycloakClaimsMapper ¶
func KeycloakClaimsMapper() ClaimsMapper
KeycloakClaimsMapper extends DefaultClaimsMapper with Keycloak-specific field mappings: iss → Realm, realm_access.roles supplemental roles.
type Option ¶
type Option func(*authenticatorConfig)
Option configures the JWT Authenticator.
func WithClaimsMapper ¶
func WithClaimsMapper(m ClaimsMapper) Option
WithClaimsMapper sets a custom ClaimsMapper to convert JWT claims to an actor.Actor. Defaults to DefaultClaimsMapper().
func WithVerifier ¶
WithVerifier sets the JWT verifier used to validate token signatures. If nil, the authenticator operates in pass-through mode (anonymous actor returned).
Source Files