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.WithRulesFunc(iamv1.AuthzRules),
))
Package authz provides a Kratos middleware for relationship-based authorization.
Engine model ¶
The Authorizer interface (Check / BatchCheck / ListAllowed) maps directly onto OpenFGA SDK and SpiceDB primitives. Both ReBAC backends support all three methods natively. The interface is not designed to host non-ReBAC engines (Cedar, Rego); those would require a separate abstraction.
Future: contextual tuples ¶
OpenFGA's "contextual tuples" (and SpiceDB's "caveats") express request-level facts that participate in a decision but are not persisted: device trust, active session, time-of-day, request region, etc.
When this is needed, the planned API is:
ctx = authz.WithContextualTuples(ctx, tuples...) // upstream mw injects authz.ContextualTuplesFromContext(ctx) []Tuple // engine adapter reads
The Authorizer interface signatures already accept context.Context as the first parameter, so no signature change will be required when this is added.
Audit integration ¶
Pair authz.WithObserver with recorder.AuthzObserver() (from obs/audit) to forward every decision to the audit pipeline without per-call wiring. See obs/audit/observers.go for the bridge implementation.
Index ¶
- func MergeRules(ms ...map[string]AuthzRule) map[string]AuthzRule
- func Server(authorizer Authorizer, opts ...Option) middleware.Middleware
- type Authorizer
- type AuthzRule
- type CheckRequest
- type CheckResult
- type DecisionDetail
- type Option
- func WithCheckTimeout(d time.Duration) Option
- func WithDefaultObjectID(id string) Option
- func WithFailOpenOnMissingRule(alertFn func(ctx context.Context, operation string)) Option
- func WithObserver(fn func(ctx context.Context, detail DecisionDetail)) Option
- func WithRules(rules map[string]AuthzRule) Option
- func WithRulesFunc(fn func() map[string]AuthzRule) Option
- func WithRulesFuncs(fns ...func() map[string]AuthzRule) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MergeRules ¶
MergeRules merges multiple AuthzRule maps into one new map. Later maps take precedence on key conflicts (which should not occur in practice). Useful when a server registers services from multiple generated packages.
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 for operation + WithFailOpenOnMissingRule set → alertFn invoked, handler called
- AUTHZ_MODE_NONE → skip (public endpoint)
- AUTHZ_MODE_CHECK, no actor or anonymous actor → 403 AUTHZ_DENIED
- AUTHZ_MODE_CHECK, nil authorizer → 503 AUTHZ_UNAVAILABLE
- AUTHZ_MODE_CHECK, allowed → handler called
- AUTHZ_MODE_CHECK, denied → 403 AUTHZ_DENIED
The OpenFGA principal is constructed as "<actor.Type()>:<actor.ID()>".
Types ¶
type Authorizer ¶
type Authorizer interface {
// Check returns whether subject has relation on objectType:objectID.
Check(ctx context.Context, subject, relation, objectType, objectID string) (allowed bool, err error)
// BatchCheck runs N checks in one round-trip; output order matches input.
// Implementations may internally chunk if the backend has per-call limits
// (OpenFGA caps at 50 per request).
BatchCheck(ctx context.Context, reqs []CheckRequest) ([]CheckResult, error)
// ListAllowed returns IDs of objects (of objectType) the subject has the
// given relation to. The returned strings are bare IDs without "type:" prefix.
// Useful for "list" endpoints — caller fetches by `WHERE id IN (...)`.
ListAllowed(ctx context.Context, subject, relation, objectType string) ([]string, error)
}
Authorizer is the interface for relationship-based authorization decisions. All three methods are required: implementations targeting non-ReBAC backends (e.g. pure Cedar/Rego) would need a different abstraction entirely, so we commit to the ReBAC shape rather than a sub-interface fan-out.
Method names match OpenFGA SDK semantics for direct mapping; SpiceDB (LookupResources / BulkCheck) maps cleanly as well.
type AuthzRule ¶
type AuthzRule struct {
Mode authzpb.AuthzMode
Relation string
ObjectType string
// IDField is the proto field name to extract object ID from the request.
// When empty, "default" is used as the object ID (singleton/platform-level checks).
IDField string
}
AuthzRule describes the authorization requirement for a single RPC operation.
type CheckRequest ¶ added in v0.4.0
CheckRequest is one item in a BatchCheck call.
type CheckResult ¶ added in v0.4.0
CheckResult is the per-item outcome of BatchCheck. Order matches the input []CheckRequest index.
type DecisionDetail ¶
type DecisionDetail struct {
Operation string
Subject string
Relation string
ObjectType string
ObjectID string
Allowed bool
Err error
}
DecisionDetail describes the result of a single authorization check. It is passed to the Observer callback after every check.
Cache-hit signals are intentionally absent — caching is an engine-internal optimization (see infra/openfga) and does not belong in audit semantics.
type Option ¶
type Option func(*serverConfig)
Option configures the Server middleware.
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 (e.g. OpenFGA cross-region calls).
func WithDefaultObjectID ¶
WithDefaultObjectID overrides the fallback object ID used when IDField 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 WithObserver ¶ added in v0.4.3
func WithObserver(fn func(ctx context.Context, detail DecisionDetail)) Option
WithObserver installs a callback invoked after every authorization Check. Pair it with `recorder.AuthzObserver()` from obs/audit to bridge decisions into the audit pipeline:
authz.Server(authorizer,
authz.WithRulesFunc(rules),
authz.WithObserver(recorder.AuthzObserver()),
)
observer == nil leaves the middleware unaffected (no-op). pkg/authz remains free of any pkg/audit dependency — bridging lives in obs/audit/observers.go.
func WithRulesFunc ¶
WithRulesFunc sets the operation→rule mapping via a single function (e.g. generated AuthzRules()). The function is called once during middleware construction. To merge rules from multiple packages, prefer WithRulesFuncs.
func WithRulesFuncs ¶
WithRulesFuncs merges the rule maps returned by one or more generator functions (e.g. userpb.AuthzRules, authnpb.AuthzRules) into a single rule set. Later entries take precedence on key conflicts (which should not occur in practice). This is the preferred alternative to combining WithRules + MergeRules.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
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 pkg/authz.
|
Package openfga provides an OpenFGA-based Authorizer implementation for pkg/authz. |