example-router-obo-flow

Example Apollo Router implementation demonstrating zero-trust authentication with On-Behalf-Of (OBO) token exchange for GraphQL federation.

Disclaimer

The code in this repository is experimental and has been provided for reference purposes only. Community feedback is welcome but this project may not be supported in the same way that repositories in the official Apollo GraphQL GitHub organization are. If you need help you can file an issue on this repository, contact Apollo to talk to an expert, or create a ticket directly in Apollo Studio.

🔐 Zero-Trust Authentication & Authorization

This playground now includes a complete implementation of zero-trust authentication with On-Behalf-Of (OBO) token exchange. This showcases industry-standard approaches for handling authentication and authorization across multiple subgraphs without multiple authentication cycles.

Key Features

• JWT Authentication: Client tokens validated at the router level
• OBO Token Exchange: Single token exchange in the supergraph phase
• Zero-Trust Architecture: Each subgraph receives a properly scoped token
• No Multiple Auth Cycles: Solves the challenge of queries hitting 4+ subgraphs with different audiences

Architecture

Quick Start for Auth Demo

1. Start the OBO Token Service (runs on port 3090):

   cd obo-service
   npm install
   npm start

2. Start the Coprocessor (runs on port 3080):

   cd coprocessor
   npm install
   npm start

3. Start Subgraphs (run on port 4001):

   cd subgraphs
   npm install
   npm start

4. Start the Router (runs on port 4000):

   cd router
   ./download-router.sh
   ./compose.sh
   ./start-router.sh

5. Test the Authentication Flow:

   ./test-auth-flow.sh

Watch the coprocessor logs to see the OBO token exchange happening once in the supergraph phase, then being distributed to all subgraphs!

How It Works

Client → Router (JWT validation) → Coprocessor (OBO exchange) → All Subgraphs (same token)
         ✓ Validates client token    ✓ Exchanges ONCE           ✓ No multiple auth cycles

Documentation

• Complete Architecture Guide - Detailed explanation of the zero-trust pattern, token flow, and production considerations
• Usage Examples - Practical examples, cURL commands, and client integrations
• OBO Service Details - Token service implementation and endpoints
• Coprocessor Details - Request flow and coprocessor stages

Convenience Scripts

• ./start-all-services.sh - Start all services (OBO service, coprocessor, subgraphs, router)
• ./stop-all-services.sh - Stop all running services
• ./test-auth-flow.sh - Test the complete authentication flow

---

Starting Subgraphs

• Navigate to subgraph folder cd subgraphs/
• Install libraries npm i
• Run all subgraphs npm start

Mocking Subgraphs

You can mock each subgraph by going to the subgraph.js file and setting the SUBGRAPH_CONFIG section mock: true for each one

Starting Router

• Navigate to router folder cd router/
• Setup .env file (see below)
• Download Router binary ./download-latest.sh
• Compose supergraph (if schema has changed) ./compose.sh
• Start Router with config ./start-router.sh

Testing Enterprise

First copy .env.sample to your own .env file. To test enterprise features, you'll need an Apollo account with an enterprise license. Create a graph in Apollo Studio and generate an API key for it. The graph should be configured with the subgraph schemas from this repository.

You can now configure and run enterprise features in router.yml.