Skip to content

Guided tour

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

MODULE 08 · LESSON 8.4

Configure and test ACL policy

Express cross-principal policy with roles, groups and explicit grants.

Lesson 46 of 86 · FabrCore 2.0

Overview

ACL governs operations such as message, create, read, reconfigure and destroy. Principals and groups organize subjects; roles collect permissions; grants bind subjects to resources. Denials and read filtering must remain observable and predictable.

Policy is evaluated for a subject, action and resource

A principal or group identifies the subject. Roles collect permissions, and grants apply those permissions to a resource. Be explicit about whether the caller may message, read, create or reconfigure an agent; permission to chat is not permission to reset its state. A filtered listing and a denied direct operation are different visible consequences of policy.

Conditional writes protect concurrent operators

Administrative ACL updates use a version/revision read from the registry so an operator cannot unknowingly overwrite newer policy. Built-in protections remain in force. When a conditional write fails, reload and review the actual policy instead of retrying blindly without the precondition. The Cloud Server is an authenticated client of this policy surface, not a new source of user consent.

Apply and test an ACL grant

  1. Use the ACL administration API to create principals/roles/groups and grant the minimum resource pattern required by the workflow.
  2. Test same-principal and cross-principal requests. Inspect allow/deny precedence and system-agent access rather than assuming every shared agent is unrestricted.
  3. Use AuditOnly deliberately when observing a policy transition; read filtering can still protect data. Add application permissions through the supported extension surface.
SDK Client Methods (`IFabrCoreHostApiClient`) · reference snippet 
// Grant P1's agent1 cross-talk to P2's agent3 (as System / an acl-admin):
await client.UpsertAclGrantAsync("system", new PermissionGrant
{
    Subject = new AclSubject(SubjectKind.Agent, "p1:agent1"),
    Permission = FabrPermissions.AgentMessageAllow,
    Resource = "p2:agent3"
});
Permission names
Permission Enforced at
agent.message.allow/deny PrincipalGrain sends/events; AgentGrain a2a sends/events
agent.create.allow/deny PrincipalGrain.CreateAgent — resource's principal segment = "for whom"
agent.reconfigure.allow/deny PrincipalGrain.ResetAgent
agent.destroy.allow/deny PrincipalGrain.UntrackAgent
agent.read.allow/deny Monitor read filtering (MonitorController, SSE stream)
acl.manage.allow/deny ACL management API mutations
acl.read.allow/deny ACL/audit read endpoints, evaluate/check

Test allow, deny and stale edits

  1. Grant a test subject only the intended read/message permission to a disposable resource. Verify the allowed operation succeeds and a reconfigure/destroy attempt remains denied.
  2. Remove the grant and repeat the access check. Inspect policy/audit context so a denial is distinguishable from a missing agent or transport failure.
  3. Read an ACL version, change policy through another test operator, then submit against the old version. Expect a conflict and reload before reviewing the next update.

The test demonstrates effective policy and edit concurrency. A successful grant save alone does not establish that the expected request path enforces it.

If the result is different

Normal 2.0 startup is not a legacy ACL seed importer. Use migration/admin APIs; a grant on an agent type alias is not the same as a resource handle pattern.

Go deeper

Explore the related documentation.