AGNTCY Identity Claims (experimental)
Unreleased integration
The HTTP/JWS v2 protocol is a draft. The verifier (identity#182)
and Node fix (identity#181) are
unreleased prerequisites. This opt-in integration is for evaluation; pin compatible
builds of both before enabling it. The database migration adds a nullable
valid_until column even when the verifier is not configured.
An AGNTCY identity is declared in the record's agntcy.dir/identity annotation:
{
"annotations": {
"agntcy.dir/identity": "agntcy://AGNTCY-security-autonomous-agent"
}
}
The record declares one identity and may have multiple signed claims. The identity reconciler checks an applicable claim's agent signature and, by default, requires an Agent Badge that binds that Agent ID to the exact record CID. Verification is asynchronous; pushing a claim does not make the record verified.
This integration adapts the reference implementation to Directory's current public-key resolver and canonical claim payload. See proposal #2291.
Architecture and storage
flowchart LR
P[Publisher] --> O[OASF record]
P --> C[Native IdentityClaim]
C -->|OCI manifest subject| O
O --> R[Identity reconciler]
C --> R
R --> K[AGNTCY claim resolver]
K -->|One full-claim request| V[External AGNTCY Identity Verifier]
V --> N[Identity Node]
V -->|Signed keys and badge evidence| K
K --> S[Native claim signature check]
S --> DB[Verification database]
DB --> Q[Status and search]
| Object | Location |
|---|---|
| Record and identity annotation | Directory content store |
| Signed claim | Native OCI referrer, type agntcy.dir.identity.v1.IdentityClaim |
| Signed Agent Badge and public-key metadata | AGNTCY Identity Node |
| Verification result and deadline | Directory database |
The claim is JSON in a RecordReferrer. The OCI referrer's manifest subject
references the record's manifest. This uses the existing claim schema and storage
APIs. The claim contains the Agent ID as its resolution reference; it has no badge
or badge URL field. The Identity Node hosts the actual signed badge.
The agntcy:// suffix is a case-sensitive Agent ID of 1–512 ASCII letters, digits,
-, _, ., or ~. . and .. are rejected. Paths, ports, user information,
percent escapes, queries, and fragments are rejected. URLs come from operator
configuration; an Agent ID cannot select a network endpoint.
Verification contracts
All schemes use the shared resolver contract, with optional claim input and an output validity deadline:
Resolve(ctx context.Context, subject string, certificate []byte, opts ...resolvers.Option) ([]crypto.PublicKey, error)
The reconciler passes resolvers.WithClaim(claim) and
resolvers.WithValidUntil(&until) to Resolve. AGNTCY requires a complete claim,
including in control-only mode, and sends one /v1/verify request per candidate.
There is no key-only AGNTCY endpoint or subject-only evidence cache. DID, SPIFFE
and ANS may ignore these options and keep their existing key-resolution behavior.
The resolver authenticates the service response and enforces the configured badge
policy. Directory then verifies the native detached JWS locally against the
returned keys. No certificate is allowed on an AGNTCY claim. The canonical payload
signs record_cid, role, subject, signed_at, and expires_at, in that order;
an absent expiry is an empty string. Evidence for one CID cannot verify another
record sharing the Agent ID.
sequenceDiagram
participant R as Directory reconciler
participant V as External AGNTCY Identity Verifier
participant N as Identity Node
participant D as Directory database
R->>R: Check CID, declared subject, role and expiry
R->>V: POST /v1/verify (profile, subject, signature, payload, nonce)
V->>N: Resolve assertion keys
V->>V: Verify native claim signature
V->>N: Fetch signed badges and verify candidate badge
V->>V: Check badge subject, definition CID and validity
V-->>R: Signed keys, identity/badge outcomes and deadline
R->>R: Authenticate response, bindings and selected policy
R->>R: Verify claim signature locally against returned keys
R->>D: Persist result and earliest deadline
The experimental HTTP protocol is agntcy.identity-verification.v2.
POST /v1/verify returns { "resultJws": "<compact embedded JWS>" }.
The signed result includes operation kind, verifier ID, profile, policy version,
checks.identity, checks.badge, aggregate outcome, authorized public JWKs,
subject, exact record CID, SHA-256 digest of the compact request JSON, check time,
and expiry. Each request includes a fresh random nonce covered by the digest.
The digest also covers the requested profile, canonical claim payload and agent
signature. Directory rejects v1 responses and incomplete v2 evidence.
The service may expose /v1/resolve for key-only callers; Directory's AGNTCY
reconciler uses only the combined /v1/verify operation. One Directory request can
require multiple internal Identity Node API calls.
Directory pins the service's response-signing keys, checks every binding, rejects stale or expired results, and derives signature algorithms from the trusted keys. HTTP success alone cannot establish verification. Redirects are disabled.
Badge policy and implementation limits
The companion Identity verifier uses profile agntcy-agent-badge.v1 and policy
subject-key-badge.v1. It delegates credential verification to the configured
Identity Node, then requires AgentBadge type, exact credentialSubject.id, and
an embedded credentialSubject.badge whose Directory CID matches the claim.
It also enforces supplied credential/JWT start and expiry fields.
This policy names the reference Identity Node's subject-key-backed verification. It establishes agent control and badge/record consistency. Independent issuer authorization and credential revocation/status-list processing need a separately defined policy and implementation before production adoption. This service does not implement them. The verifier's result key is loaded from a PEM file; KMS/HSM result signing is also a future integration.
Reconciler configuration
reconciler:
identity:
enabled: true
interval: 15m
record_timeout: 1m
agntcy:
verifier_url: https://identity-verifier.example.com:8443
verifier_trust_bundle_file: /etc/agntcy/verifier-keys.json
verifier_id: agntcy-identity-verifier
profile: agntcy-agent-badge.v1
require_agent_badge: true
bearer_token_file: /etc/agntcy/verifier-token
request_timeout: 10s
max_verification_age: 30m
The trust bundle is a public JWKS (multiple keys permit rotation) or one PEM
SubjectPublicKeyInfo public key. It authenticates service results and is separate
from the agent keys and HTTPS CA trust. Trust and token files are reloaded at the
start of each reconciliation run. Invalid initial configuration is rejected.
A later reload failure returns a task error before any records are reconciled.
Existing observations still expire at their stored deadlines. require_agent_badge defaults to true; disabling
it establishes only control of the declared identity. The pinned service ID
defaults to agntcy-identity-verifier.
The companion service requires bearer authentication. The resolver can instead use
an injected authenticated HTTP client when embedded by an operator; daemon
configuration should provide bearer_token_file for this service. HTTPS CA trust
uses Go's system roots; private deployments can provide SSL_CERT_FILE or
SSL_CERT_DIR in the process environment.
Deploying the external verifier
The verifier belongs to the AGNTCY Identity deployment. Directory contains the client adapter and reconciliation wiring. Configure its URL, response-signing trust bundle, authentication, profile and time limits as shown above.
The companion verifier PR provides
the service, Dockerfile and deployment instructions in the Identity repository's
integrations/directory-verifier module. It uses the Node's
/v1alpha1/id/resolve, /v1alpha1/vc/<agent-id>/.well-known/vcs.json, and
/v1alpha1/vc/verify APIs. Only keys referenced by assertionMethod are accepted.
The feature is optional: without agntcy.verifier_url, AGNTCY claims fail closed
and other resolver schemes keep their existing behavior. Badge verification is
required by default. Explicitly setting require_agent_badge: false selects the
agntcy-agent-control.v1 profile, which establishes identity control only and does
not fetch badges. A mismatched configured profile is rejected.
Freshness and search
Each verified result has an optional valid_until database column. The AGNTCY
deadline is the earliest of claim expiry, combined-result expiry, and the configured maximum
verification age. Combined-result expiry is also bounded by the matching badge's
expiry. Every accepted AGNTCY result must have a deadline.
Startup rejects a configured AGNTCY verifier when identity.interval is not
positive or is at least max_verification_age (default 30 minutes). The task's
one-hour default therefore requires an explicit shorter interval; the example
uses 15 minutes. Allow time for the full reconciliation run, and choose an interval
shorter than the service's signed result lifetime and badge lifetime too: a maximum
age is a cap, not a promise of that much validity.
An outage may preserve the previous observation only until its deadline and the AGNTCY scheme grace (the configured maximum verification age). Expired results are reported as failed by status reads and excluded by verified search immediately, even between runs. This immediate expiry guarantee applies to identity status and verified-search filters. Stored policy verdicts are invalidated by the next successful reconciliation write; the policy read gate does not independently expire them at the identity deadline. Under normal operation this write occurs on the next reconciliation run. Interrupted runs, configuration reload failures or failed writes can delay it further, so the interval is not a strict freshness bound for stored policy verdicts.
Authoritative rejections such as withdrawn keys or missing valid badges fail
verification. Withdrawn claims remove the stored result on reconciliation.
The column is added by the existing database auto-migration; existing rows with a
null deadline retain their previous behavior. valid_until is internal to the
database and is not added to the protobuf response in this draft.
dirctl identity claim --record <cid> --role identity --key agent.key
dirctl identity status <cid> --output json
dirctl search --identity 'agntcy://*' --identity-verified
dirctl search --identity 'agntcy://AGNTCY-security-autonomous-agent' --identity-verified
API search combines RECORD_QUERY_TYPE_IDENTITY with
RECORD_QUERY_TYPE_IDENTITY_VERIFIED set to true. The generic VERIFIED filter
refers to ownership. A subject filter alone does not establish verification; it
matches reconciled identity rows, including failures.
flowchart LR
Q[Identity subject and identity-verified filters] --> F[Database predicates]
DB[Reconciled result per CID and role] --> F
F --> S[Matching subject and verified status]
S --> E[Deadline absent or after current time]
E --> C[Return qualifying CIDs or records]
Search reads persisted results and checks deadlines. It does not contact the Identity Node or scan OCI claims per request. Each record version has its own CID and result; verifying one version does not verify all versions of an Agent ID.