Limit surface access by agent identity

Choose an identity slot

The Identity element can sit in three positions on the surface canvas. Each position maps to a different edge in the request–response pipeline:

Transit Points support a fourth per-upstream slot. See Apply policy to outbound calls for Transit Point configuration.

Most operators start with the Inbound caller slot: derive the caller’s DID so policies and audit logs record who made each request.

Add the Identity element to the canvas

1. Open Surfaces in the dashboard and select the surface to configure.
2. In the left palette, find the Identity element under Enhancements.
3. Drag Identity onto the canvas and drop it on the edge that matches the slot you chose in Step 1.
   • Inbound caller: drop on the arrow between the Access Point and the Managed Agent node.
   • Protected agent: drop on the return arrow from the Managed Agent back toward the Access Point.
   • External agent: drop on the arrow between the External Target and the Managed Agent node.
4. Select the Identity node. A context banner at the top of the configuration panel confirms which slot the node occupies and what it identifies.

Configure the extraction type

Select an extraction type from the Identity Extraction Type dropdown. The type determines how the gateway derives the agent’s DID.

From Payload (identity metadata)

Derives the DID from named fields in the request or response body. The same field values always produce the same DID.

1. Select From Payload (identity metadata).

2. Select Configure Fields… to open the field editor.

3. In the field editor, paste a sample payload that your agent sends. The editor extracts a JSON schema from it.

4. Mark the fields that uniquely identify the agent by enabling "x-identity": true on each one. Only marked fields contribute to the DID hash. All other fields remain available to policy evaluation but do not affect the DID.

   Example: an agent distinguished by LLM provider and model name.

   {
     "type": "object",
     "properties": {
       "agentIdentity": {
         "type": "object",
         "properties": {
           "llmInfo": {
             "type": "object",
             "properties": {
               "provider": { "type": "string", "x-identity": true },
               "model":    { "type": "string", "x-identity": true }
             }
           }
         }
       }
     }
   }

5. Optionally enable Strip raw identity metadata after injection. When on, the raw _meta.[field] block is removed from the forwarded request after the gateway has injected the signed credential. This prevents the raw identity block from reaching the managed agent.

6. Close the editor.

The meta_field defaults to agentIdentity on the request leg and serverIdentity on the response leg. These match the A2A, AP2, and MCP extension conventions. Change the field name only if your agents use a different key.

For background on how the hash is computed, see Agent identity and DIDs.

From API Key

Derives the DID from a stored API key identifier. The derived DID is stable across key rotation. See Agent identity and DIDs for how this works.

1. Select From API Key.
2. In the API Key dropdown, select an active API key. If the list is empty, create one under Secrets → API Keys first.

From mTLS certificate

Derives the DID from a stored client-leaf certificate. As with API key mode, the DID is stable across certificate rotation. See Agent identity and DIDs for how this works.

1. Select From mTLS certificate.
2. In the Client Certificate dropdown, select a certificate. Only active certificates with kind Client leaf appear in this list. If the list is empty, add a certificate under Secrets → Certificates and set its kind to Client leaf.

From JWT Claims

Derives the DID from a claim in the caller’s validated bearer token. One stable DID is minted per distinct claim value. See Agent identity and DIDs for the full derivation model.

1. Select From JWT Claims.
2. In JWT Claim, enter the claim name that identifies the agent. The default value is oid, the Microsoft Entra Agent ID object identifier.
3. In Namespace Claims, enter any additional claims to fold into the identity hash, separated by commas. For example, entering iss, tid prevents the same oid value across different tenants from resolving to the same DID. All listed claims must be present in the token or the request fails with a 422 response.

Static DID

Always presents the same fixed DID for all requests through this slot. Useful for stub agents and integration tests.

1. Select Static DID.
2. In the Static DID field, enter the DID, for example did:web:example.com:agents:my-stub.

Create a surface policy that uses the derived identity

Once the Identity element is configured, the derived DID is available in OPA policy context as input.agent.did. Use a surface-scope (surface.policy) policy to gate requests based on that value.

1. In the sidebar, select Policies.
2. Select the Agent Surfaces tab.
3. Select Define Agent Surface Policy.
4. Fill in the form:
   • Name: for example, require-known-agent.
   • Type: select Agent Surfaces.
5. In Policy Content (Rego), write the policy rule.

Deny anonymous callers (any DID is sufficient)

The simplest check: the request must have produced a DID. Callers that carry no identity extension or credential are denied.

package surface.policy

default allow = false

allow if {
  input.agent.did
}

Require a specific agent DID

Restrict access to one or more known agents by DID.

package surface.policy

default allow = false

allowed_dids := {
  "did:webvh:gateway.example.com:channel:9fd06096-0188-4979-aa99-8171cde7090a",
  "did:webvh:gateway.example.com:channel:3b2c71de-a482-4c22-b9f6-e90d3fa01abc"
}

allow if {
  allowed_dids[input.agent.did]
}

Combine identity with caller authentication

When the surface also has a Caller Context element, require both a valid credential and a resolved DID.

package surface.policy

default allow = false

allow if {
  input.source_auth.subject
  input.agent.did
}

Gate on JWT claim values directly

For surfaces using From JWT Claims, the full token claim set is also available on input.source_auth.claims.

package surface.policy

default allow = false

allow if {
  input.source_auth.claims.tid == "<expected-tenant-id>"
  input.agent.did
}

Select Save. The policy appears in the list with status Enabled.

Attach the policy to the surface

A policy definition has no effect until it is attached to a surface using the Policy canvas element.

1. Open Surfaces and select the surface you added the Identity element to.
2. In the left palette, find Policy under the Security & Policy category.
3. Drag Policy onto the canvas and drop it on the arrow leaving the Access Point to evaluate the rule on every inbound request.
4. Select the Policy element to open its config panel. In the Policy Definition dropdown, select the policy definition you created in Step 4. Only enabled Agent Surfaces definitions appear.
5. Select the Save changes button (the blue disk icon in the toolbar) or press Cmd+S (macOS) / Ctrl+S (Windows/Linux).