docs: ADR-0007 — External JWKS federation for cross-org identity

[Pico (piiiico)]

Summary

Proposal ADR for cross-org agent identity federation via external JWKS, as invited by Imran Siddique (@imran-siddique) in #1234.

What this ADR covers:

• Discovery: DNS-anchored /.well-known/jwks.json following the OpenID Federation / SPIFFE trust domain pattern — one dereference hop, no coordination overhead
• Trust anchoring: DNS/WebPKI as default, with three-tier federation policy (explicit allowlist → domain-scoped TOFU → open federation). Default is explicit allowlist, matching AGT's default-deny posture
• Revocation propagation: Short-lived tokens (matching AGT's 15-min credential lifecycle) + cached JWKS with 5-min TTL + co-located revocation list endpoint for urgent key compromise
• Integration: Provider-based IdentityProviderChain alongside existing SPIFFE and Entra modules, HandshakeResult.external_identity extension, ADR-0003 (200ms SLA) and ADR-0005 (liveness) composition

Key design choice: The abstraction sits at the provider boundary, not the wire format. This allows operators to plug in any identity backend (hosted federation, DIF MCP-I, custom trust anchors) without modifying the handshake protocol.

Relationship to Entra Agent ID bridge: Complementary, not competing. Entra handles cross-tenant within the Microsoft ecosystem; external JWKS handles agents outside it. The ADR includes a routing table for when to use which.

Working example: AgentLair JWKS endpoint — production Ed25519 keys, same algorithm as ADR-0001. Two independent projects have adopted this verification pattern.

Incorporates technical input from Kevin Knapp (@Knapp-Kevin)'s analysis on discovery constraints, trust anchoring topology, and revocation cadence.

Closes #1234

Prior art

• OpenID Federation 1.0 — entity statement chains, /.well-known/ discovery
• SPIFFE — trust domain federation model
• did:web specification — DNS-anchored DIDs
• springdrift PR #38 — JWKS gate handler integration
• task-orchestrator — independent JWKS ActorVerifier adoption

Disclosure: I maintain AgentLair, referenced as a working example in the ADR.

🤖 Generated with Claude Code

[github-actions]

🤖 AI Agent: contributor-guide — 🌟 What You Did Well

Hello @first-time-contributor! 👋

Welcome to the microsoft/agent-governance-toolkit community! 🎉 Thank you for taking the time to contribute to this project — we’re thrilled to have you here. Your detailed and well-structured pull request is a fantastic first contribution, and we appreciate the effort you’ve put into it. Let’s dive into the review!

---

🌟 What You Did Well

1. Thorough Documentation: Your ADR is incredibly comprehensive, well-researched, and thoughtfully structured. The inclusion of prior art, working examples, and clear diagrams makes it easy to understand the proposal and its context.
2. Alignment with Existing Standards: You've done an excellent job aligning the proposal with existing standards like OpenID Federation, SPIFFE, and did:web. This ensures interoperability and builds on proven patterns.
3. Security-First Approach: The explicit allowlist as the default federation policy aligns perfectly with AGT's default-deny posture. Your focus on short-lived tokens and revocation propagation demonstrates a strong commitment to security.
4. Forward Compatibility: The provider-based architecture is a smart design choice, allowing for future extensibility without disrupting existing functionality.

---

🛠 Suggestions for Improvement

1. Conventional Commit Message:

   • Your commit message docs: ADR-0007 — External JWKS federation for cross-org identity is close to the conventional commits style, but it could be simplified to align more closely with the format. For example:

     docs(adr): add ADR-0007 for external JWKS federation
     

     This ensures consistency with the project's commit conventions.

2. Linting Check:

   • We use ruff for linting (configured to check E, F, and W codes). While this is a documentation PR, it’s good practice to run ruff check . to ensure any Python snippets in the ADR (like the FederationPolicy example) conform to the style guide.

3. Test Coverage:

   • While this is an ADR and not an implementation, when the ExternalJWKSProvider is implemented, tests should be added under packages/{name}/tests/. For example:
     • Unit tests for the IdentityProviderChain and ExternalJWKSProvider.
     • Mocked tests for JWKS discovery and revocation propagation.
     • Integration tests to ensure the handshake path works with federated identities.

4. Security Considerations:

   • Since this proposal involves security-sensitive code (e.g., identity verification, trust anchoring, revocation), it will require extra scrutiny during implementation. Be prepared to address questions about edge cases, such as:
     • How to handle malformed or malicious JWKS responses.
     • Mitigating risks from DNS spoofing or TLS certificate compromise.
     • Ensuring the revocation list mechanism is robust and performant.

5. Clarify Revocation List Endpoint:

   • The /.well-known/jwks-revoked.json endpoint is a great idea, but it would be helpful to clarify its expected structure and how it integrates with the revocation flow. For example:
     • Should it include a timestamp for each revoked key?
     • How should verifiers handle cases where the revocation list is unavailable?

---

📚 Helpful Resources

Here are some resources to help you align your contribution with the project’s conventions:

• CONTRIBUTING.md: Contains guidelines for contributing to this repository.
• QUICKSTART.md: A great resource for understanding the project setup and workflow.
• Conventional Commits Specification: For crafting commit messages.

---

✅ Next Steps

1. Update your commit message to align with the conventional commits format.
2. Run ruff check . to ensure any Python code snippets in the ADR are linted.
3. Address the feedback above (e.g., clarifying the revocation list endpoint).
4. Once you’ve made the updates, push your changes to this branch. The CI/CD pipeline will automatically re-run, and we’ll review the updates.

If you have any questions or need help with any of the feedback, don’t hesitate to ask! We’re here to support you. 😊

Thank you again for your thoughtful contribution — we’re excited to see this feature evolve! 🚀

[Kevin Knapp (Knapp-Kevin)]

LGTM. Reads clean and self-contained.

Posted #1386 as a separate follow-up for cross-org policy-layer
questions. They sit a layer above identity federation and would
muddy this ADR if folded in, so keeping them out of the thread to
preserve the scope as drafted.

[Pico (piiiico)]

@microsoft-github-policy-service agree

[Pico (piiiico)]

Thanks Kevin Knapp (@Knapp-Kevin) — appreciate the clean review and the scoping judgment to split the policy-layer questions into #1386. Agreed that folding them in here would've bloated the ADR past its natural boundary.

CLA signed. This should be mergeable once CI is green and a maintainer approves. Happy to rebase or address anything else that comes up.