Documentation
¶
Overview ¶
Package authz provides a generic Kratos middleware for authorization. It is engine-agnostic: any Authorizer implementation can be injected.
Example usage:
import (
pkgauthz "github.com/Servora-Kit/servora/security/authz"
fgaengine "github.com/Servora-Kit/servora/security/authz/openfga"
)
mw = append(mw, pkgauthz.Server(
fgaengine.NewAuthorizer(fgaClient),
pkgauthz.WithRulesFuncs(iamv1.AuthzRules),
pkgauthz.WithSubjectFunc(mySubjectExtractor),
))
Package authz provides a Kratos middleware for engine-agnostic authorization.
Engine model ¶
The Authorizer interface exposes a single Check method that accepts a CheckRequest (Subject, Action, ResourceType, ResourceID, Attributes). Any authorization backend — OpenFGA, SpiceDB, Cedar, OPA, or custom — can implement this interface.
Batch and list capabilities are available via optional sub-interfaces in the batch and lister sub-packages, which engines may implement as needed.
Subject resolution ¶
The middleware does NOT assume how a subject string is derived from the request context. Callers provide a WithSubjectFunc option that extracts the subject from ctx. This decouples authz from any specific authn scheme.
Audit integration ¶
When WithAuditor is configured with an audit.Auditor, the middleware emits typed CloudEvents events on authorization allowed, denied, and error decisions. The authenticated subject is written to the CloudEvents authid extension so platform audit storage can project actor_id. Without the option, the middleware is silent.
Future: contextual tuples / attributes ¶
The CheckRequest.Attributes field (map[string]any) is reserved for request-level facts that participate in a decision but are not persisted: device trust, active session, time-of-day, request region, etc. Engines that support ABAC or contextual tuples can read from this field.
Index ¶
- Constants
- func Server(authorizer Authorizer, opts ...Option) middleware.Middleware
- type Authorizer
- type CheckRequest
- type Option
- func WithAuditor(auditor audit.Auditor) Option
- func WithCheckTimeout(d time.Duration) Option
- func WithDefaultResourceID(id string) Option
- func WithFailOpenOnMissingRule(alertFn func(ctx context.Context, operation string)) Option
- func WithRulesFuncs(fns ...func() map[string]*authzpb.AuthzRule) Option
- func WithSubjectFunc(fn func(context.Context) (string, bool)) Option
Constants ¶
const ( EventTypeAuthzAllowed = "servora.authz.allowed.v1" EventTypeAuthzDenied = "servora.authz.denied.v1" EventTypeAuthzError = "servora.authz.error.v1" )
Variables ¶
This section is empty.
Functions ¶
func Server ¶
func Server(authorizer Authorizer, opts ...Option) middleware.Middleware
Server returns a Kratos middleware that performs authorization checks.
Behavior:
- No transport in context → passthrough (non-server calls).
- No rule for operation → fail-closed (403 AUTHZ_NO_RULE).
- No rule + WithFailOpenOnMissingRule set → alertFn invoked, handler called.
- AUTHZ_MODE_NONE → skip (public endpoint).
- AUTHZ_MODE_CHECK, no subject → 403 AUTHZ_DENIED.
- AUTHZ_MODE_CHECK, nil authorizer → 503 AUTHZ_UNAVAILABLE.
- AUTHZ_MODE_CHECK, authorizer returned (true, nil) → handler called. if WithAuditor is set, emits servora.authz.allowed.v1.
- AUTHZ_MODE_CHECK, authorizer returned (false, nil) → 403 AUTHZ_DENIED; if WithAuditor is set, emits servora.authz.denied.v1.
- AUTHZ_MODE_CHECK, authorizer returned (_, err) → 503 AUTHZ_CHECK_FAILED; if WithAuditor is set, emits servora.authz.error.v1.
Types ¶
type Authorizer ¶
type Authorizer interface {
// Check returns whether the request described by req is authorized.
Check(ctx context.Context, req CheckRequest) (allowed bool, err error)
}
Authorizer is the single-method interface for authorization decisions. Implementations may target any backend (OpenFGA, SpiceDB, Cedar, OPA, etc.).
type CheckRequest ¶ added in v0.4.0
type CheckRequest struct {
Subject string
Action string
ResourceType string
ResourceID string
Attributes map[string]any
}
CheckRequest describes a single authorization check.
type Option ¶
type Option func(*serverConfig)
Option configures the Server middleware.
func WithAuditor ¶ added in v0.8.1
WithAuditor configures the middleware to emit CloudEvents audit events for authorization decisions:
- Check returns (true, nil): emit type "servora.authz.allowed.v1".
- Check returns (false, nil): emit type "servora.authz.denied.v1".
- Check returns (_, err): emit type "servora.authz.error.v1".
Each event carries AuthzDecision protobuf data and the authenticated subject in the CloudEvents "authid" extension. No severity extension is emitted.
func WithCheckTimeout ¶ added in v0.4.0
WithCheckTimeout bounds the time spent in Authorizer.Check on each request. Zero (default) disables the deadline — the upstream context applies.
This protects business-RPC latency from a slow authorization backend.
func WithDefaultResourceID ¶ added in v0.5.0
WithDefaultResourceID overrides the fallback resource ID used when resource_id_field is empty. Defaults to "default".
func WithFailOpenOnMissingRule ¶ added in v0.4.0
WithFailOpenOnMissingRule changes the missing-rule policy from fail-closed (default — return AUTHZ_NO_RULE 403) to fail-open: the handler is called, and the alertFn callback is invoked so the gap is visible (oncall page, Slack, log warning, etc.).
Use during development or staged rollouts. NEVER use in production for security-sensitive services.
func WithRulesFuncs ¶
WithRulesFuncs merges the rule maps returned by one or more generator functions (e.g. userpb.AuthzRules, iampb.AuthzRules) into a single rule set. Later entries take precedence on key conflicts.
func WithSubjectFunc ¶ added in v0.5.0
WithSubjectFunc sets the function used to extract the subject string from the request context. The function should return the subject identifier and a boolean indicating whether the subject was found. When not set or when the function returns false, the middleware returns 403 AUTHZ_DENIED.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package batch defines the optional BatchAuthorizer sub-interface for authorization backends that support multi-check in a single round-trip.
|
Package batch defines the optional BatchAuthorizer sub-interface for authorization backends that support multi-check in a single round-trip. |
|
Package lister defines the optional Lister sub-interface for authorization backends that can enumerate resources a subject is allowed to access.
|
Package lister defines the optional Lister sub-interface for authorization backends that can enumerate resources a subject is allowed to access. |
|
Package noop provides a no-op Authorizer that always permits all requests.
|
Package noop provides a no-op Authorizer that always permits all requests. |
|
Package openfga provides an OpenFGA-based Authorizer implementation for security/authz.
|
Package openfga provides an OpenFGA-based Authorizer implementation for security/authz. |