ID-JAG The Hard Way: Learning AI Agent Security Through Failure, Hands-On (opens in new tab)
ID-JAG provides a structured way for AI agents to access protected APIs on behalf of users without granting them permanent, broad permissions. The hands-on environment demonstrates how authentication, enterprise authorization policies, delegation, and token exchange work together across Keycloak, Athenz, MCP, and resource servers. Its central conclusion is that AI-agent security requires explicit delegation boundaries and centralized policy enforcement, not just user authentication at the entry point. ## Why AI Agents Need a Different Authorization Model - AI agents continuously call internal APIs, SaaS tools, databases, and other services. - Requesting user consent for every automated action would create an unusable experience. - Granting agents permanent, broad access increases: - Blast radius during failures or compromise - Difficulty assigning responsibility - Exposure to prompt injection and shadow AI risks - The key question becomes whether an agent is authorized to access a specific resource, for a specific user, with a specific scope at a specific time. ## ID-JAG and Its Practical Role - ID-JAG is an emerging OAuth profile discussed by the IETF OAuth Working Group. - It combines: - OAuth 2.0 Token Exchange (RFC 8693) - JWT Profile for OAuth 2.0 Authorization Grants (RFC 7523) - It models delegated, cross-domain API access using explicit authorization grants. - The hands-on explores questions that architecture diagrams often leave unanswered: - What token payloads are issued? - Why should an ID token not be exchanged directly for an access token? - Where are enterprise policies evaluated? - How does an agent prove it is acting for a user? - How is trust established between the identity provider and authorization server? ## Separating Authentication from Enterprise Authorization - Keycloak acts as the upstream identity provider: - Authenticates the user - Issues the original identity assertion - Athenz, through `KeycloakTokenExchangePlugin`, acts as: - The authorization server - The ID-JAG issuer - The policy decision point (PDP) - The central resource authorization authority - Athenz validates the Keycloak assertion’s: - Issuer - Signature - Audience - Subject - Client binding - Enterprise policy requirements - Resource authorization servers trust only the Athenz-issued ID-JAG, rather than accepting Keycloak tokens directly. - Centralizing delegation policies in Athenz reduces duplicated or conflicting rules across identity providers, SaaS vendors, and applications. ## End-to-End Request Flow - The user logs in through Keycloak. - The user gives the AI agent a task through a prompt. - The agent requests an ID-JAG from Athenz. - Athenz evaluates enterprise policies and determines whether the delegation is allowed. - The agent requests an access token from Athenz. - The agent calls the protected MCP server with the issued token. - The MCP server exchanges the token with the authorization server. - The MCP server uses the exchanged token to call the final resource server. - The agent therefore operates within a policy-defined boundary instead of holding a long-lived master credential. ## Learning Through Deliberate Failures The tutorial emphasizes failure paths to show where each security control applies. - Calling a protected API without a token produces `401 Unauthorized`. - Defining an enterprise role without adding membership causes token exchange to fail. - Omitting the agent’s required delegation permission breaks the delegation chain. - These failures reveal whether the problem lies in authentication, grant validation, agent delegation, enterprise policy, or resource-token validation. ## Why ID Tokens Should Not Be Used Directly - An ID token proves that a user authenticated successfully to a client. - An authorization grant is an artifact submitted to request access to a particular resource and scope. - Directly exchanging an ID token can implicitly treat login evidence as permission to access resources. - Using an explicit ID-JAG grant creates clearer boundaries between: - Authentication failure - Grant validation failure - Delegation denial - Enterprise policy rejection - Resource authorization failure - ID-JAG is not technically required for the small local demo, but it makes authorization boundaries and audit paths much clearer. ## Hands-On Environment - The tutorial is available in `athenz-community/id-jag-the-hard-way`. - It guides users through a deliberate “fail, diagnose, and fix” workflow. - Users can later remove an agent’s delegation permission in the Athenz UI and observe exactly where execution is blocked. - This experimentation demonstrates the value of centralized policy control more effectively than a successful request alone. AI-agent ecosystems need more than front-door authentication. A practical deployment should use short-lived, explicitly scoped delegation, centralized enterprise policy evaluation, and observable token-exchange boundaries such as those demonstrated by ID-JAG.