Documentation
¶
Overview ¶
Package apikey provides an API-key authentication skeleton for the engine-agnostic authn dispatcher. It is a thin engine: the framework owns the wiring (header extraction + dispatch) while the storage backend (in-memory / DB / cache / cross-service RPC) is supplied by the business via the Store interface.
Header carrier:
- The engine reads the API key from the inbound `X-API-Key` header on the Kratos server transport.
- It deliberately does NOT consume `Authorization: Bearer <token>` so that an apikey engine can be wired alongside `security/authn/jwt` in the same `authn.Multi` decorator without header collision.
Multi-engine composition example:
authn.Server(
authn.Multi(
authn.Named(jwt.Scheme, jwt.NewAuthenticator(jwt.WithVerifier(jv))),
authn.Named(apikey.Scheme, apikey.NewAuthenticator(apikey.WithStore(myStore))),
),
authn.WithRulesFuncs(myProto.AuthnRules),
)
Storage backend ownership:
- The framework imposes no constraint on how API keys are stored or revoked; that is a business / platform concern.
- Implementations of Store may be backed by an in-memory map (test stub), a database table, a cache, or a cross-service RPC.
- Likewise, [Store.Lookup] returns a generic actor.Actor; concrete implementations decide whether to return `*actor.UserActor` (human- issued keys), `*actor.ServiceActor` (service-account keys), or any custom actor implementation.
Unlike `security/authn/jwt`, this subpackage exposes no `ClaimsMapper` extension point: API keys carry no JWT claims and the actor shape is produced directly by [Store.Lookup].
Index ¶
Constants ¶
const Scheme = "apikey"
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 NewAuthenticator ¶
func NewAuthenticator(opts ...Option) authn.Authenticator
NewAuthenticator creates an API-key based authn.Authenticator.
The returned authenticator's `Authenticate(ctx)`:
- Reads the `X-API-Key` header from the Kratos server transport.
- If absent / empty → returns `(nil, errMissingHeader)`.
- Otherwise calls `Store.Lookup(ctx, key)` and propagates its `(actor.Actor, error)` verbatim.
REQUIRED: at least one WithStore Option MUST be supplied. Calling `NewAuthenticator()` (no opts) panics with `apikey: WithStore is required`. The fail-fast panic surfaces wiring bugs at boot time rather than per-request 401s.
Types ¶
type Option ¶
type Option func(*config)
Option configures an apikey [authenticator] at construction time.
func WithStore ¶
WithStore configures the storage backend used to resolve API keys into actors. It is REQUIRED — NewAuthenticator panics if called without `WithStore` (fail-fast: an apikey engine without a Store can never authenticate any request, so silent acceptance would mask wiring bugs).
type Store ¶
Store resolves an API key string into an actor.Actor.
Implementations may be backed by an in-memory map (test stubs), a database table, a cache, or a cross-service RPC. The framework imposes no constraint on the actor type — implementations should construct an appropriate concrete (e.g. `*actor.UserActor` for human-issued keys, `*actor.ServiceActor` for service-account keys, or any custom actor implementation).
Error semantics:
- Unknown / revoked / disabled keys SHOULD return a non-nil error; the apikey engine propagates that error verbatim to the dispatcher.
- The error string is surfaced via `*auditpb.AuthnDetail.FailureReason` when the request ultimately fails, so implementations should keep reasons short and PII-free.
Source Files