6.2 API Gateway: Authentication, JWT Validation, Rate Limiting & Usage Plans

11.2 API Gateway: Authentication, JWT Validation, Rate Limiting & Usage Plans

Managed Regional API Proxy Architecture

Oracle Cloud Infrastructure (OCI) API Gateway is a fully managed, multi-tenant regional proxy service that enables organizations to publish, secure, route, and monitor APIs at scale. Positioned at the network perimeter or within internal enterprise boundaries, API Gateway acts as the unified front door for microservices, legacy HTTP backends, and serverless applications.

API Gateway is deployed directly into a customer's Virtual Cloud Network (VCN), inheriting standard OCI network isolation and security controls:

• Public API Gateway: Provisioned in a public subnet with an internet-facing public IP address. It exposes public REST endpoints to mobile applications, web clients, and external third-party partners.
• Private API Gateway: Provisioned within a private subnet without public internet routability. It serves as an internal gateway for enterprise service meshes, hub-and-spoke VCN transit routing, or hybrid workloads connected over FastConnect or Site-to-Site VPN.

API Gateway is a managed, highly available service that Oracle scales automatically, so you do not provision load balancers or plan gateway capacity yourself.

---

Deployments, Path Routing & Backend Types

The core operational unit on an API Gateway is an API Deployment. A single API Gateway instance can host multiple API Deployments, each bound to a unique path prefix and managing its own collection of routes, security policies, and traffic rules.

API Gateway (Regional Proxy)
  ├── Deployment A (Prefix: /v1/payments) ──> Routes (/charge, /refund) ──> OCI Functions
  ├── Deployment B (Prefix: /v1/inventory) ──> Routes (/items, /{sku}) ──> HTTP Load Balancer
  └── Deployment C (Prefix: /v1/health)    ──> Routes (/status)        ──> Stock Mock Backend

Routing Mechanics

Deployments map incoming client HTTP request paths and verbs (GET, POST, PUT, DELETE) to specific upstream backends using route definitions:

• Path Mapping: Supports exact path matching (e.g., /orders), path parameters (e.g., /orders/{orderId}), and wildcard prefixes (e.g., /static/*). Path parameters can be extracted and forwarded to backend query strings, headers, or URL paths.
• URL Rewriting & Transformations: The gateway can strip prefixes, rewrite target paths, or append static headers before passing requests to backend servers.

Supported Backend Types

OCI API Gateway natively supports three distinct backend architectures:

1. HTTP / HTTPS Backends: Routes traffic to web applications, OCI Flexible Load Balancers, Container Engine for Kubernetes (OKE) Ingress controllers, Compute instances, or public third-party endpoints. Supports SSL/TLS verification, custom timeouts, and SNI host header overrides.
2. OCI Functions Backends: Dispatches incoming requests directly to serverless OCI Functions. The gateway handles the translation between HTTP request bodies and the Fn container input stream, returning function output directly to the calling client.
3. Stock (Mock) Backends: Returns synthetic static HTTP responses—including custom HTTP status codes (e.g., 200 OK, 503 Service Unavailable), response headers, and static JSON/XML response bodies—directly from the gateway without dispatching calls to any downstream compute resource. Mock backends are invaluable for API contract prototyping, health check endpoints, and graceful degradation during maintenance windows.

---

Authentication & Security Policies

API Gateway serves as the centralized enforcement point for authentication and authorization, decoupling security logic from backend business code. Architects can choose between two primary authentication mechanisms:

1. Native OAuth 2.0 / JWT Validation

For modern enterprise architectures utilizing standard JSON Web Tokens (JWT) issued by identity providers—such as Microsoft Entra ID, Okta, Auth0, or OCI Identity Domains—API Gateway provides native JWT validation without requiring custom code or serverless execution.

When a client submits an HTTP Authorization: Bearer {token} header:

• The gateway retrieves and caches the JSON Web Key Set (JWKS) from the identity provider's public keys endpoint (jwks_uri).
• It validates the cryptographic signature of the token using the corresponding public key.
• It verifies core JWT claims: token expiration (exp), not-before (nbf), issuer (iss), and audience (aud).
• It validates custom scopes and role claims required for specific routes.
• It extracts token claims (such as sub, email, or tenant_id) and injects them as new HTTP headers forwarded to backend services.

Architectural Advantage: Native JWT validation executes entirely within the API Gateway data plane. It incurs zero compute billing for OCI Functions, produces no cold starts, and prevents unauthorized requests from ever reaching backend infrastructure.

2. Custom Authorizer Functions

When authentication requires non-standard validation logic—such as inspecting proprietary API keys in database tables, verifying legacy HMAC signatures, checking LDAP directories, or calling legacy SOAP security services—architects implement a Custom Authorizer Function.

In this model:

• The gateway intercepts the incoming request and invokes an OCI Function designated as the custom authorizer.
• The authorizer function receives the request headers and query parameters, executes custom verification logic, and returns a structured JSON response:

  {
    "active": true,
    "principal": "user_98765",
    "scope": ["orders:read", "orders:write"],
    "expiresAt": "2026-10-11T20:30:00Z",
    "context": {
      "tier": "gold",
      "companyId": "corp_102"
    }
  }
  

• If active is true, the gateway permits the request, injecting values from the context object into backend HTTP headers.
• Authorizer Caching: To prevent invoking the authorizer function on every single incoming request, the gateway caches authorization verdicts based on the expiresAt timestamp or a configured cache TTL. Subsequent requests with identical credentials are authenticated directly from cache.

---

Traffic Management: Rate Limiting, Throttling & CORS

To maintain service reliability and protect backend applications from cascading failures, API Gateway incorporates robust traffic management policies:

Rate Limiting & Throttling

Architects can configure rate limiting at the deployment level or route level:

• Global Rate Limiting: Enforces a maximum aggregate request-per-second (RPS) threshold across the entire deployment.
• Per-Client Throttling: A rate-limiting policy can count requests per client IP address or in total across all clients.
• When a client exceeds the limit, the gateway rejects the request with HTTP 429 Too Many Requests before it reaches the backend.

Cross-Origin Resource Sharing (CORS)

Web browsers enforce the Same-Origin Policy, restricting web applications from issuing cross-origin API calls unless explicit CORS headers are returned. API Gateway provides a declarative CORS policy engine that defines:

• Allowed Origins: Specific authorized domains (e.g., https://app.example.com) or wildcards (*).
• Allowed Methods: Permitted HTTP verbs (GET, POST, PUT, DELETE, OPTIONS).
• Allowed & Exposed Headers: Headers the client may send or read from responses.
• Preflight Cache (Max Age): How long browsers can cache OPTIONS preflight responses, drastically reducing preflight traffic.

---

API Usage Plans & Client Subscriber Management

Enterprise organizations exposing APIs to external partners or commercial subscribers require monetization, quota enforcement, and tier-based consumption management. API Gateway provides this through Usage Plans and Client Subscribers.

Subscriber (Client Application) ──[client token]──> API Gateway Deployment
                                                                 │
                                                     Validates Subscription Tier
                                                                 ├── Bronze: 10 RPS, 50k req/month
                                                                 ├── Silver: 50 RPS, 500k req/month
                                                                 └── Gold:   500 RPS, 5M req/month

Core Governance Components

1. API Usage Plans: Define access agreements comprising two constraints:
   • Rate Limit: Maximum requests per second allowed for the plan.
   • Quota: Maximum total requests in a period of a minute, hour, day, or month. You choose whether requests over the quota are rejected or still allowed, and a rejected response tells the client when it can retry.
2. Subscribers: Represent API consumers. Each subscriber definition contains client names and client tokens, and names the usage plans the clients can use. Requests pass the client token in the location you define in the deployment's usage plan request policy, such as a header or a query parameter.
3. Entitlements: Each usage plan has one or more entitlements that target API deployments, possibly on different gateways. When a request arrives with a client token, the gateway checks that the client is subscribed to a plan covering that deployment, applies the rate limit and quota, and rejects requests that exceed them. If an entitlement has no rate limit or quota, access is unlimited, but the client must still be subscribed and present a client token.

---

Authentication Architectural Comparison