Secure AI Agent-to-Tool Calls with AgentCore Gateway: OAuth2 + PKCE for Per-User Auth

Secure AI agent-to-tool calls: OAuth 2.0 Authorization Code + PKCE with AgentCore Gateway

TL;DR — Tie every AI agent action to a real user by enforcing inbound authentication at the AgentCore Gateway. Use OAuth 2.0 Authorization Code flow with PKCE (for public/native clients), an OIDC identity provider, and AgentCore Gateway JWT validation to ensure agentic clients (example: Kiro IDE) present valid identity tokens before the Gateway proxies requests to MCP (Model Context Protocol) tools. This gives you per-user accountability, auditability, and a practical enterprise path to safer agent automation.

Why this matters for business and risk

AI agents are moving from experiments to operational tools that can change data, deploy infrastructure, or modify customer records. Without per-user authentication you lose accountability: who did what, when, and under whose authority. Enforcing inbound authentication for agent-to-tool traffic prevents unauthorized side effects, supports least-privilege access, and creates an auditable trail for compliance or incident response.

Short business payoff:

  • Auditability: agent actions map back to authenticated employees.
  • Least privilege: token claims let you scope what an agent may do per user.
  • Faster security posture: centralized validation at the Gateway reduces distributed configuration errors.

High-level architecture

Core components and their roles:

  • Identity Provider (IdP) — Cognito, Okta, Entra ID, etc. Issues OIDC tokens and hosts discovery metadata and JWKS (public keys).
  • AgentCore Gateway — Acts as the resource server. It validates inbound JWTs, enforces claim rules, and proxies allowed requests to MCP servers.
  • Agentic client — Example: Kiro IDE. Runs on the developer’s machine and initiates the OAuth flow when challenged.
  • MCP server — Backend tools/services exposed via the Model Context Protocol.
  • mcp-remote (optional) — Experimental local proxy to bridge clients to the Gateway when client behavior differs from what the Gateway expects.

Authors of the AWS reference walkthrough (Swagat Kulkarni, Anagh Agrawal, Navneet Sabbineni, Daniel Suarez Souto) demonstrate a practical implementation that follows standards (OIDC discovery + JWKS) and common best practices (PKCE for public clients).

End-to-end authentication flow (step-by-step)

  1. Client calls an MCP endpoint hosted behind the AgentCore Gateway.
  2. Gateway challenges unauthenticated calls. If the request lacks a valid Bearer token, the Gateway returns HTTP 401 and a WWW-Authenticate header pointing to its Protected Resource Metadata endpoint (the discovery entry point).
  3. Client discovers IdP endpoints. The client uses the metadata referenced by the Gateway to locate the IdP’s authorization and token endpoints and public keys.
  4. Interactive OIDC auth code + PKCE flow. The client launches the user’s browser for the Authorization Code flow with PKCE. The user authenticates and grants consent where required.
  5. Client exchanges code for tokens. At the IdP token endpoint the client exchanges the authorization code for an access token, ID token, and optionally a refresh token.
  6. Client calls Gateway with Bearer token. The Gateway validates the JWT (signature via JWKS, exp, iss, audience/custom claim checks) and, if valid, proxies the request to the MCP server.

The Gateway functions as the resource server: it requires a valid identity token before clients may access tools exposed via MCP.

What the Gateway checks on arrival

  • Signature validity against the IdP’s JWKS (public keys discovered via OIDC discovery).
  • Expiration (exp) and issued-at (iat) claims.
  • Issuer (iss) matches the configured IdP.
  • Audience (aud) or client-related claims (examples: azp, cid), or custom claim assertions mapped to your policy.
  • Optional extra assertions—require that a claim equals a configured value to bind tokens to a known client.

IdP and token configuration recommendations

  • Register the agentic client as an OIDC web/native app and enable Authorization Code and Refresh Token grants.
  • Use PKCE for public clients so there’s no embedded client secret on the desktop.
  • Recommended starter lifetimes (adjust to your risk appetite): access token = 1 hour, ID token = 1 hour, refresh token = 90 days. Shorten refresh tokens in high-risk environments.
  • Use the IdP revocation endpoint and test revocation workflows for emergency deauthorization.

Implementation checklist (engineers)

  1. Register your client in the IdP. Add redirect URI such as http://localhost:<PORT>/callback for desktop apps.
  2. Configure AgentCore Gateway to use the IdP’s OIDC discovery URL for JWT discovery and JWKS.
  3. Define claim validation rules (audience, issuer, or custom claims like azp or cid).
  4. Optionally run mcp-remote locally to bridge client behaviors—note it’s experimental and a pragmatic stopgap.
  5. Configure Kiro IDE (or your agentic client) to point to the Gateway MCP endpoint; let it trigger the interactive flow on 401s.
  6. Test end-to-end: confirm 401 + WWW-Authenticate when unauthenticated; complete the auth flow and verify successful, authorized calls.

Non-interactive agents and alternatives

Authorization Code with PKCE is the right pattern for interactive, human-in-the-loop clients. For headless automation or CI you’ll want other patterns:

  • Client Credentials — Suitable for machine-to-machine but loses per-user accountability. Use short lifetimes and strict claim checks if used.
  • Token Exchange (RFC 8693) — Exchange a user token for a scoped service token to preserve delegated authority while isolating service-level permissions.
  • OAuth Device Flow — An alternative for devices without a browser or for constrained UX, though it still requires user interaction via a second device.
  • mTLS or DPoP — Add stronger binding between token and client if higher assurance is required.

Operationalization: monitoring, caching, rotation

  • Cache JWKS and discovery metadata with a sensible TTL. Honor key-rotation events by refreshing cache on signature verification failures.
  • Monitor metrics: auth failures/minute, JWKS fetch latency, refresh token usage, number of revocations, and anomalous agent-originated writes per user.
  • Log validation failures with contextual fields (iss, aud, exp mismatch) to accelerate incident response.
  • Plan key rotation and test automated JWKS refresh behaviors to avoid outages during cryptographic rollover.
  • Encrypt refresh tokens in client storage and consider one-time-use refresh tokens or rotation for higher security.

Smoke tests and runbook (quick checks)

Basic checks you should run during setup:

  1. Call the Gateway MCP endpoint without a token. Expect HTTP/1.1 401 and a WWW-Authenticate header pointing to the Gateway’s Protected Resource Metadata.
  2. Trigger the authorization code + PKCE flow via your agentic client. Exchange the code for an access token and re-call the endpoint with Authorization: Bearer <token>. The call should succeed if token validation passes.
  3. Revoke the refresh token at the IdP and confirm the client can no longer refresh the session.

Example of a discovery-style WWW-Authenticate header (illustrative):

WWW-Authenticate: Bearer realm="agentcore", authorization_uri="https://gateway.example/.well-known/oauth-protected-resource"

Cleanup steps

  • Revoke active tokens via the IdP revocation endpoint.
  • Clear any local mcp-remote auth caches and remove client configuration from Kiro IDE.
  • Uninstall mcp-remote if used and delete or update the Gateway and IdP client registrations.

Pilot plan: get to a working demo in two weeks

  1. Week 0–1 (setup): Register a test OIDC app (Cognito/Okta), configure AgentCore Gateway to point at the IdP discovery URL, and add a simple MCP tool behind the Gateway.
  2. Week 1 (client integration): Configure Kiro IDE to hit the Gateway MCP endpoint and validate the interactive auth code + PKCE flow. Use mcp-remote locally if needed for a shim.
  3. Week 2 (ops and testing): Implement JWKS caching policies, add logging for validation failures, and run the smoke tests and revocation workflow.

Common gotchas and quick troubleshooting

  • Clock skew — ensure NTP-synced hosts; exp/iat failures are often clock-related.
  • Wrong audience or claim name — IdPs differ (use aud, azp, or custom claim assertions as needed).
  • Missing redirect URI — native apps must match the registered redirect exactly.
  • Stale JWKS cache — a new key rotation can cause sudden signature verification failures unless your cache refresh is aggressive enough.

Key questions and short answers

  • How do you enforce per-user authentication for agentic clients calling MCP tools?

    Use OAuth 2.0 Authorization Code flow with PKCE for interactive clients and configure the AgentCore Gateway to validate inbound JWTs before proxying requests to MCP servers.

  • Where does a client discover OAuth endpoints when challenged?

    The Gateway returns a Protected Resource Metadata reference via the WWW-Authenticate header. Clients follow that to the IdP’s OIDC discovery URL to find authorization and token endpoints.

  • What token checks does the Gateway perform?

    Signature vs JWKS, expiration, issuer, audience or configured claim assertions, and optional custom claim rules to tie tokens to known clients.

  • What about non-interactive agents or CI?

    Use client credentials, token exchange, or device flow depending on the use case. Prefer delegated tokens or token exchange when per-user accountability is required.

  • Is mcp-remote ready for production?

    mcp-remote is pragmatic and experimental; treat it as a bridge while client behaviors and the MCP ecosystem mature. Replace it with standardized client implementations for production.

PKCE is non-negotiable for desktop agent clients—don’t skip it. The Gateway treats any valid OAuth token as valid by default, so use claim assertions to distinguish machine tokens from user tokens where policy requires it.

Secure agent automation is a combination of standards, configuration, and operational discipline. Point the AgentCore Gateway at your IdP’s discovery URL, enforce Authorization Code + PKCE for interactive agents, add concrete claim checks, and operationalize logging and revocation. That gives your AI agents the accountability and auditability enterprises need while letting teams safely unlock agent-driven productivity.

0