Documentation
¶
Overview ¶
Package jwt provides a generic Bearer JWT authentication skeleton for the engine-agnostic authn dispatcher. It owns its credential I/O end-to-end:
- Client is a Kratos client middleware that propagates the token from the ctx into the outbound Authorization header.
- WithToken / TokenFrom are the jwt-package-private ctx channel; they are the supported way to read or write the raw bearer token in flight.
- NewAuthenticator exposes the bare engine wired through authn.Named and authn.Multi.
Typical business usage:
import authjwt "github.com/Servora-Kit/servora/security/authn/jwt"
mw = append(mw, authn.Server(
authn.Multi(
authn.Named(authjwt.Scheme, authjwt.NewAuthenticator(authjwt.WithVerifier(v))),
authn.Named(apikey.Scheme, apikey.NewAuthenticator(...)),
),
authn.WithRulesFuncs(examplev1.AuthnRules),
))
The transport middleware package MUST NOT host equivalents of WithToken / TokenFrom / Bearer extraction — those are jwt-engine concerns, not framework-wide concerns.
Index ¶
- Constants
- func ClaimsFrom(ctx context.Context) (gojwt.MapClaims, bool)
- func Client() middleware.Middleware
- func NewAuthenticator(opts ...Option) authn.Authenticator
- func SubjectFrom(ctx context.Context) (string, bool)
- func TokenFrom(ctx context.Context) (string, bool)
- func WithClaims(ctx context.Context, claims gojwt.MapClaims) context.Context
- func WithToken(ctx context.Context, token string) context.Context
- type ClaimsMapper
- type Option
Constants ¶
const Scheme = "jwt"
Scheme is the canonical scheme string for this engine, paired with NewAuthenticator via authn.Named. The framework does not enumerate scheme constants — each engine sub-package owns its own string.
Variables ¶
This section is empty.
Functions ¶
func ClaimsFrom ¶ added in v0.5.0
ClaimsFrom reads the parsed JWT MapClaims previously stored by WithClaims. Returns (nil, false) if no claims are present in the context.
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 [Authenticator] 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.
If no token is found, Authenticate returns authn.ErrNoCredentials. Missing verifier is a wiring error and panics at construction time. Verifier failure returns a normal error, so Multi can fail fast.
func SubjectFrom ¶ added in v0.5.0
SubjectFrom is a convenience accessor that reads the "sub" claim from the jwt-private claims ctx channel. It returns ("", false) if no claims are present or if "sub" is missing or not a string.
func TokenFrom ¶ added in v0.4.8
TokenFrom reads the raw bearer token previously stored by WithToken. It is used by Client for outbound propagation, and may be used by business middleware that wants to observe the inbound token. Returns ("", false) if no token is present.
func WithClaims ¶ added in v0.5.0
WithClaims stores the parsed JWT MapClaims into a jwt-package-private ctx channel. It is invoked by the default ClaimsMapper after successful verification, and may also be called by custom mappers that wish to expose the full claims to downstream handlers via ClaimsFrom.
func WithToken ¶ added in v0.4.7
WithToken stores the raw bearer token into a jwt-package-private ctx channel. It is invoked by [Authenticate] after resolving the inbound Authorization header, and may also be called directly by upstream code that obtained a token via some other path.
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.
Types ¶
type ClaimsMapper ¶
ClaimsMapper converts parsed JWT MapClaims into an enriched context.
The first parameter is the incoming ctx that the engine needs to write private ctx channels into. The returned context carries whatever the mapper chose to store (at minimum the full claims map via WithClaims).
This is the extension point business code uses to interpret IdP-specific claims. The framework ships only a minimal default — anything richer (custom roles, tenant, scopes, group memberships, …) belongs in business code, plugged via WithClaimsMapper.
func DefaultClaimsMapper ¶
func DefaultClaimsMapper() ClaimsMapper
DefaultClaimsMapper returns the framework's minimal Bearer-JWT mapper.
It validates that the `sub` claim is present and non-empty (REQUIRED), then stores the full claims map into the jwt-private ctx channel via WithClaims. Downstream handlers read individual claims via ClaimsFrom or the convenience SubjectFrom.
IdP-specific claim interpretation (azp, scope, email, roles, groups, custom claims, …) is intentionally NOT covered. Business code that needs those fields installs its own ClaimsMapper via WithClaimsMapper.
type Option ¶
type Option func(*authenticatorConfig)
Option configures the JWT Authenticator.
func WithClaimsMapper ¶
func WithClaimsMapper(m ClaimsMapper) Option
WithClaimsMapper sets a custom ClaimsMapper to enrich the ctx with parsed JWT claims. Defaults to DefaultClaimsMapper, which validates the sub claim and stores the full claims map via WithClaims.
Business code that needs IdP-specific fields (custom roles / scopes / tenant / group memberships / …) installs its own mapper here.
func WithVerifier ¶
WithVerifier sets the JWT verifier used to validate token signatures. It is required; NewAuthenticator panics when no verifier is supplied.
Source Files