Skip to main content

A05 - Authorization

GroupTechnologyStatusServiceRoadmap phaseContracts
A - Governance, identity and securityOpenFGAopen source integratedauthz1-

Back to index - Français

Role and responsibilities​

Fine grained relationship based authorization (ReBAC) on tenants, projects, agents, tools, knowledge bases.

Data model​

Tables (schema eai, every tenant table carries tenant_id uuid NOT NULL with an RLS policy on current_setting('app.tenant_id', true)::uuid): eai.authz_tuples, eai.audit_events.

API endpoints​

  • POST /v1/authz/check
  • POST /v1/authz/tuples
  • DELETE /v1/authz/tuples
POST /v1/authz/check HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: en
Content-Type: application/json

{"subject": "user:alice", "relation": "can_run", "object": "agent:support-bot"}
{"allowed": true, "backend": "openfga"}

Errors use the common envelope {"error": {"code", "message", "message_i18n", "details", "request_id"}}; lists are paginated with limit and cursor.

Resource relations (ReBAC)​

Routes of projects, agents, tools, knowledge bases, MCP servers, skills and plugins depend on require_relation(relation, type, param): viewer to read, editor to change, owner to delete, can_invoke to run, invoke, query or proxy. Resolution order: direct tuple on the resource (OpenFGA when configured, else eai.authz_tuples), then the project the resource is attached to (project:<id> project <type>:<id>, owner from project, viewer from project), then the tenant role. Tenant roles keep the scope of model.fga: tenant_admin is admin of the tenant, hence owner of every project and its resources; developer and security_officer are tenant editors; other roles are tenant members. Every member is viewer of projects (viewer from tenant). A resource without a project inherits from the tenant. Creating a resource writes the owner tuple and, with X-Project, the project link. A refusal answers 403 relation_required (EN and FR) and is audited as authz.deny. Existing role checks still apply on top of the relation.

SDK usage​

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
decision = client.identity.check(subject="user:alice", relation="viewer", object="project:p1")

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const decision = await eai.authz.check({ subject: "user:alice", relation: "viewer", object: "project:p1" });

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var decision = client.authz().check(Map.of("subject", "user:alice", "relation", "viewer", "object", "project:p1"));

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
decision, err := client.Authz.Check(ctx, map[string]any{"subject": "user:alice", "relation": "viewer", "object": "project:p1"})

Configuration​

  • Environment: EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
  • Helm values: controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config.

Security controls​

  • Authentication by OIDC JWT, tenant API key with scopes, or SPIFFE mTLS; tenant resolved from the credential, never from the body.
  • Authorization through OpenFGA and OPA decisions; every mutation and decision writes a hash-chained eai.audit_events row.
  • Secrets never returned by the API; TLS everywhere; Cilium network policies restrict who can reach the service.

Observability​

  • Metrics: eai_authorization_requests_total, eai_authorization_errors_total, eai_authorization_latency_seconds (Prometheus).
  • Traces: OpenTelemetry spans eai.authz.* with W3C traceparent propagation, AI spans forwarded to Opik.
  • Audit actions: authz.check, authz.write, authz.delete, policy.evaluate.

FinOps aspects​

Operating cost is allocated per tenant and project through labels on Usage Events and Kubernetes resource requests; no direct per-call cost.

Failure modes and resilience​

OpenFGA unavailable: the builtin fallback (tuples in PostgreSQL) answers in dev; in production checks fail closed.

Standalone adoption (client of a client)​

A client of a client can adopt this brick alone with the Python SDK sub-client client.identity (TS eai.authz, Java client.authz(), Go client.Authz). Minimal deployment: Control Plane API + PostgreSQL + Keycloak (or API keys), the Control Plane loads every domain of services/control-plane/src/eai/domains; the optional chart components are switched off in deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Acceptance tests​

  1. A tenant cannot read or modify another tenant's resources (RLS test).
  2. Every mutation produces an audit event verifiable by GET /v1/audit/verify.
  3. Errors are returned in English and French according to Accept-Language.

Effective rights and delegations (kit 7 and 8)​

Every agent action is decided by the intersection user AND agent AND delegation AND resource (relationship check above) AND policy: POST /v1/delegations/authorize returns the decision layer by layer, and a relationship engine error is a deny. A delegation (/v1/delegations) is always a subset of its parent and revocation cascades. See identity-context-delegation.md. Tests: tests/test_identity_context_delegation.py.

Evidence on real components​

See the identity and policy plane guide: components started from the official releases (tools/iam/fetch.sh), tests services/control-plane/tests/test_iam_*.py.