Introduction

This tutorial provides a comprehensive walkthrough of implementing RFC 8693 Token Exchange within AgentGateway. This standard is crucial for enabling secure and efficient delegation of authority in agentic AI systems, allowing agents to act on behalf of users or other services without directly exposing sensitive credentials.

Why Token Exchange Matters for Agentic AI

Modern AI agents often need to interact with various services and resources on behalf of users. This presents a significant security challenge: how can an agent securely prove its identity and authorization to downstream services without compromising user credentials or requiring complex, custom integration for each service?

The Problem

Traditionally, agentic AI systems would face issues like:

  • Hardcoding API keys or secrets, creating significant security risks.
  • Complex OAuth flows for every interaction, leading to poor user experience and development overhead.
  • Lack of a standardized way for agents to prove their identity and the identity of the user they represent.

The Solution: RFC 8693 Token Exchange

RFC 8693, "Token Exchange", defines a standardized protocol for exchanging one security token for another. This allows a client (like an AI agent) to request a new token from an authorization server that is tailored for a specific audience (a downstream service) and scope, while potentially carrying the identity of the original token holder (the user).

AgentGateway's Three Exchange Grants

AgentGateway, a flexible and powerful API gateway, supports RFC 8693 through three primary exchange grants, enabling diverse use cases:

  • JWT Bearer Grant (RFC 7523): Allows the agent to present a signed JWT as a credential to exchange for a new token.
  • Microsoft Entra OBO (On-Behalf-Of) Flow: Facilitates scenarios where the agent needs to access Microsoft Graph or other Entra ID-protected resources.
  • Custom Subject Token Source: Offers flexibility to integrate with custom identity providers or token formats.

These grants allow AgentGateway to act as a central hub for managing and transforming security tokens, simplifying complex authentication scenarios for AI agents.

Prerequisites

Before you begin, ensure you have the following:

  • Docker and Docker Compose installed.
  • Basic understanding of JWTs, OAuth 2.0, and OIDC.
  • A development environment set up for Go (as AgentGateway is Go-based).

Architecture Overview

The architecture involves several key components:

  1. Keycloak: Acts as the Identity Provider (IdP), issuing initial user tokens.
  2. Echo Upstream: A simple backend service that AgentGateway will proxy requests to. It will validate the incoming tokens.
  3. AgentGateway: The core component that intercepts requests, performs token exchange based on RFC 8693, and forwards requests with transformed tokens to the upstream service.
Diagram showing Keycloak, AgentGateway, and Echo Upstream interaction

Step 1: Clone and Build AgentGateway

First, obtain the AgentGateway source code and build it. This typically involves cloning the repository and running a build command.

git clone https://github.com/agentgateway/agentgateway.git

cd agentgateway

go build ./cmd/agentgateway

Step 2: Start Keycloak and the Echo Upstream

We'll use Docker Compose to spin up Keycloak and a sample Echo Upstream service. Keycloak needs to be configured with a realm and a client for AgentGateway to interact with. The Echo Upstream will be a simple HTTP server that validates JWTs.

A sample docker-compose.yml file should be used to orchestrate these services. Ensure Keycloak is accessible and has a user and client configured.

Step 3: Understand the Configuration

AgentGateway's behavior is controlled by a configuration file (e.g., config.yaml). Key parameters include:

  • listen_address: The address AgentGateway listens on.
  • upstream_address: The address of the backend service (Echo Upstream).
  • oidc_provider_url: The OIDC discovery endpoint for Keycloak.
  • client_id and client_secret: For AgentGateway's authentication with Keycloak.
  • token_exchange section: Defines the exchange grants and their configurations. This is where you specify the grants (JWT Bearer, OBO, Custom) and their respective parameters.

Pay close attention to the token_exchange.grants section. For the JWT Bearer grant, you'll define audience and issuer details. For OBO, you'll specify the resource to access.

Step 4: Run AgentGateway

With AgentGateway built and the configuration file ready, start the AgentGateway executable, pointing it to your configuration file.

./agentgateway --config config.yaml

Verify that AgentGateway starts without errors and successfully connects to Keycloak and the Echo Upstream.

Step 5: Test the Token Exchange Flow

This is where we validate the implementation.

5.1 Get a User Token

Using a tool like curl or Postman, authenticate with Keycloak to obtain a user access token. This token represents the user's identity and permissions.

5.2 Call AgentGateway

Make a request to AgentGateway, including the user's access token in the Authorization: Bearer <user_token> header. AgentGateway will intercept this request. Configure AgentGateway to expect a specific audience for the exchanged token.

5.3 Verify the Token Transformation

AgentGateway will use the incoming user token and its configuration to request a new token from Keycloak (or another token issuer) for the Echo Upstream's audience. It then forwards the request to Echo Upstream with this new, transformed token. The Echo Upstream service should validate this new token, confirming it's intended for its audience and issued correctly.

5.4 Test Token Caching

RFC 8693 implementations often include caching for performance. Test this by making multiple requests with the same initial user token. Observe that subsequent requests might use cached exchanged tokens, reducing latency and load on the identity provider.

Step 6: Understand the Security Boundary

The security boundary is defined by the tokens. AgentGateway sits between the client (agent) and the upstream service. It ensures that the upstream service only ever receives tokens it's meant to trust and for which it is the intended audience. The user's original token is never directly passed to the upstream service unless explicitly configured and intended. This is the core principle of delegation.

Step 7: Advanced Configuration

AgentGateway's flexibility extends to more complex scenarios:

JWT Bearer (RFC 7523)

This grant type allows AgentGateway to accept a JWT from the client and exchange it for a new token. The client's JWT must be signed and contain relevant claims that AgentGateway can use to construct the new token.

Microsoft Entra OBO

For applications interacting with Microsoft 365 or Azure services, the OBO flow is critical. AgentGateway can take a token issued by Entra ID and exchange it for a new token scoped to a specific Microsoft API (e.g., Microsoft Graph), enabling agents to access user data within the Microsoft ecosystem.

Custom Subject Token Source

If you use a non-standard identity provider or a proprietary token format, you can configure a custom token source. This allows you to write logic to parse and validate arbitrary tokens and use them as the basis for exchanging new tokens.

Delegation with Actor Token

RFC 8693 also supports the concept of an "actor token," which identifies the agent itself performing the action, separate from the "subject token" which identifies the end-user. AgentGateway can be configured to manage both, providing a robust model for auditing and authorization.

Step 8: Troubleshooting

Common issues include:

  • Incorrect Keycloak configuration (realm, client secrets, redirect URIs).
  • Mismatched audiences between AgentGateway configuration and upstream service expectations.
  • Expired or invalid user tokens.
  • Network connectivity issues between components.

Check AgentGateway's logs for detailed error messages. Debugging token validation on the upstream service is also critical.

Step 9: Cleanup

To clean up the Docker environment, run docker-compose down -v in the directory containing your docker-compose.yml file. This will stop and remove the containers and any associated volumes.

Conclusion

Implementing RFC 8693 Token Exchange with AgentGateway provides a powerful, standardized mechanism for securing agentic AI workflows. By abstracting the complexities of token management and transformation, developers can build more robust, secure, and user-friendly AI applications.