Expose OAuth 2.0-secured APIs as MCP tools for AI agents while preserving user authentication context using Amazon Bedrock AgentCore Gateway Interceptors.
- USER_FEDERATION pattern - JWT propagation through the entire request chain
- Three-layer JWT validation - Runtime, Gateway, and API Gateway
- Gateway Interceptor - Authorization header injection to downstream APIs
- CUSTOM_JWT authorizer - Works with any OIDC provider (Okta, Auth0, Azure AD, Amazon Cognito)
# 1. Clone repository
git clone https://github.com/aws-samples/sample-bedrock-agentcore-gateway-user-federation.git
cd sample-bedrock-agentcore-gateway-user-federation
# 2. Configure environment (see docs/SETUP.md)
cp frontend/.env.example frontend/.env
cp backend/.env.example backend/.env
cp api/.env.example api/.env
# 3. Start services (3 terminals)
# Terminal 1 - Frontend
cd frontend && npm install && npm start
# Terminal 2 - Backend
cd backend && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && python src/app.py
# Terminal 3 - API
cd api && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && python src/api.pyAccess: http://localhost:3000
three-tier-chat-app/
├── docs/ # Project documentation
│ ├── README.md # Architecture overview
│ ├── SETUP.md # Setup guide
│ ├── DEPLOYMENT.md # AWS deployment
│ ├── ARCHITECTURE.md # Detailed architecture & diagrams
│ └── SECURITY.md # Security guidelines
│
├── frontend/ # React application (Port 3000)
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── App.js # Main app
│ │ └── index.js # Entry point
│ ├── package.json
│ └── .env.example
│
├── backend/ # Backend proxy (Port 5002)
│ ├── src/
│ │ └── app.py # Flask application
│ ├── requirements.txt
│ └── .env.example
│
├── api/ # Secured API (Port 5001)
│ ├── src/
│ │ ├── api.py # Flask application
│ │ └── user_database.py # Mock database
│ ├── requirements.txt
│ └── .env.example
│
├── agentcore/ # AgentCore agent
│ ├── agents/
│ │ └── userassistant/ # User assistant agent
│ └── README.md
│
├── base-infra/ # Infrastructure
│ ├── cdk/ # AWS CDK stacks
│ ├── scripts/ # Utility scripts
│ └── README.md
│
└── README.md # This file
flowchart LR
User([User]) --> Frontend[Frontend<br/>React + Okta]
Frontend -->|JWT| Backend[Backend<br/>Flask]
Backend --> API[Secured API<br/>Lambda]
Backend --> Agent[AgentCore<br/>AI Agent]
Agent -.->|Federated JWT| API
Data Flow: User → Frontend → Backend → API / AgentCore → Response
See docs/ARCHITECTURE.md for detailed sequence diagrams, security headers, and tracing.
- Okta SSO with Authorization Code + PKCE flow
- JWT signature verification at each layer
- CORS restricted to specific origins
- Security headers (HSTS, CSP, etc.)
- No secrets in code (.env files gitignored)
- Modern React UI with responsive design
- AI-powered chat with AgentCore
- User profile display
- API flow comparison demo
- Context-aware responses using Claude
- USER_FEDERATION (agent uses user's JWT)
- Access to user-specific data
- Session management
- Mock database (no infrastructure setup required)
- Debug mode enabled
- Detailed error messages for development
| Document | Description |
|---|---|
| docs/SETUP.md | Getting started guide |
| docs/DEPLOYMENT.md | AWS deployment instructions |
| docs/ARCHITECTURE.md | Detailed architecture diagrams |
| docs/SECURITY.md | Security guidelines |
- frontend/README.md - React application
- backend/README.md - Backend proxy service
- api/README.md - Secured API layer
- agentcore/README.md - AgentCore agent
- base-infra/README.md - Infrastructure
| Layer | Technologies |
|---|---|
| Frontend | React 18, Okta React SDK, Axios, React Router |
| Backend | Python 3.11, Flask 3.0, PyJWT 2.8 |
| API | Python 3.11, Flask (Lambda-ready), Mock DB |
| Infrastructure | AWS CDK, Lambda, S3, CloudFront, API Gateway |
| AI | AWS Bedrock AgentCore, Claude |
- Node.js 18+
- Python 3.10+
- Okta account
- AWS account (for AgentCore)
Each service runs independently:
# Frontend (http://localhost:3000)
cd frontend && npm install && npm start
# Backend (http://localhost:5002)
cd backend && pip install -r requirements.txt && python src/app.py
# API (http://localhost:5001)
cd api && pip install -r requirements.txt && python src/api.pycd base-infra/cdk
# Install dependencies
npm install
# Bootstrap CDK (first time only)
cdk bootstrap aws://ACCOUNT_ID/REGION
# Deploy all stacks
cdk deploy --allSee docs/DEPLOYMENT.md for detailed instructions.
This is an educational project demonstrating cloud-native architecture patterns.
Implemented:
- No secrets in git (.env files gitignored)
- JWT signatures verified at each layer
- No sensitive data in console logs
- AWS credentials protected
Deferred for Production:
- Rate limiting
- Input validation
- CSRF protection
- Real database
For production deployments, follow security best practices:
See docs/SECURITY.md for detailed security guidelines.
Port Already in Use:
lsof -ti:3000 # Find process
kill -9 <PID> # Kill processOkta Authentication Fails:
- Verify redirect URIs in Okta dashboard
- Check OKTA_ISSUER includes
/oauth2/default - Ensure PKCE is enabled
CORS Errors:
- Verify ALLOWED_ORIGINS in backend/.env
- Check backend is running
- Clear browser cache
- Okta SSO authentication
- Three-tier architecture
- AgentCore integration with USER_FEDERATION
- AWS CDK infrastructure (alpha constructs for AgentCore)
- Distributed tracing with OpenTelemetry/ADOT
- Mock database
- Security review
- Real database (DynamoDB/RDS)
- Rate limiting & input validation
- Comprehensive test suite
- CI/CD pipeline
- Monitoring & alerting
Abhijeet Patil GitHub: @prajwalendra
See CONTRIBUTING for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.