peopleserver

PeopleServer Lambda

AWS Lambda deployment for the AIStandardsIO PeopleServer - an AAuth Person Server for agent authorization.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          AWS Cloud                                  │
│                                                                     │
│  ┌──────────────────┐     ┌─────────────────────────────────────┐  │
│  │  API Gateway     │     │       Lambda Function               │  │
│  │  (HTTP API)      │────>│       PeopleServer                  │  │
│  │                  │     │                                     │  │
│  │  /aauth/*        │     │  • AAuth authorization              │  │
│  │  /oauth/*        │     │  • Consent flow                     │  │
│  │  /.well-known/*  │     │  • Token issuance                   │  │
│  └──────────────────┘     └──────────────┬──────────────────────┘  │
│                                          │                          │
│  ┌───────────────────────────────────────┴──────────────────────┐  │
│  │                      DynamoDB Tables                          │  │
│  │  users | agents | missions | tokens | policies               │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ┌─────────────────┐  ┌─────────────────┐                         │
│  │  Route 53       │  │  ACM            │                         │
│  │  (optional)     │  │  Certificate    │                         │
│  └─────────────────┘  └─────────────────┘                         │
└─────────────────────────────────────────────────────────────────────┘

Prerequisites

• AWS CLI configured with appropriate credentials
• AWS SAM CLI installed (brew install aws-sam-cli or pip install aws-sam-cli)
• Go 1.21+
• Make

Quick Start

1. Build

cd lambda/peopleserver
make build

2. Deploy to AWS

# Deploy to dev environment
make deploy

# Deploy to production
ENVIRONMENT=prod make deploy

3. Get Endpoint URL

make outputs

Deployment Options

Standard Deployment

# Default deployment (dev environment, us-east-1)
make deploy

# Custom environment and region
ENVIRONMENT=prod REGION=eu-west-1 make deploy

Custom Domain Deployment

# First, create an ACM certificate for your domain
# Then deploy with custom domain
ENVIRONMENT=prod \
DOMAIN_NAME=auth.example.com \
CERTIFICATE_ARN=arn:aws:acm:us-east-1:123456789012:certificate/xxx \
make deploy-domain

After deployment, create a Route 53 alias record pointing to the API Gateway domain.

Local Development

Run Locally with SAM

# Start local API Gateway
make local

# In another terminal, test the API
curl http://localhost:8888/health
curl http://localhost:8888/.well-known/jwks.json

Test with Sample Event

make invoke

Configuration

Environment Variables

SAM Parameters

API Endpoints

Once deployed, the following endpoints are available:

Usage with OmniAgent

After deploying, configure OmniAgent to use the Lambda endpoint:

# Get the API endpoint
API_URL=$(aws cloudformation describe-stacks \
  --stack-name peopleserver-dev \
  --query 'Stacks[0].Outputs[?OutputKey==`ApiEndpoint`].OutputValue' \
  --output text)

# Configure OmniAgent
export AUTH_AAUTH_ENABLED=true
export AUTH_AAUTH_ISSUER=$API_URL
export AUTH_AAUTH_AUDIENCE=http://localhost:8080

# Start OmniAgent
omniagent openai serve

Monitoring

View Logs

make logs

CloudWatch Metrics

The Lambda function emits standard CloudWatch metrics:

• Invocations
• Duration
• Errors
• Throttles

Cost Estimation

With pay-per-request DynamoDB and Lambda:

For a typical auth workload (10K requests/day):

• ~$10-15/month estimated

Security Considerations

1. Signing Keys: Use AWS KMS for production signing keys
2. DynamoDB: Enable encryption at rest (default)
3. API Gateway: Consider adding WAF rules
4. IAM: Use least-privilege policies

Cleanup

make delete

This removes:

• Lambda function
• API Gateway
• DynamoDB tables
• All associated resources

Troubleshooting

Lambda Cold Starts

The function is configured with 256MB memory. Increase if cold starts are slow:

# In template.yaml
MemorySize: 512  # or 1024

CORS Issues

CORS is configured to allow all origins by default. For production, restrict to specific origins in template.yaml.

Token Validation Fails

Check that:

1. PEOPLESERVER_ISSUER matches the URL clients use
2. JWKS endpoint is accessible
3. Token hasn't expired

Next Steps

• Implement DynamoDB store for persistent state
• Add KMS signing key support
• Add CloudWatch alarms
• Add X-Ray tracing
• Create Terraform alternative to SAM