OAuth2 Authentication Molecule

---

Reusability and Security by Design

This OAuth2 Molecule assembles multiple AWS infrastructure components into a complete, production-ready authentication system optimized for secure server-to-server communication. It integrates:

• API Gateway (HTTP or REST) as the protected entry point
• Two Lambda functions:
  • /token endpoint for issuing OAuth2 bearer tokens
  • /v1 endpoint accessible only with valid bearer tokens
• Amazon Cognito for user identity and secure token lifecycle

This pattern provides OAuth2 support out of the box, allowing teams to adopt robust API security without implementing custom authentication logic.

What You Get

• Full OAuth2 token issuance and validation using Cognito and Lambda
• Signed JWT access tokens with claims validation
• Custom domains, mTLS support, WAF rules, and IP-based protections
• Bearer token enforcement through API Gateway authorizers
• AWS-native observability: logging, metrics, and tracing
• Reusable and extensible TypeScript AWS CDK codebase

Developer Experience

Includes a complete README.md for deployment, configuration, and local testing. Optional CI/CD pipelines enable automated, version-controlled releases.

Built with Secure Defaults

Security-critical settings like access logs, throttling, and authorization are enforced by default. Developers can safely extend the system with additional protected routes.

Test the Molecule

To test the OAuth2 molecule, follow these steps:

1. Create a User in Cognito Pool

Run the following script to create a test user:

#!/usr/bin/env bash
set -euo pipefail

USER_POOL_ID="XXXXX"
USERNAME="alice3"
EMAIL="alice3@example.com"
PASSWORD="S3cureP@ssw0rd!"
AWS_PROFILE="default"

echo "Creating user '$USERNAME' in pool '$USER_POOL_ID'..."

# Create the user without sending email/SMS and mark email as verified
aws cognito-idp admin-create-user \
  --user-pool-id "$USER_POOL_ID" \
  --username "$USERNAME" \
  --temporary-password "$PASSWORD" \
  --message-action SUPPRESS \
  --user-attributes \
      Name=email,Value="$EMAIL" \
      Name=email_verified,Value=true \
  --profile "$AWS_PROFILE" \
  >/dev/null

# Set the permanent password so the user can sign in immediately
aws cognito-idp admin-set-user-password \
  --user-pool-id "$USER_POOL_ID" \
  --username "$USERNAME" \
  --password "$PASSWORD" \
  --permanent \
  --profile "$AWS_PROFILE" \
  >/dev/null

echo "User created successfully!"

2. Execute the Test Script

Run the following script to test the OAuth2 endpoints:

#!/usr/bin/env bash
set -euo pipefail

APIGW_TYPE="REST"
REGION="us-east-1"
API_GW_URL="https://XXXXX.execute-api.us-east-1.amazonaws.com/up"
USERNAME="alice3"
EMAIL="alice3@example.com"
PASSWORD="S3cureP@ssw0rd!"

# Get tokens
basicAuthCredentials=$(echo -n "$USERNAME:$PASSWORD" | base64)
accessToken=$(curl --location --request POST "$API_GW_URL/token" \
  --header "Authorization: Basic $basicAuthCredentials" | jq -r '.access_token')
idToken=$(curl --location --request POST "$API_GW_URL/token" \
  --header "Authorization: Basic $basicAuthCredentials" | jq -r '.id_token')

# Test protected endpoint
curl -k --location --request GET "$API_GW_URL/v1/hello" \
  --header "Authorization: Bearer $idToken"

Note: Change the API_GW_URL, REGION and USER_POOL_ID according to the API Gateway endpoint created in your AWS account.