Relationship Authorization (OpenFGA)

Overview

DeepIntShield Agentic uses OpenFGA relationship authorization to answer the questions that a tool allow-list cannot:

• Does this user or agent hold the required permission on this exact object?
• May this agent use this tool?
• When the tool exposes named actions, may it execute this exact action?
• If it acts for a user or service account, is there an active delegation for this exact agent, principal, and scope?
• Do groups, roles, ownership, or inherited relationships satisfy the check?

These are not a secondary advisory result. They form the authoritative GAF decision on a modern gateway.

Required mode on the Cloud Run cost tier

The repository’s Cloud Run cost tier deploys OpenFGA with AGENTICNEW_GAF_REQUIRED=true. The server waits for a database-ready OpenFGA sidecar and fails startup if the authorizer, durable store, or base bootstrap cannot become ready. Exact workspace model pins are loaded and refreshed lazily for each decision; a missing or corrupt pin fails that authorization closed rather than taking an ungoverned path. This tier does not silently omit protected routes.

Decision intersection

For an agent-only action:

check(agent, permission, object)
AND check(agent, can_use, tool)
AND check(agent, can_execute, tool_action)  # when the tool exposes a named action
AND optional context policy

For an on-behalf-of action:

check(agent, acts_for, user|service_account)
AND check(agent, delegate, delegation)
AND check(user|service_account, delegator, delegation)
AND check(object, scope, delegation)
AND check(user|service_account, permission, object)
AND check(agent, can_use, tool)
AND check(agent, can_execute, tool_action)  # when the tool exposes a named action
AND optional context policy

Every applicable leg must pass. OpenFGA errors, missing stores, unknown tools or required actions, expired delegations, and missing relationships fail closed.

Server-owned action identity

Internally, action boundaries are versioned and integrity-bound. The everyday UI resolves them to friendly tool and action names; operators do not need to copy their internal object IDs. The gateway still resolves the exact action and its class/risk, so a caller cannot relabel or collide a privileged action by changing request fields.

Workspace surfaces

The canonical UI separates guided access from raw model authoring:

Surface	Purpose
Agentic → Policy & Access → Guided access	Run the full effective-access check, inspect failed legs, grant least-privilege relationships, and manage time-boxed OBO delegations.
Policy & Access → Advanced relationships → Model	Edit, validate, visualize, version, and publish the OpenFGA DSL/JSON model.
Policy & Access → Advanced relationships → Tuples	Create, filter, and revoke raw relationship tuples.
Policy & Access → Advanced relationships → Assertions	Save and run model regression checks.
Policy & Access → Advanced relationships → Explorer	Check subject/relation/object access and list reachable objects.
Policy & Access → Advanced relationships → Changes	Inspect the OpenFGA model and relationship change feed.
Agentic → Identities	Manage users, groups, roles, permissions, service accounts, and effective-permission projection.
Agentic → Activity → Runs	Overlay relationships and per-check results on a specific workflow run.
Agentic → Activity → Decisions	Search the immutable decision ledger and export filtered evidence.

Old ReBAC Studio, Access, Executions, and Agentic Logs bookmarks redirect to Advanced, Policy & Access, or Activity. They do not point to another relationship store.

Configure least privilege

1. Register the workflow. Let the SDK discover its agents, tools, named actions, MCP servers, and network under Agentic → Assets.

2. Create principals. Add users and service accounts under Agentic → Identities, or let the SDK JIT-resolve the acting identity.

3. Define permissions and roles. Bundle permission keys into roles, then assign users, service accounts, agents, or group usersets.

4. Grant tool access. In Policy & Access → Guided access, select the agent, tool, and target resource, then grant access. Use Policy & Access → Advanced relationships → Tuples only for a relationship the guided form does not expose.

5. Grant the exact action when available. If the tool exposes named actions, select the friendly action in the same Access form. Internally, the grant targets the exact versioned tool_action object. A coarse tool grant does not authorize those named operations.

6. Grant object permission. Grant the acting user or agent the required relation/permission on the target resource.

7. Create scoped OBO when needed. Bind the delegation to the exact agent, principal, object, and expiry.

8. Prove it. Run Check access, add assertions under Advanced, and inspect the resulting graph in Activity → Runs and decision in Activity → Decisions.

Discovery writes structural relationships such as organization ownership, network membership, MCP hosting, and tool/action structure. It deliberately does not write authorization grants such as allowed_caller, can_use, or can_execute.

Custom roles and effective permissions

Identities projects management rows into OpenFGA usersets:

• a group’s members inherit grants made to group:<name>#member;
• a role’s assignees inherit the permissions bundled into that role;
• direct permission grants remain visible alongside role-based grants; and
• superuser inheritance is computed by the model.

The user’s Effective permissions view compares the relational projection with OpenFGA. only_in_db, only_in_fga, or diverged means the two sources need reconciliation; it is not silently treated as success.

Advanced workflow

Treat the authorization model like application code:

1. Edit DSL or API JSON in Policy & Access → Advanced relationships → Model.
2. Use live compile/render validation before publication.
3. Add positive and negative checks under Assertions.
4. Run the full assertion suite.
5. Publish and confirm the new model is pinned.
6. Inspect Advanced relationships → Changes, then verify a concrete decision under Activity → Runs.

Published pins are restored on restart. If OpenFGA is unavailable, Advanced may show the shipped fallback model for diagnosis, but publication and authorization remain unavailable/fail closed.

API boundary

The internal base path is /api/agentic-new.

Virtual Key data-plane calls may:

• check authorization;
• list objects reachable through an allowed relation;
• submit a canonical decision;
• resolve the acting identity;
• discover registry topology; and
• write execution lifecycle events.

Virtual Keys cannot write tuples or publish models. Those are operator control- plane operations because a tuple is a permission.

Examples below use an operator session, not a Virtual Key:

BASE="https://gateway.example/api/agentic-new"
AUTH="Authorization: Bearer $SESSION_TOKEN"

# Give an agent the coarse tool capability.
curl -sS -X POST "$BASE/authorization/relationships" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"user":"agent:helper","relation":"allowed_caller","object":"tool:crm"}'

# Use Advanced or the server-generated subject helper for the exact versioned
# tool_action object; do not construct a lossy legacy ID.

Tenant and workspace scope are derived from the authenticated session or workspace-bound Virtual Key. They are not trusted from request bodies.

Consistency and latency

• OpenFGA checks request higher consistency for authorization-sensitive reads.
• Independent decision legs run concurrently under one bounded, fail-closed deadline.
• The process-local Allow cache is disabled by default.
• An operator may explicitly configure a short agent-only cache TTL as the accepted revocation window.
• OBO, explicit-delegation, and contextual decisions remain uncached because their validity is time-sensitive.
• Relationship writes bump the local relationship epoch so cached results on the same replica cannot survive a mediated change.

This design minimizes latency, but cold OpenFGA checks and network calls retain measurable, workload-dependent cost. Across replicas, a durable status or generation change is enforced on the next acquisition or reconciliation; an already leased call may drain, and a passive stream closes on that replica’s next reconciliation. Do not treat cache disablement as synchronous global termination of every in-flight operation.

Evidence

Every mediated tuple change appears in Policy & Access → Advanced relationships → Changes. Every decision is workspace-scoped, append-only, and integrity-protected in Agentic → Activity → Decisions. The normal interface shows integrity status without exposing cryptographic values.

Open a run under Activity → Runs to see the concrete relationship closure—user/service account, group, role, permission, resource, tool, and action—overlaid with each allowed or denied check. This is the fastest way to answer both “what happened?” and “why was it authorized?”