Binding subjects
An Access Binding grants access to its subjects. You author six subject types. AIControls adds one more, the derived workload subject, for every Workload Blueprint or registration that references the binding.
Subject types
Subjects on one binding are OR-combined: a request matches the binding when it matches any subject.
| Type | Value | Matches when |
|---|---|---|
team | Team name | The delegating user belongs to the team (object.user.teams). |
group | IdP group claim, for example okta:eng-platform | The delegating user carries the group claim (object.user.groups). |
user | Email address | The delegating user's email is the value (object.user.email). |
agent | Agent ID, with an optional single trailing * | The agent ID equals the value, or starts with the prefix before * (object.agent.agentId). |
agentLabel | key and value | The agent carries the label with that exact value (object.agent.labels). A missing label never matches. |
everyone | None, or * | Every caller: every person, agent, and workload. The binding's other subjects don't matter, but its servers, tools, models, and conditions still limit what it grants. |
The legacy groups field still works: a binding with no subjects treats each group as a group subject.
The binding editor's Type list doesn't include everyone, so add it through the Access Bindings API with {"type": "everyone"}. When you open a binding that has one, the editor shows the raw type everyone and the value *. The API stores its value as * and rejects any other value or a key.
A binding can name no subject at all. It then grants nothing until a Workload Blueprint or registration references it. The binding editor warns you when you save such a binding.
Derived workload subjects
This section applies only to self-managed installations, because Workload Trust isn't available on Nirmata-hosted workspaces. The rest of this page applies to every deployment. See Feature availability.
A Workload Blueprint selects exactly one Access Binding, and a registration's override can list more in bindingRefs. For each binding that reaches a workload, AIControls adds a derived subject that matches the workload's effective access policy ID:
object.agent.workload.accessPolicy != "" && object.agent.workload.accessPolicy in ["<effective policy IDs>"]
The derived subject has these properties:
- You can't author it. The Access Bindings API rejects any subject type other than the six above.
- It keys only on
object.agent.workload.accessPolicy. AIControls publishes that field only from a coherent registration snapshot bound to the verified, cluster-qualified Kubernetes ServiceAccount identity. It never keys on the workload name, kind, namespace, binding rung, Blueprint name, labels, or owner references. - A missing, stale, conflicting, or incoherent registration publishes an empty
accessPolicyand matches no derived subject. A heuristic match also matches nothing. - All Pods that run as one ServiceAccount are one principal. A discovered shared ServiceAccount raises a warning but doesn't change the grant.
- Workloads of one Blueprint with no override share one effective policy ID. A workload whose override adds references or blocks has its own, so it matches only its own references.
- A reference to a missing or disabled binding grants nothing.
The derived subject joins every policy the binding compiles to, exactly like an authored subject: the per-server gate (mcpaccessbinding-gate:<server>), the exact allow marker, the tool-scoped decision mode, conditions, input and output conditions, scopes, the unlisted-tool posture (mcptooldefault:<server>), and model selectors. A binding that no workload references compiles byte for byte as it did before derived subjects existed.
Referenced binding contents are live. When you edit a referenced binding, or a Toolset that it references, the change applies to every workload that uses it on its next call without a rollout, after an impact preview. See Review and restore a binding change. The Used by panel in the binding editor lists the Workload Blueprints and registrations that use the binding. A Blueprint appears only when the Blueprint itself selects the binding; a reference that only a workload's override carries lists the workload, not its Blueprint. Each Blueprint links to its detail drawer on the Blueprints view of Inventory → Workloads, and each registration links to the workload's AI access tab.
Rate limits
Binding rate limits count every subject the binding matches, including referencing workloads. With per: agent, a workload counts under its cluster-qualified ServiceAccount identity, so the same namespace and ServiceAccount in two clusters never share one counter.