Hi, I'm Jeongwoo, a security platform engineer at LY Corporation developing and operating Athenz.
In my previous post, Why ID-JAG is the future of AI agent security - LY Tech Blog, I discussed why identity assertion JWT authorization grant (ID-JAG) is becoming increasingly important for AI agents, how it extends the traditional single sign-on (SSO) trust model into the API domain, and what the core benefits and considerations are for both AI developers and enterprises.
Today, we are moving from theory to practice. To help bridge the gap between abstract specs and real-world execution, I’ve put together a hands-on tutorial called athenz-community/id-jag-the-hard-way.
This local lab allows you to observe the exact tokens, policies, and trust relationships required when an AI agent accesses a protected API on behalf of a user.
Demo Video:
Repository: athenz-community/id-jag-the-hard-way
TL;DR: What you will learn
- How to replicate the end-to-end ID-JAG flow locally, enabling an AI agent to securely access a protected API on behalf of a signed-in user.
- How an AI agent interacts with a protected model context protocol (MCP) server, how enterprise policy is evaluated by the authorization server, and how the resource server enforces the resulting least-privilege access token.
- Exactly where tokens are issued and precisely where the pipeline breaks when a specific policy is missing.
1. Beyond the diagrams
ID-JAG is an active Internet-Draft from the IETF OAuth working group (draft-ietf-oauth-identity-assertion-authz-grant-03 as of May 2026) that leverages established primitives of the following RFCs to facilitate secure, delegated cross-domain API access:
While architecture diagrams provide a high-level view, they rarely answer the practical engineering questions that surface during implementation:
- What exact token payload is generated when a user signs into an AI agent?
- If we already have an ID token, why can't we just exchange it directly for an access token without involving ID-JAG?
- Can we keep the IdP responsible for authentication while maintaining enterprise authorization policy management and evaluation in a separate policy decision point (PDP)?
- What specific permissions does the AI agent hold when calling an MCP server, and how does it prove it is acting on behalf of the signed-in human user?
- How is system-level trust configured between an Enterprise IdP and the authorization server?
2. The AI agent authorization challenge
In traditional application security models, a human user or a service account presents credentials (passwords, certificates) to gain static access. AI agents do not fit either mold cleanly. They are not service accounts running fixed, predictable routines, nor are they human users who can take immediate accountability for their actions. Instead, they represent a distinct and evolving type of actor.
AI agents continuously invoke internal APIs, SaaS tools, and databases in the background. Prompting a human user for consent at every step in this automated chain significantly disrupts the user experience.
Conversely, granting an agent blanket, permanent consent can create broad blast-radius and accountability problems. If an agent misbehaves or is exploited, it becomes difficult to distinguish user intent from delegated agent behavior. This places a constant cognitive burden on individuals to manually police agent behavior, which wastes valuable human attention and operational effort. It also can lead to the proliferation of Shadow AI within the enterprise, leaving the organization vulnerable to emerging attack vectors like prompt injection attacks, and significantly expanding the corporate attack surface.
"Is this AI agent authorized to access this specific resource, on behalf of this user, under this precise scope of permissions, right now?"
ID-JAG helps this by moving away from fragmented, ad-hoc connections, establishing a centralized trust fabric between the Enterprise IdP and the Resource authorization server governed by fine-grained enterprise policies.
3. Demo architecture components
The lab environment uses five core components:
| Component | Technology | Role |
|---|---|---|
| Requesting Agent | Open WebUI, Ollama, Gemma 4, AI Client Gateway | Local AI agent and gateway executing tools on behalf of the user. |
| IdP | Keycloak (on Docker) | The identity provider managing user authentication and subject assertions. |
| IdP authorization server | Athenz KeycloakTokenExchangePlugin | The plugin responsible for validating identity assertions and issuing the ID-JAG token. |
| Authorization server | Athenz (on Local K8s) | The authorization server acting as the PDP to issue access tokens. |
| Resource server | Sample Document API | The target protected resource server. |
Architecture design note
In the reference ID-JAG model, the IdP authorization server is typically the component that authenticates the user, evaluates whether a client may act on that user’s behalf, and issues the ID-JAG.
This tutorial intentionally separates those responsibilities. Keycloak acts as the upstream IdP responsible for user authentication and the original identity assertion. Athenz, through the KeycloakTokenExchangePlugin, acts as a federated IdP authorization server for the ID-JAG flow: it validates the Keycloak-issued assertion, applies enterprise policy, and issues the ID-JAG assertion.
This is slightly different from the simplest deployment model described in the draft, but it preserves the same security boundary. The Resource authorization server does not blindly accept the upstream Keycloak token as a resource authorization grant. Instead, it trusts the Athenz-issued ID-JAG, which is produced only after issuer, signature, audience, subject, client binding, and enterprise policy checks have been applied.
4. Tracing the execution flow
When running the lab, the following sequence occurs internally:
- The user logs into the system via the Keycloak IdP.
- The user inputs a prompt, initiating a task with the AI agent.
- The AI agent requests an ID_JAG token from the Athenz IdP authorization server.
- Athenz evaluates and validates the enterprise policies to ensure the requested delegation is permitted.
- The AI agent requests an access token from the Athenz authorization server.
- The AI agent sends a request, equipped with the token, to the MCP server.
- The MCP server performs a token exchange with the authorization server.
- The MCP server sends a request with the exchanged token to the final resource server.
Crucially, the AI agent avoids holding a long-lived master key; instead, it operates within the specific boundaries evaluated by the enterprise policy engine.
5. Engineered for failure: Learning through blockers
AI agent authorization architectures are best understood through their failure pathways, not their success paths. As security design becomes clearer when you observe how a system handles unauthorized states, this lab intentionally walks you through deliberate failure points:
- You will call a protected API without a token and observe a
401 Unauthorized. - You will configure an enterprise role but omit the membership, triggering a token exchange failure.
- You will attempt a delegated call without explicitly granting the agent the required permissions, causing the delegation chain to break.
Architectural deep dive: Why not exchange the ID token directly?
For the small local setup in this tutorial, directly exchanging a Keycloak ID Token for an Athenz access token would also be technically possible. Athenz could validate the issuer, signature, audience, and subject of the Keycloak token. It could then evaluate Athenz policy and issue an access token.
However, that model implicitly treats a login token as an authorization grant for resource access. The distinction matters most in failure and audit paths. An ID Token proves that a user has authenticated to a client. An authorization grant is the artifact submitted to an authorization server to request an access token for a resource and scope.
By introducing an authorization grant boundary, we can separate authentication failure, grant validation failure, agent delegation denial, enterprise policy denial, and resource token rejection. In short, it prevents identity data from being conflated with explicit access permissions, ensuring that an authentication event does not automatically guarantee a cross-domain authorization right.
6. Quick start: Running the flow locally
To begin the practical exercise, navigate to the repository link below:
🔗 Repository: athenz-community/id-jag-the-hard-way
Clicking the START THE TUTORIAL NOW button on the main page will direct you to the steps to set up the local environment and verify the ID-JAG flow.
Wrapping up
As AI agents scale across enterprise workflows, validating authentication at the front door is rarely sufficient on its own. Modern architecture requires systemic control and explicit auditing of delegated access.
ID-JAG provides a structured approach for managing this complexity, and it is best understood through direct, hands-on experimentation. Contributions, issues, and feedback on id-jag-the-hard-way are always welcome.
💡 Tech-Verse 2026 preview
We will be presenting on this topic at Tech-Verse 2026, LY Corporation's annual tech conference, with a session titled:
"ID-JAG: The Enterprise-Ready Standard for AI Agent Authorization in the MCP & A2A Era".
We will look beyond basic protocol mechanics to discuss central policy control models, explore adjacent movements in the agent ecosystem—including Google’s Agent2Agent (A2A) work and broader cloud-platform approaches to AI agent security—and analyze how these strategies compare with the ID-JAG draft, whose authors include contributors from Okta and Ping Identity. See you there!
Also by this author