<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-api-gateway-security-architecture
description: >-
  Architect secure API gateways with authentication enforcement, rate limiting,
  request validation, token management, and threat protection to defend API
  endpoints against abuse and exploitation.
domain: cybersecurity
subdomain: security-architecture
tags:
  - api-gateway
  - oauth2
  - rate-limiting
  - api-security
  - jwt
  - openapi
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1190"]
---

# Implementing API Gateway Security Architecture

## Overview

API gateway security architecture centralizes authentication, authorization, rate
limiting, and threat protection at the ingress layer. This skill covers designing
gateway policies, token validation flows, request/response transformation security,
and API abuse prevention.

Mode: `[MODE: ARCHITECT]` — API security design and policy enforcement.

## Prerequisites

- API gateway platform (Kong, AWS API Gateway, Envoy, Apigee)
- Identity provider with OAuth2/OIDC support
- OpenAPI specifications for target APIs
- Python 3.10+

## Key Concepts

### API Gateway Security Layers

| Layer | Function | Controls |
|-------|----------|----------|
| **TLS Termination** | Encrypt transport | TLS 1.3, HSTS, certificate pinning |
| **Authentication** | Verify identity | OAuth2, API keys, mTLS |
| **Authorization** | Enforce access | Scope validation, RBAC, OPA policies |
| **Rate Limiting** | Prevent abuse | Per-client quotas, burst limits |
| **Request Validation** | Block malformed input | Schema validation, size limits |
| **Threat Protection** | Detect attacks | SQL injection, XXE, SSRF patterns |
| **Logging** | Audit trail | Request/response logging, correlation IDs |

### OAuth2 Token Validation Flow

```
Client → Gateway: Bearer token in Authorization header
Gateway → IDP: Token introspection / JWKS validation
Gateway: Validate scopes, audience, expiry
Gateway → Backend: Forwarded with X-User-ID, X-Scopes headers
Backend: Trusts gateway-injected identity headers
```

### Rate Limiting Configuration

```json
{
  "rate_limits": [
    {
      "name": "global-default",
      "requests_per_second": 100,
      "burst": 200,
      "key": "client_ip"
    },
    {
      "name": "authenticated-user",
      "requests_per_second": 1000,
      "burst": 2000,
      "key": "oauth2_client_id"
    },
    {
      "name": "sensitive-endpoint",
      "path": "/api/v1/admin/*",
      "requests_per_minute": 10,
      "burst": 15,
      "key": "oauth2_subject"
    }
  ]
}
```

### Request Validation Policy

```yaml
# OpenAPI-based request validation
validation:
  request:
    headers:
      required: [Authorization, Content-Type, X-Request-ID]
    body:
      max_size_bytes: 1048576  # 1MB
      validate_schema: true
      block_unknown_fields: true
    query:
      max_parameters: 20
      max_value_length: 512
  response:
    strip_headers: [Server, X-Powered-By]
    add_headers:
      X-Content-Type-Options: nosniff
      X-Frame-Options: DENY
      Strict-Transport-Security: max-age=31536000; includeSubDomains
```

### Gateway Security Policy Schema

```json
{
  "policy": {
    "name": "production-api",
    "authentication": {
      "type": "oauth2",
      "jwks_uri": "https://idp.example.com/.well-known/jwks.json",
      "required_scopes": ["api:read"],
      "audience": "https://api.example.com"
    },
    "rate_limit": {
      "requests_per_second": 100,
      "key": "oauth2_client_id"
    },
    "threat_protection": {
      "sql_injection": true,
      "xss": true,
      "xxe": true,
      "max_body_size": 1048576
    }
  }
}
```

## Workflow

### Step 1: Analyze API Surface

```bash
node scripts/agent.js --action analyze --openapi openapi.yaml
```

### Step 2: Generate Gateway Policies

```bash
node scripts/agent.js --action policies --openapi openapi.yaml --output gw-policies.json
```

### Step 3: Validate Security Posture

```bash
node scripts/agent.js --action validate --policies gw-policies.json
```

### Step 4: Generate Rate Limit Configuration

```bash
node scripts/agent.js --action ratelimit --endpoints endpoints.json --output limits.json
```

## Detection

```yaml
title: Api Gateway Security Architecture Detection
id: 02865991-1d96-4c2a-97a9-f7e53f2a58e6
status: experimental
description: Detects suspicious activity related to implementing api gateway security architecture techniques in security architecture context
logsource:
  category: network_connection
  product: firewall
detection:
  selection:
    DestinationPort: 443
    Initiated: "true"
  condition: selection
level: medium
tags:
  - attack.t1190
  - attack.lateral_movement
falsepositives:
  - Network segmentation testing by authorized infrastructure teams
```

## Verification

- [ ] All API endpoints require authentication (no open endpoints unless intentional)
- [ ] Token validation checks signature, expiry, audience, and scopes
- [ ] Rate limiting configured per-client with burst protection
- [ ] Request schema validation enforced against OpenAPI spec
- [ ] Response headers strip server information, add security headers
- [ ] Sensitive endpoints have stricter rate limits and additional authorization
- [ ] API access logged with correlation IDs for incident investigation

## References

- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
- [RFC 6749 — OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
- [NIST SP 800-204 Security Strategies for Microservices](https://csrc.nist.gov/publications/detail/sp/800-204/final)
