Introducing caipe-authz: one authorization service, migrated safely

[sriaradhyula]

What is changing?

CAIPE is introducing caipe-authz, a standalone authorization service that gives the BFF and AgentGateway one consistent policy decision point while allowing each path to migrate independently.

This is the concrete evolution of the Central Authorization Service proposal in discussion #1778. The service name is caipe-authz; “central authorization service” describes its architectural role.

The implementation is available for review in PR #2395.

Why introduce a separate service?

Today, authorization behavior exists in more than one runtime. Conditional policy makes duplication riskier because every enforcement path must agree on:

• Which identity and resource are being checked.
• Which request attributes are trusted.
• How input schemas are pinned and drift is handled.
• How decisions are audited and compared.
• How enforcement can be promoted or rolled back safely.

caipe-authz centralizes those responsibilities without requiring a flag-day replacement of the current paths.

Architecture at a glance

flowchart LR
    BFF["CAIPE BFF"] --> BR["BFF migration router"]
    GW["Envoy / AgentGateway"] --> GR["Gateway migration router"]

    BR --> LEGACY["Existing evaluators"]
    GR --> LEGACY
    BR --> AUTHZ["caipe-authz"]
    GR --> AUTHZ

    AUTHZ --> CTX["Trusted context builder"]
    AUTHZ --> POL["Typed policy templates"]
    CTX --> FGA["OpenFGA relationships + CEL"]
    POL --> FGA
    AUTHZ --> OUTBOX["Durable audit outbox"]
    OUTBOX --> AUDIT["Audit Service"]
    AUTHZ --> GRAPH["Sanitized inspection graph"]
    AUDIT --> UI["CAIPE admin UI"]
    GRAPH --> UI

Loading

One decision core, two transports

The transport adapters normalize different protocols before policy evaluation:

sequenceDiagram
    autonumber
    participant App as Application caller
    participant BFF as CAIPE BFF
    participant Gateway as Envoy / AgentGateway
    participant Authz as caipe-authz decision core
    participant Context as Trusted context resolvers
    participant FGA as OpenFGA + native CEL
    participant Outbox as Durable audit outbox

    alt Application authorization
        App->>BFF: Protected HTTP request
        BFF->>Authz: HTTP or batch decision request
    else Gateway authorization
        App->>Gateway: MCP tools/call
        Gateway->>Authz: ext_authz CheckRequest
    end
    Authz->>Authz: Normalize subject, action, and resource
    Authz->>Context: Resolve trusted identity, schema, and request context
    Context-->>Authz: Typed bounded context and revisions
    Authz->>FGA: Check relationship with explicit model ID and context
    FGA-->>Authz: Allowed or denied
    Authz->>Outbox: Journal one normalized decision event
    Authz-->>BFF: HTTP decision when BFF is the caller
    Authz-->>Gateway: gRPC decision when gateway is the caller

Loading

Neither adapter selects a policy provider or changes failure semantics. A deny
from the shared decision core remains a deny at both enforcement points.

Layer	v1 choice
Universal entry point	One caipe-authz service
Application transport	HTTP and batch HTTP
Gateway transport	Envoy ext_authz gRPC
Relationship authorization	OpenFGA
Conditional expressions	OpenFGA-native CEL
Context construction	Trusted, typed, and bounded inside caipe-authz
Policy authoring	Named, typed, versioned templates
Future providers	Cedar and OPA extension points, disabled in v1

How conditional policy works

Conditional policies are constructed at two different times:

1. Build/release time: developers define and review named CEL conditions plus typed template versions.
2. Policy-administration runtime: administrators instantiate a template for a resource; caipe-authz validates the policy, pins the applicable schema, and reconciles condition constants onto an OpenFGA tuple.
3. Request runtime: caipe-authz derives bounded context from authenticated request data. OpenFGA evaluates the relationship and its condition.

Administrators and callers cannot submit arbitrary CEL. Caller-provided values are never treated as trusted policy constants.

The existing model.fga gains named conditions and conditional relations, but remains additive during migration. The OpenFGA bridge changes only enough to pass canonical trusted context for exact-tool checks; broad legacy checks remain context-free until their scope is promoted.

Policy creation and request evaluation are separate

sequenceDiagram
    autonumber
    actor Admin as Administrator
    participant UI as Policy UI
    participant Authz as caipe-authz policy API
    participant Catalog as Tool schema catalog
    participant Metadata as Policy metadata
    participant FGA as OpenFGA
    participant Request as Later protected request

    Admin->>UI: Choose exact tool, subject, template, field, and values
    UI->>Authz: Save typed template instance
    Authz->>Catalog: Validate field type and current schema hash
    Catalog-->>Authz: Eligible field and trusted schema hash
    Authz->>Metadata: Persist RECONCILING revision
    Authz->>FGA: Write and read-back conditional tuple
    FGA-->>Authz: Verified condition name and constants
    Authz->>Metadata: Mark policy ACTIVE
    Authz-->>UI: Active policy revision

    Note over Admin,FGA: No request argument is used while authoring policy

    Request->>Authz: Authenticated call with observed request arguments
    Authz->>Catalog: Resolve current schema and eligible projection
    Catalog-->>Authz: Current trusted schema hash
    Authz->>FGA: Check with typed request context
    FGA-->>Authz: Relationship and condition result
    Authz-->>Request: ALLOW or DENY

Loading

The tuple stores administrator-controlled constants. The Check request carries
request-derived values, so a caller cannot replace the policy field, allowlist,
or expected schema hash.

Can one service handle both the BFF and gateway?

Yes. The transports differ, but the decision contract is shared:

• The BFF calls HTTP or batch HTTP.
• Envoy and AgentGateway call ext_authz gRPC.
• Both receive the same normalized decision, reason, provider metadata, revision, and audit behavior.
• BFF and gateway rollout modes are stored and promoted independently.

Why CEL first instead of Cedar or OPA?

OpenFGA already owns CAIPE relationship authorization. OpenFGA-native CEL lets v1 evaluate relationship and request conditions together without introducing a second authoritative engine or translating semantics between languages.

The provider interface leaves room for Cedar or OPA later, but they are intentionally disabled in v1. Enabling another provider should require a concrete use case, conformance tests, equivalent audit semantics, and an explicit decision about which engine is authoritative.

Parallel rollout

Each BFF or gateway scope advances independently:

Mode	Authoritative result	What else runs?
LEGACY	Existing evaluator	No caipe-authz decision required
SHADOW	Existing evaluator	caipe-authz runs asynchronously for comparison
CANARY	Deterministic per-subject cohort	Non-canary traffic remains legacy-authoritative
AUTHZ	caipe-authz	Legacy stays available for comparison and routing rollback
AUTHZ_ONLY	caipe-authz	Legacy is not invoked

stateDiagram-v2
    [*] --> LEGACY
    LEGACY --> SHADOW: deploy and compare
    SHADOW --> CANARY: promotion evidence passes
    CANARY --> AUTHZ: bounded cohort is healthy
    AUTHZ --> AUTHZ_ONLY: enter retention window

    CANARY --> SHADOW: routing rollback
    AUTHZ --> SHADOW: routing rollback
    SHADOW --> LEGACY: disable comparison
    AUTHZ_ONLY --> AUTHZ: rollback while legacy release is retained

    AUTHZ_ONLY --> RETIRED: retention and removal gates pass
    RETIRED --> [*]

Loading

AUTHZ_ONLY stops invoking legacy code but does not immediately delete it.
RETIRED is a later, separately reviewed removal step.

Promotion requires evidence for model compatibility, context-schema compatibility, audit health, semantic parity, provider errors, latency SLOs, ownership, and rollback readiness.

Two independent rollback paths

• Routing rollback moves a scope to its previous evaluator. It never writes or deletes OpenFGA tuples.
• Policy rollback changes only the targeted conditional policy revision. It does not restore broad legacy grants or change which evaluator is authoritative.

Physical removal of legacy code is deferred until every applicable scope completes the configured AUTHZ_ONLY retention period and a compatible rollback release still exists.

Audit and visualization

The CAIPE admin UI adds:

• Side-by-side legacy and caipe-authz outcomes, reasons, errors, provider codes, and durations.
• Filters for rollout revision, authoritative path, and mismatch class.
• Evidence summaries for sample size, semantic parity, provider errors, and latency completeness.
• Graph layers for current conditional relationships, policy and relationship history, migration comparisons, rollout revisions, schema drift, exclusive policies, and shadow warnings.

Inspection and audit projections expose structure, identifiers, hashes, and revisions—not tool argument values or condition constants.

Current state and history remain separate

flowchart LR
    UI["CAIPE authorization explorer"] --> BFF["Admin BFF"]
    BFF --> Inspect["caipe-authz inspection API"]
    Inspect --> FGA["OpenFGA current model and tuples"]
    Inspect --> Metadata["Current policy metadata"]

    BFF --> Audit["Audit Service query API"]
    Audit --> History["Decisions, changes, comparisons, revisions"]

    Inspect --> Current["Current authorization graph"]
    History --> Overlay["Historical and migration overlays"]
    Current --> Layers["Joined display layers"]
    Overlay --> Layers
    Layers --> UI

Loading

OpenFGA and active policy metadata define current access. Audit events annotate
that graph with history and rollout evidence; replaying audit history never
creates the current authorization state.

Security and operational invariants

• Deployment is disabled and dark by default in Helm and Docker Compose.
• A denied exact-tool call is stopped before the MCP server.
• Missing, malformed, oversized, wrong-type, or stale-schema context cannot satisfy a conditional grant.
• Existing unconditional grants continue to work during the additive migration period.
• Required audit persistence fails closed for strict allow decisions.
• Sensitive-value tests scan logs, audit events, fixtures, and graph responses.

What has been validated?

PR #2395 includes automated proof for:

• LEGACY → SHADOW → CANARY → AUTHZ → AUTHZ_ONLY against a real caipe-authz gRPC server and pinned OpenFGA v1.15.1 container.
• Independent BFF and gateway replay and routing rollback.
• Tuple-preserving routing rollback and scoped policy rollback.
• Denied exact-tool calls never reaching an MCP recorder.
• Promotion, retention, legacy-retirement, schema-drift, audit-delivery, and redaction gates.
• Admin graph history, audit overlays, revision layers, and comparison views.

The PR description contains the complete test counts and packaging checks.

Feedback requested

We would especially value feedback on:

1. Are the five rollout modes understandable and operationally sufficient?
2. Which initial typed conditional-policy templates would be most useful?
3. What promotion thresholds and AUTHZ_ONLY retention period should become defaults?
4. Which graph or comparison evidence would help operators approve a promotion?
5. What concrete requirement would justify enabling Cedar or OPA after v1?

Please use this discussion for architecture and rollout feedback, and PR #2395 for implementation-specific review.