Agent Enrolment

Overview

Every agent that calls a governed tool has to exist in the Agentic Registry with an accountable owner, a risk tier, and its tool access. Reviewing each one by hand is correct for the first few agents and becomes the reason people stop enrolling agents at all once there are two hundred of them on a weekly deploy cadence, which produces shadow AI, not safety.

An enrolment policy states those facts once, for a class of workloads: “any agent this issuer vouches for, whose identity matches this pattern, is owned by this person, runs at this risk tier in this namespace, and draws its tool access from this role.” A workload that matches arrives already described. A workload that does not meet every approval gate remains in Agents → Needs attention for individual review. Enrolment policies are available on Business and above and require the corresponding Agentic create/update permission to configure.

Enrolment is not authorization

An enrolment policy describes an agent; it never decides a tool call. The agent still needs relationships that permit the tool and the action, and every call is still authorized at request time.

Provisioning and enrolment

Agentic → Identities → Provisioning creates or links the external workload identity. Identity providers configures how the gateway verifies its tokens. An enrolment policy applies governance defaults after verified proof arrives. Creating an identity or declaring its expected subject does not itself approve code or grant access.

Keep one identity for a logical agent and environment across runs and replicas. Use separate identities when permissions or revocation must be independent; one human owner may own many agents. Provision outside the agent’s execution loop. Use Authorize provisioning to attach customer-approved management access to the selected verifier for an existing Entra blueprint, Keycloak realm, Auth0 tenant, or Okta organization. Managed identities have lifecycle actions; linked identities remain read-only. See Provision identities from DeepIntShield for connector capabilities, authorization references, and credential delivery.

Created & linked counts provisioning records; cards marked Declaration on the same tab show separate expected identity reservations. A zero count does not mean the workspace has no declarations. Neither record substitutes for the verified proof an enrolment policy requires.

What makes automatic enrolment safe

A policy can only ever match a workload whose identity an identity provider verified. The identity provider is a required field, and matching happens against the verified claim in the agent’s workload token, never against a name the workload chose for itself. An agent that presents no workload proof is never matched by a policy.

Automatic approval requires all of these conditions:

• The current registration is pending and its workload token was verified by the selected identity provider.
• An enabled policy matches that verified workload and still applies when the registration is reviewed.
• Grants via role names the intended granting role userset. A matching policy without a granting role leaves the agent pending for manual review.
• The code scan has completed and its worst finding is within Max scan finding. Select none for a clean scan; incomplete source coverage, a running or failed model scan, and findings above the ceiling cannot be auto-approved.
• Accountable owner resolves to an active human directory entry in this workspace. A nonempty but stale owner subject is insufficient.

The gateway uses the same registration approval and grant-write checks as a human reviewer. The audit records the policy as the approving actor. A failed automatic approval leaves the registration pending; it does not bypass an identity, code, or access gate.

Create an enrolment policy

1. Confirm the identity provider

   Open Agentic → Identities → Identity providers and make sure the issuer that vouches for this class of agents is connected and tested. See Agent workload identity.

2. Open Agentic → Policy & Access → Enrolment

   Select New policy and enter a Name. This form has Verified workload match and Ownership & defaults sections.

3. Set the match predicate

   Field	Meaning
   Identity provider	Required. The issuer whose verified tokens this policy trusts.
   Matches	every agent from this issuer, prefix, or list. These choose all verified identities from the provider, prefixes, or exact listed identities respectively.
   Identity values	Comma-separated values for the prefix and list modes.
   Priority	Evaluation order, lowest first. Ties break deterministically on creation time.
   Max scan finding	The worst blueprint finding severity this policy will enrol through. Anything worse goes to review.

4. Set the defaults applied on match

   Field	Meaning
   Accountable owner	Required. Paste the existing active human’s canonical user:... subject from Identities → Users; this field is a text input, not a new-user form.
   Grants via role	A role userset (for example role:reporting#assignee) that carries the class’s reviewed tool access. Configure the role and its permissions first. A blank value requires manual registration review.
   Risk tier	The default risk level recorded on the agent.
   Namespace	The default namespace the agent is filed under.

5. Enable and verify

   Check Enabled: matching verified workloads may enrol automatically and click Save policy. Run one matching workload with its stable agent name, active reporting key, and provider credential. Confirm the registration’s result under Agents → Agent inventory and the policy’s Enrolled count. A match alone does not imply approval; check Agents → Needs attention if it remains pending.

A policy saved disabled stays disabled. Use Edit to change its defaults or clear Enabled, then Save policy. Delete policy removes that rule. Disabling or deleting a policy stops future matches; it does not revoke grants or remove agents already enrolled. Review existing access separately in Policy & Access.

Complete an individual registration

Open the registration’s Review action from Agents → Needs attention. The review checklist retains completed sections: Identity & owner, Code & changes, Tools & access, Runtime access, Validate changes, and Review & decide.

1. Select an active Accountable owner (an owner proposed from the registering e-mail needs Confirm owner or another choice), confirm the framework, and preserve the stable workspace key. Changing the display name does not change the workload’s token binding.
2. Select a validated Identity provider. A completed provisioning job has already declared the expected identity; otherwise create or link the identity, or declare the external identity once, in this sitting. In Runtime access, authorize the runtime key the developer’s first run enrolled: compare its fingerprint with the SHA256: thumbprint the developer received. A key submitted before the identity existed is marked Provisional and waits for the identity. Provider validation and a reporting key alone do not prove the workload; the proof arrives on the agent’s next run.
3. Review the completed Code scan and exact discovered tool actions. blueprint_coverage_incomplete must be repaired through saved-source discovery with a current SDK. A no-tool calculation may need no tool grants, but still needs complete code evidence.
4. Select only required tool actions and resource permissions. Additional access can reuse reviewed access choices; namespace and governed capabilities do not themselves grant resource permissions.
5. Inspect Runtime access and Validate changes, then open Review & decide. While workload proof is still outstanding, select Approve now, activates on the agent’s next run and confirm with Approve now · activates on next run: the decision is recorded and the next run of the unchanged script activates the agent and executes it; a reviewer other than the accountable owner, and other than an administrator who registered the agent with their own sign-in e-mail, is required. The Decision recorded card lists the actions that activation will grant, which are all the tool actions selected in step 4. Resource permissions are not part of a recorded decision and are added after activation. When proof has been observed, choose Preview approval, inspect the exact planned access, then Confirm approval and access. If Plan saved · access incomplete appears, use Resume saved approval and check completion. Re-review a conflicting plan; archiving it leaves existing grants unchanged. Deny requires a note. The registrant is e-mailed on a recorded decision, approval and denial.

For a saved managed execution, these checks apply to the server runtime and saved source. The client does not need to remain running while the operator completes review.

Follow the full workload setup and review steps for provider setup, credential references, source capture, and proof status. Explicit Approve as VK-trusted (development only), offered with or without a declared identity while the workspace allows it, is a separate unattested trust choice and cannot satisfy an enrolment policy’s verified-identity requirement.

Deferred activation versus an enrolment policy

An enrolment policy admits a whole class of workloads automatically at their attested discover: the token verifies against the policy’s provider, the rule matches, and the registration is approved without a reviewer. A recorded individual decision applies to exactly one registration at its next attested discover of the same code, runtime key and identity; it is pinned to the source digest, scan, declaration revision and runtime-key binding the reviewer saw, and any change makes it stale. Neither runs on the authorization path: both are settled during discovery, before the first governed action, and /decide is unchanged. An explicit Approve as VK-trusted (development only) approval is an immediate, unattested decision; it cannot be deferred and cannot satisfy a policy’s verified-identity requirement. See Registration notifications for the e-mails each route sends.

The registration route by identity type

Every identity type follows the same route: run 1, one review sitting, then the next run. What the sitting contains and what the developer needs before run 2 depend on how the agent proves who it is.

Identity type	What the administrator does in the sitting	What the developer needs before run 2	Runs	Server runs
Plain virtual key (VK-trusted)	Confirms the owner, reviews code and tools, and selects Approve as VK-trusted (development only), with or without a declared identity. The option is offered only while Allow VK-trusted approvals (development only) is on (Policy & Access → Runtime policy → Registration review). Keep that setting off in production workspaces. A VK-trusted approval is never recorded for later and never automatic.	Nothing new: the four settings and pip install deepintshield.	Two	No. Where server runs reach every workspace (*, the default), the program runs on the developer’s machine after its server run ends, and in this release that first local run asks for one more code review. In a workspace listed for server runs the agent cannot run (managed_gateway_runtime_required).
Microsoft Entra with gateway exchange	Confirms the owner, creates or links the identity, authorizes the runtime key by its thumbprint, reviews code and tools, and selects Approve now, activates on the agent’s next run.	The four settings and pip install 'deepintshield[runtime]' from run 1, on the same machine.	Two. Three when no runtime key arrived on run 1.	Yes. It is the only identity type that can finish a server run.
Microsoft Entra direct	Confirms the owner, declares or creates the identity, reviews code and tools, and records the decision. There is no runtime key to authorize.	An Azure host whose identity the agent blueprint trusts, the four settings and pip install 'deepintshield[azure]'. It never works from a laptop.	Two, on an Azure host	No, as for a plain virtual key.
Generic OIDC: Okta, Auth0, Keycloak and any issuer	Confirms the owner, declares the agent’s token subject, reviews code and tools, and records the decision.	The agent’s own client credential on the machine: OIDC_CLIENT_ID plus OIDC_CLIENT_SECRET, or OIDC_CLIENT_AUTH_METHOD=private_key_jwt with OIDC_PRIVATE_KEY_FILE.	Two, only when that credential is on the machine before run 2	No, as for a plain virtual key.
ZeroID (experimental)	The provider is configured through the API beforehand. In the sitting, the same steps as Generic OIDC.	ZEROID_SUBJECT_TOKEN and ZEROID_EXCHANGE_ENDPOINT.	Two, when both are set before run 2	No, as for a plain virtual key.
SPIFFE	Not available for registration. A SPIFFE provider cannot be created.	Not applicable	Not applicable	Not applicable

For Generic OIDC, the issuer and its signing keys must be reachable at a public https address on port 443. A Keycloak on a private network therefore cannot be verified. The gateway accepts tokens that live one hour or less; set the token lifetime at the issuer. The subject to declare depends on the issuer: for Okta it is the client id, for Auth0 <client id>@clients, and for Keycloak the service-account user id.

An administrator who registered an agent with their own sign-in e-mail cannot record its decision. While Require a separate reviewer for immediate approvals is on, they cannot approve it at all. In a one-person workspace, approve immediately after the agent’s next run (three runs), or register the agent with a different e-mail.

Re-enrolling after a denial

A denied registration is not edited; the audit trail grows rather than being rewritten. An operator supersedes the denial with a new registration that references and overrides it, so the original decision and its reason remain readable. Until that happens, status() reports denied. Resolve the recorded denial with an operator; changing a workload’s name is not approval of the denied implementation.

Use Re-enrol agent from its declaration in Identities → Provisioning when offered for a denied registration, then collect fresh proof and complete review. Denial does not free an identity that another registration has already proven. Release declaration is available only for an unbound declaration with no proof in its current or historical registration. Provisioning or linking another identity does not erase the original decision.

An ordinary approved registry agent may also be Quarantined or Reactivated from Agents → Agent inventory. Reactivation is not a substitute for resolving pending or denied registration, code review, or retired identity state.

Code changes after approval

An approved agent whose code changes is re-scanned, and the new scan is compared against its approved baseline rather than judged from scratch:

• With Block runtime drift off (the default), a change that introduces no new finding and escalates none can be admitted without another review against a valid approved baseline.
• A new or escalated finding sends the agent back to review and quarantines it in the meantime.
• Findings the change resolved are shown in the delta so a reviewer sees the whole picture, not only the bad half.

With Block runtime drift on, every different observed digest is quarantined for fresh review, including clean deltas and a rollback to an older approved digest. An enrolment policy does not exempt an already approved workload from this check. Turning strict mode off does not release an existing quarantine.

Mandatory scanning remains active in either mode. Configure blueprint_runtime_enforce under Policy & Access → Runtime policy → Blueprint protection; it defaults to false and requires no SDK change. See Blueprint code review for coverage limits and the review flow.

Automation and CI

Governance objects (identity providers, enrolment policies, grants, agents) are control-plane objects, so mutating them normally requires an operator signed in to the workspace. A control-plane token is the machine credential that lets the same objects be declared in version control and applied by a pipeline.

Route	Purpose
GET /api/agentic-new/control-plane-tokens	List tokens in the active workspace.
POST /api/agentic-new/control-plane-tokens	Issue a token. Body: {"name": "...", "lifetime_days": 90}.
DELETE /api/agentic-new/control-plane-tokens/{id}	Revoke a token immediately.

Token handling

• The secret is returned once, by the create call, and is never stored; only its hash is. A lost token is replaced, not recovered.
• An expiry is required. A machine credential with no expiry becomes a permanent key in a CI variable that nobody rotates.
• A token is scoped to one workspace and is refused if presented against another.
• A control-plane token cannot manage control-plane tokens. Issuing and revoking require an operator session, so a leaked token cannot mint itself a replacement ahead of revocation.

Next steps

• Agent workload identity: verified agent tokens, proof-of-possession, and SPIFFE.
• Agentic: the full control-plane workflow.
• Relationship Authorization: roles, resources, tools, actions, and delegation.