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.
- [Store.Lookup] returns a KeyMeta with the key identifier and owner subject. On successful authentication, the engine writes KeyMeta into ctx via WithKeyMeta and sets auth type to "api_key".
Downstream code reads the result via:
- KeyMetaFrom — full metadata struct.
- SubjectFrom — convenience: extracts OwnerID only.
- authn.AuthTypeFrom — "api_key" on success.
Unlike `security/authn/jwt`, this subpackage exposes no `ClaimsMapper` extension point: API keys carry no JWT claims and the key metadata 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 `(ctx, errMissingHeader)`, which matches authn.ErrNoCredentials.
- Otherwise calls `Store.Lookup(ctx, key)`.
- On success: attaches KeyMeta via WithKeyMeta and sets auth type to "api_key" via authn.WithAuthType; returns the enriched ctx.
- On failure: propagates Store.Lookup 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.
func SubjectFrom ¶ added in v0.5.0
SubjectFrom extracts the owner subject identifier from ctx. Returns the OwnerID previously written by the apikey authenticator on success, or ("", false) if no KeyMeta is present or the OwnerID is empty.
Types ¶
type KeyMeta ¶ added in v0.5.0
type KeyMeta struct {
KeyID string // The key identifier (not the secret)
OwnerID string // Owner subject identifier
}
KeyMeta carries the minimal metadata that the framework needs from a resolved API key. Business code can define its own Store returning richer structures; the framework only inspects these two fields.
- KeyID: the key identifier (NOT the secret); used in audit trails.
- OwnerID: the subject identifier of the key owner; surfaced via SubjectFrom.
func KeyMetaFrom ¶ added in v0.5.0
KeyMetaFrom retrieves the KeyMeta previously set via WithKeyMeta. Returns the zero value and false if not present.
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 KeyMeta. 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 a KeyMeta.
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 how keys are stored — implementations construct a KeyMeta with the identifier and owner of the resolved key.
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 audit failure reason when the request ultimately fails, so implementations should keep reasons short and PII-free.
Source Files