API Gateway Auth Boundaries: Correcting Security Test Assumptions

Our security tests failed with unexpected results: unauthenticated requests returned 200 OK instead of 401 Unauthorized. The issue wasn't a security vulnerability—it was incorrect test assumptions about where authentication happens in serverless architectures.

The Problem

Security tests expected Flask to reject unauthenticated requests:

def test_protected_endpoint_requires_auth():
    """Unauthenticated requests should return 401."""
    response = client.get('/user/profile')
    assert response.status_code == 401  # FAILED: Got 200

These tests passed in local development but exposed a misunderstanding of production architecture. In serverless deployments, API Gateway handles authentication before requests reach Flask.

Architecture: Assumed vs Actual

Before (Incorrect Assumption):

Request Flow (Assumed)
┌──────────────────┐       ┌──────────────────┐
│ Client Request   │──────>│ Flask App        │
│ (No auth header) │       │ - Auth check     │
└──────────────────┘       │ - Return 401     │
                            └──────────────────┘
    Tests expected Flask to reject

After (Correct Architecture):

Request Flow (Actual)
┌──────────────────┐       ┌──────────────────┐       ┌──────────────────┐
│ Client Request   │──────>│ API Gateway      │──────>│ Flask App        │
│ (No auth header) │       │ - Auth check     │       │ - Trusts Gateway │
│                  │       │ - Return 401     │       │ - No auth check  │
└──────────────────┘       └──────────────────┘       └──────────────────┘
    Auth enforced at Gateway, not Flask

Understanding Serverless Authentication

Traditional server architectures implement authentication in the application layer:

# Traditional approach (monolithic)
@app.before_request
def authenticate_request():
    """Check authentication before handling request."""
    token = request.headers.get('Authorization')
    if not token or not validate_token(token):
        abort(401)

Serverless architectures move authentication to the API Gateway layer:

# API Gateway configuration (AWS)
Resources:
  ApiGateway:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: AlphaZed API

  Authorizer:
    Type: AWS::ApiGateway::Authorizer
    Properties:
      Name: CognitoAuthorizer
      Type: COGNITO_USER_POOLS
      IdentitySource: method.request.header.Authorization
      RestApiId: !Ref ApiGateway

  ProtectedRoute:
    Type: AWS::ApiGateway::Method
    Properties:
      HttpMethod: GET
      ResourceId: !Ref UserProfileResource
      RestApiId: !Ref ApiGateway
      AuthorizationType: COGNITO_USER_POOLS
      AuthorizerId: !Ref Authorizer

API Gateway validates JWT tokens against AWS Cognito before invoking Lambda. Invalid tokens never reach the application.

Why This Architecture Makes Sense

1. Performance

Authentication at the gateway prevents unnecessary Lambda invocations:

Unauthenticated Request (Gateway Auth)
┌──────────────────────────────────────┐
│ API Gateway validates token: 5ms     │
│ Token invalid → Return 401           │
│ Total: 5ms                           │
│ Lambda invocations: 0                │
│ Cost: $0.000                         │
└──────────────────────────────────────┘

Unauthenticated Request (App Auth)
┌──────────────────────────────────────┐
│ API Gateway forwards request: 5ms    │
│ Lambda cold start: 2000ms            │
│ Flask validates token: 50ms          │
│ Token invalid → Return 401           │
│ Total: 2055ms                        │
│ Lambda invocations: 1                │
│ Cost: $0.002                         │
└──────────────────────────────────────┘

Gateway authentication is 400× faster and eliminates Lambda costs for invalid requests.

2. Security Isolation

Application code never handles authentication credentials:

# Flask receives pre-validated user info
@app.route('/user/profile')
def get_profile():
    # API Gateway injects validated claims
    user_id = request.environ['apigateway.event']['requestContext']['authorizer']['claims']['sub']

    # No token validation needed
    return User.query.get(user_id).to_dict()

This reduces attack surface—application vulnerabilities can't compromise authentication.

3. Centralized Policy

Authentication rules live in infrastructure code, not application code:

# Single source of truth for all routes
AuthorizationScopes:
  - user:read
  - user:write
  - admin:all

Changing authentication policy doesn't require application redeployment.

Correcting Security Tests

Original (Failing) Tests

class TestSecurityBoundaries:
    """Test authentication enforcement."""

    def test_profile_requires_auth(self, client):
        """GET /user/profile should reject unauthenticated requests."""
        response = client.get('/user/profile')
        assert response.status_code == 401  # FAILS: Got 200

    def test_profile_with_auth(self, client, auth_token):
        """GET /user/profile should succeed with valid token."""
        response = client.get('/user/profile', headers={
            'Authorization': f'Bearer {auth_token}'
        })
        assert response.status_code == 200  # Passes

These tests failed because Flask test client bypasses API Gateway authentication layer.

Corrected Tests

We rewrote tests to reflect architectural boundaries:

class TestSecurityBoundaries:
    """Test security boundaries match architecture."""

    def test_gateway_enforces_auth(self):
        """API Gateway rejects unauthenticated requests (integration test)."""
        # Make real HTTP request to deployed API
        response = requests.get('https://api.thurayya.app/user/profile')
        assert response.status_code == 401
        assert 'Unauthorized' in response.json()['message']

    def test_flask_trusts_gateway(self, client):
        """Flask trusts API Gateway authentication (unit test)."""
        # Simulate API Gateway injecting user claims
        with client.application.test_request_context(
            '/user/profile',
            environ_base={'apigateway.event': {
                'requestContext': {
                    'authorizer': {
                        'claims': {'sub': 'user-123'}
                    }
                }
            }}
        ):
            response = client.get('/user/profile')
            assert response.status_code == 200

Test Organization

We reorganized tests by architectural layer:

tests/
├── unit/                    # Flask logic (no auth checks)
│   ├── test_user_service.py
│   └── test_profile_logic.py
├── integration/             # API Gateway + Flask
│   ├── test_auth_flow.py
│   └── test_protected_endpoints.py
└── security/                # Infrastructure-level security
    ├── test_gateway_auth.py
    └── test_cognito_config.py

Implementation Changes

1. Update Test Fixtures

We created fixtures that simulate API Gateway behavior:

@pytest.fixture
def authenticated_context(app):
    """Simulate API Gateway authentication."""
    def _context(user_id='test-user-123'):
        return app.test_request_context(
            environ_base={
                'apigateway.event': {
                    'requestContext': {
                        'authorizer': {
                            'claims': {
                                'sub': user_id,
                                'email': f'{user_id}@test.com',
                                'cognito:groups': ['users']
                            }
                        }
                    }
                }
            }
        )
    return _context

2. Add Integration Tests

We added integration tests against deployed environments:

class TestDeployedAuthSecurity:
    """Test authentication in deployed environments."""

    @pytest.mark.integration
    def test_prod_rejects_missing_auth(self):
        """Production API Gateway rejects missing auth."""
        response = requests.get(f"{PROD_API_URL}/user/profile")
        assert response.status_code == 401

    @pytest.mark.integration
    def test_prod_rejects_invalid_token(self):
        """Production API Gateway rejects invalid tokens."""
        response = requests.get(
            f"{PROD_API_URL}/user/profile",
            headers={'Authorization': 'Bearer invalid-token'}
        )
        assert response.status_code == 401

    @pytest.mark.integration
    def test_prod_accepts_valid_token(self, valid_cognito_token):
        """Production API Gateway accepts valid tokens."""
        response = requests.get(
            f"{PROD_API_URL}/user/profile",
            headers={'Authorization': f'Bearer {valid_cognito_token}'}
        )
        assert response.status_code == 200

3. Document Architecture

We added architecture documentation to CLAUDE.md:

## Authentication Architecture

**Authentication Boundary: API Gateway**

API Gateway handles all authentication via AWS Cognito:
- JWT token validation
- Token expiration checks
- Cognito user pool verification
- Authorization scope validation

**Flask Application: Trusts Gateway**

Flask assumes all requests are pre-authenticated:
- Reads user claims from API Gateway event context
- No token validation in application code
- No authorization checks (handled by Gateway)

**Testing Implications**

Unit tests: Mock API Gateway context injection
Integration tests: Test against deployed Gateway
Security tests: Verify Gateway configuration

Results

Before correction:

• 37 failing security tests
• Incorrect assumptions about auth boundaries
• Developers confused by test failures
• Time wasted investigating "security issues"

After correction:

• 0 failing security tests
• Clear understanding of serverless auth architecture
• Tests validate correct architectural layers
• Security tests focus on infrastructure configuration

Test coverage:

• Unit tests: Flask business logic (no auth checks)
• Integration tests: Gateway + Flask interaction
• Security tests: Gateway configuration validation

Developer experience:

• Security test failures now indicate real misconfigurations
• Tests document authentication architecture
• New developers understand auth boundaries from tests

Key Insights

1. Architecture Determines Test Strategy

Serverless architectures require different testing approaches than monolithic architectures. Don't assume application-layer authentication in serverless environments.

2. Test What You Deploy

Local Flask test client doesn't include API Gateway. Integration tests against deployed environments catch real security issues.

3. Security Tests Should Match Security Architecture

If authentication happens at the gateway, test gateway configuration—not application behavior.

4. Documentation Prevents Confusion

Explicit architecture documentation (CLAUDE.md, AGENTS.md) helps future developers write correct tests.

Common Serverless Auth Patterns

Pattern 1: Gateway Authentication (Our Approach)

• Auth Layer: API Gateway
• Pros: Fast, centralized, no Lambda cost for invalid requests
• Cons: Requires infrastructure-level testing

Pattern 2: Authorizer Lambda

• Auth Layer: Separate Lambda function invoked by Gateway
• Pros: Custom authentication logic
• Cons: Additional Lambda costs, slower

Pattern 3: Application Authentication

• Auth Layer: Flask application
• Pros: Familiar pattern, easy to test locally
• Cons: Slower, higher costs, larger attack surface

We chose Pattern 1 for performance and cost optimization.

Key Takeaways

1. Authentication boundaries differ in serverless - Gateway handles auth, not application
2. Test infrastructure separately - Security tests should validate Gateway configuration
3. Mock Gateway context in unit tests - Simulate pre-authenticated requests
4. Use integration tests for auth flows - Test against deployed environments
5. Document architecture explicitly - Prevent future confusion about auth boundaries

Resources

• AWS API Gateway Authorization
• JWT Token Validation
• Commit: 9994077 - Security test corrections
• Documentation: CLAUDE.md - Authentication Architecture section

Implementation date: January 2026 Commits: 9994077 Impact: Corrected security test assumptions, validated serverless auth architecture