Setup Guide

Get the three-tier chat application running locally in minutes.

Prerequisites

  • Node.js 18+ (for frontend)
  • Python 3.10+ (for backend and API)
  • Okta Account (for SSO authentication)
  • AWS Account (for AgentCore, optional for local dev)
  • Git (for cloning the repository)

Quick Start

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 Variables

Each service needs its own .env file. Copy the examples:

# Frontend
cp frontend/.env.example frontend/.env

# Backend
cp backend/.env.example backend/.env

# API
cp api/.env.example api/.env

3. Configure Okta

Create Application

  1. Go to Okta Admin Console → Applications → Create App Integration
  2. Choose “OIDC - OpenID Connect” → “Single Page Application”
  3. Configure:
    • Sign-in redirect URIs: http://localhost:3000/login/callback
    • Sign-out redirect URIs: http://localhost:3000
    • Grant types: Authorization Code, Refresh Token

Security Settings

  1. Go to Applications → Your App → General
  2. Under “General Settings”:
    • Proof Key for Code Exchange (PKCE): Required
    • Initiate login URI: http://localhost:3000
  3. Under “Login”:
    • Login initiated by: App Only

API Settings (Authorization Server)

  1. Go to Security → API → Authorization Servers
  2. Select “default” (or create custom)
  3. Note the Issuer URI: https://your-domain.okta.com/oauth2/default
  4. Under “Access Policies”:
    • Ensure a policy allows your app

Claims Configuration

  1. Go to Security → API → Authorization Servers → default → Claims
  2. Add claim for ID Token:
    • Name: email
    • Include in: ID Token (Always)
    • Value type: Expression
    • Value: user.email
  3. Verify scopes include: openid, profile, email

Configure AWS CLI 

# Install AWS CLI (if not installed)
# https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

# Configure credentials
aws configure

# Enter:
# - AWS Access Key ID
# - AWS Secret Access Key
# - Default region: us-east-1
# - Default output format: json

# Verify configuration
aws sts get-caller-identity

Required IAM Permissions:

  • bedrock-agentcore:InvokeAgent - Invoke AgentCore agent
  • bedrock-agentcore:InvokeAgentRuntime - Access AgentCore runtime

See AWS Bedrock AgentCore IAM Permissions for details.

Update Environment Files 

# frontend/.env
REACT_APP_OKTA_DOMAIN=your-domain.okta.com
REACT_APP_OKTA_CLIENT_ID=your_client_id
REACT_APP_OKTA_ISSUER=https://your-domain.okta.com/oauth2/default
REACT_APP_BACKEND_URL=http://localhost:5002

# backend/.env
OKTA_ISSUER=https://your-domain.okta.com/oauth2/default
OKTA_CLIENT_ID=your_client_id
SECURED_API_URL=http://localhost:5001
AGENTCORE_AGENT_ARN=arn:aws:bedrock-agentcore:us-east-1:ACCOUNT_ID:runtime/AGENT_ID
AGENTCORE_REGION=us-east-1
ALLOWED_ORIGINS=http://localhost:3000

# api/.env
OKTA_ISSUER=https://your-domain.okta.com/oauth2/default
OKTA_CLIENT_ID=your_client_id
ALLOWED_ORIGINS=http://localhost:3000

4. Start Services

Terminal 1 - Frontend:

cd frontend
npm install
npm start

Frontend runs on http://localhost:3000

Terminal 2 - Backend:

cd backend
python3 -m venv .venv
source .venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python src/app.py

Backend runs on http://localhost:5002

Terminal 3 - Secured API:

cd api
python3 -m venv .venv
source .venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python src/api.py

API runs on http://localhost:5001

5. Test the Application

  1. Open http://localhost:3000
  2. Click “Login with Okta”
  3. Enter your Okta credentials
  4. Test the chat interface

Detailed Setup Instructions

Frontend Setup 

cd frontend

# Install dependencies
npm install

# Environment variables
cp .env.example .env
# Edit .env with your Okta configuration

# Start development server
npm start

Available Scripts:

  • npm start - Start development server
  • npm build - Build production bundle
  • npm test - Run tests

Backend Setup 

cd backend

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Environment variables
cp .env.example .env
# Edit .env with your configuration

# Start server
python src/app.py

Key Environment Variables:

# Okta Configuration
OKTA_ISSUER=https://your-domain.okta.com/oauth2/default
OKTA_CLIENT_ID=your_client_id

# AgentCore Configuration
AGENTCORE_AGENT_ARN=arn:aws:bedrock-agentcore:region:account:runtime/agent
AGENTCORE_REGION=us-east-1

# API Configuration
SECURED_API_URL=http://localhost:5001

# CORS Configuration
ALLOWED_ORIGINS=http://localhost:3000

API Setup 

cd api

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Environment variables
cp .env.example .env
# Edit .env with your Okta configuration

# Start server
python src/api.py

Key Environment Variables:

# Okta Configuration
OKTA_ISSUER=https://your-domain.okta.com/oauth2/default
OKTA_CLIENT_ID=your_client_id

# API Configuration
SECURED_API_PORT=5001

# CORS Configuration
ALLOWED_ORIGINS=http://localhost:3000

Testing the Setup

Health Checks

Frontend:

curl http://localhost:3000
# Should return React app HTML

Backend:

curl http://localhost:5002/api/health
# Expected: {"status":"healthy"}

Secured API:

curl http://localhost:5001/api/health
# Expected: {"status":"healthy","service":"secured-api",...}

API Documentation

Visit http://localhost:5001/api/docs for API endpoint documentation.

Common Issues

Port Already in Use

If a port is already in use:

# Find process using port
lsof -ti:3000  # or :5002 or :5001

# Kill process
kill -9 <PID>

Python Module Not Found 

# Make sure virtual environment is activated
source .venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Okta Authentication Fails

  1. Check Okta application configuration
  2. Verify redirect URIs are correct
  3. Ensure PKCE is enabled
  4. Check that issuer URL is correct (including /oauth2/default)

CORS Errors

Ensure ALLOWED_ORIGINS in backend and API .env files includes http://localhost:3000.

Development Workflow

Making Changes

  1. Frontend Changes: React hot-reload will apply changes automatically
  2. Backend Changes: Restart backend server (Flask debug mode enables auto-reload)
  3. API Changes: Restart API server

Debugging

Frontend:

  • Open browser DevTools (F12)
  • Check Console tab for errors
  • Check Network tab for API calls

Backend/API:

  • Check terminal output for logs
  • Add logger.debug() statements for detailed logging

Next Steps