diff --git a/learn/security/api-input-validation-injection-prevention.md b/learn/security/api-input-validation-injection-prevention.md new file mode 100644 index 00000000..c223cbf4 --- /dev/null +++ b/learn/security/api-input-validation-injection-prevention.md @@ -0,0 +1,24 @@ +--- +title: Input Validation and Injection Prevention +description: Prevent API injection attacks and mass assignment vulnerabilities using OpenAPI schema validation and automated governance. +seo: + title: Input Validation and Injection Prevention + description: Prevent API injection attacks and mass assignment vulnerabilities using OpenAPI schema validation and automated governance. +--- + +# Input validation and injection prevention + +*This comprehensive guide is coming soon and will cover:* + +## What you'll learn + +- **SQL Injection Prevention**: Parameterized queries and input sanitization +- **Mass Assignment Protection**: Schema-based validation and field filtering +- **OpenAPI Validation**: Schema constraints and automated enforcement +- **OWASP API Security**: Addressing Top 10 injection vulnerabilities +- **Real-World Examples**: Code samples in Node.js with security patterns +- **Automated Governance**: CI/CD validation rules and policy enforcement + +--- + +*This article is currently under review and will be available soon. Return to the [API Security Framework and Fundamentals](.) to explore other security topics.* diff --git a/learn/security/api-rate-limiting-abuse-prevention.md b/learn/security/api-rate-limiting-abuse-prevention.md new file mode 100644 index 00000000..e1b16354 --- /dev/null +++ b/learn/security/api-rate-limiting-abuse-prevention.md @@ -0,0 +1,24 @@ +--- +title: Rate Limiting and Abuse Prevention +description: Implement API rate limiting strategies to prevent DoS attacks, brute force attempts, and business logic abuse. +seo: + title: Rate Limiting and Abuse Prevention + description: Implement API rate limiting strategies to prevent DoS attacks, brute force attempts, and business logic abuse. +--- + +# Rate limiting and abuse prevention for APIs + +*This comprehensive guide is coming soon and will cover:* + +## What you'll learn + +- **Rate Limiting Algorithms**: Token bucket, sliding window, and fixed window approaches +- **OpenAPI Documentation**: x-rateLimit extensions and client communication +- **Multi-Tier Protection**: Global, per-endpoint, and per-client rate limiting +- **Abuse Detection**: Pattern recognition and automated response strategies +- **Real-World Examples**: Implementation patterns in Node.js and Redis +- **Monitoring & Observability**: Metrics collection and alerting strategies + +--- + +*This article is currently under review and will be available soon. Return to the [API Security Framework and Fundamentals](.) to explore other security topics.* diff --git a/learn/security/api-tls-encryption-https-best-practices.md b/learn/security/api-tls-encryption-https-best-practices.md new file mode 100644 index 00000000..ca0ff727 --- /dev/null +++ b/learn/security/api-tls-encryption-https-best-practices.md @@ -0,0 +1,24 @@ +--- +title: TLS Encryption and HTTPS Best Practices for APIs +description: Protect data in transit with proper TLS configuration, certificate management, and HTTPS enforcement using OpenAPI security contracts. +seo: + title: TLS Encryption and HTTPS Best Practices for APIs + description: Protect data in transit with proper TLS configuration, certificate management, and HTTPS enforcement using OpenAPI security contracts. +--- + +# TLS encryption and HTTPS best practices for APIs + +*This comprehensive guide is coming soon and will cover:* + +## What you'll learn + +- **TLS 1.3 Configuration**: Modern encryption standards and cipher suite selection +- **Certificate Management**: Best practices for SSL/TLS certificate lifecycle +- **OpenAPI Security Contracts**: Enforcing HTTPS-only APIs through specifications +- **Mutual TLS (mTLS)**: Service-to-service cryptographic authentication +- **Real-World Examples**: Configuration examples for Nginx and Express.js +- **Automated Governance**: CI/CD integration for transport security validation + +--- + +*This article is currently under review and will be available soon. Return to the [API Security Framework and Fundamentals](.) to explore other security topics.* diff --git a/learn/security/authentication-authorization-openapi.md b/learn/security/authentication-authorization-openapi.md new file mode 100644 index 00000000..0123bd6b --- /dev/null +++ b/learn/security/authentication-authorization-openapi.md @@ -0,0 +1,1213 @@ +--- +title: Authentication and Authorization with OpenAPI +description: Implement secure access control using OpenAPI security schemes and modern authentication patterns. +seo: + title: Authentication and Authorization with OpenAPI + description: Implement secure access control using OpenAPI security schemes and modern authentication patterns. +--- + +# Authentication and authorization with OpenAPI + +--- + +## Key takeaways + +Authentication and authorization form the foundation of API access control. While often used interchangeably, these concepts serve distinct purposes: authentication verifies *who* the user is, while authorization determines *what* they can do. Modern APIs require both layers to prevent unauthorized access and enforce business rules. + +In this guide, we'll explore how to use OpenAPI 3.1 security schemes to define robust access control patterns that integrate seamlessly with automated governance and modern authentication providers. + +**We'll cover how to:** +- [Define authentication methods (JWT, OAuth2, API Keys, mTLS)](#authentication-methods) in OpenAPI specifications +- [Implement advanced authorization patterns](#advanced-authorization-patterns) with granular permissions +- [Enforce security requirements through automated governance](#automated-governance-for-access-control) +- [Configure API gateways from OpenAPI security definitions](#api-gateway-integration) +- [Monitor and troubleshoot authentication and authorization failures](#authentication-and-authorization-monitoring) + +--- + +## Quick start guide + +Ready to implement authentication and authorization? Start here: + +1. **Choose your authentication method:** Review [Authentication Methods](#authentication-methods) and select JWT Bearer, OAuth2, API Keys, or mTLS based on your needs +2. **Set up governance:** Implement [automated governance rules](#automated-governance-for-access-control) to prevent accidentally public endpoints +3. **Configure your gateway:** Use [API gateway integration](#api-gateway-integration) to automatically enforce your OpenAPI security definitions +4. **Add monitoring:** Set up [authentication and authorization monitoring](#authentication-and-authorization-monitoring) to track security violations +5. **Plan for issues:** Review [troubleshooting common issues](#troubleshooting-common-issues) and implement [best practices](#best-practices-summary) + +**Next Steps:** Now that you have authentication and authorization in place, explore the complete [API Security by Design guide](/learn/security) to learn about other essential security domains like TLS encryption, input validation, and rate limiting. + +--- + +## Understanding authentication vs authorization + +The distinction between authentication and authorization is fundamental to API security design. Understanding this difference helps you implement the right controls at the right layers. + +### The two-phase security process + +```mermaid +sequenceDiagram + participant U as User + participant A as API Gateway + participant Auth as Auth Service + participant API as API Endpoint + + Note over U,API: Authentication Phase + U->>A: 1. Request with credentials + A->>Auth: 2. Verify identity + Auth->>A: 3. Identity confirmed + token + A->>U: 4. Return access token + + Note over U,API: Authorization Phase + U->>A: 5. API request + token + A->>A: 6. Validate token + A->>A: 7. Check permissions/scopes + + alt Authorized + A->>API: 8. Forward request + API->>A: 9. Response + A->>U: 10. Return response + else Unauthorized + A->>U: 11. 403 Forbidden + end +``` + +*Sequence diagram showing the two-phase process: authentication verifies who the user is, while authorization determines what they can do. Both phases are essential for secure API access control.* + +**Authentication (Who are you?):** +- Verifies the identity of the caller +- Typically involves credentials like passwords, API keys, or certificates +- Results in a token or session that proves identity +- Usually happens once per session or token lifetime + +**Authorization (What can you do?):** +- Determines what resources and operations the authenticated user can access +- Based on permissions, roles, scopes, or policies +- Evaluated for each request to protected resources +- Can be fine-grained (specific endpoints) or coarse-grained (broad permissions) + +### Common authentication patterns + +**[API Keys](#authentication-methods):** +- Simple, stateless authentication +- Often used for service-to-service communication +- Limited authorization capabilities (typically binary: access or no access) + +**[JWT Bearer Tokens](#authentication-methods):** +- Self-contained tokens with embedded claims +- Support fine-grained authorization through scopes and claims +- Stateless validation (no database lookup required) +- Industry standard for modern APIs + +**[OAuth2 with PKCE](#authentication-methods):** +- Delegated authorization framework +- Supports multiple grant types and client types +- Built-in scope-based authorization +- Recommended for user-facing applications + +## Defining security schemes in OpenAPI + +OpenAPI 3.1 provides a robust framework for defining access control through two primary constructs: + +1. **`components.securitySchemes`**: Defines *how* clients can authenticate (JWT Bearer, OAuth2, API Keys) +2. **`security`**: Specifies *that* an endpoint is secured and by which mechanism(s) + +## Authentication methods + +Choose the authentication method that best fits your use case: + +{% tabs %} + {% tab label="JWT Bearer Token" %} + +### JWT bearer token authentication + +JWT (JSON Web Token) Bearer authentication is the most common pattern for modern APIs. The token contains encoded claims about the user and can be validated without database lookups. + +```yaml {% title="openapi.yaml" %} +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer # [!code highlight] Standard Bearer token scheme + bearerFormat: JWT # [!code highlight] Specify JWT format + description: "Enter JWT with 'Bearer ' prefix" + +# Apply globally to all operations # [!code highlight] +security: + - bearerAuth: [] # [!code highlight] Require authentication for all endpoints +``` + +**What this configuration does:** + +- **`type: http`** - Uses standard HTTP authentication (as opposed to API keys or OAuth2 flows) +- **`scheme: bearer`** - Specifies Bearer token authentication, where tokens are sent in the `Authorization: Bearer ` header +- **`bearerFormat: JWT`** - Documents that tokens must be valid JWTs (helps with API documentation and client generation) +- **`security: - bearerAuth: []`** - Applies this authentication requirement to all endpoints globally (individual endpoints can override this) + +This approach ensures every API request includes a valid JWT token, preventing anonymous access to protected resources. + +**JWT Token Structure:** +```javascript {% title="JWT Token Anatomy - 3 Parts Separated by Dots" %} +// PART 1: HEADER - Defines how the token is secured // [!code highlight] +{ + "alg": "RS256", // CRITICAL: Use RS256, not HS256 (prevents key confusion attacks) + "typ": "JWT", // Token type declaration (required for JWT processing) + "kid": "key-123" // Key ID helps API find correct public key for verification +} + +// PART 2: PAYLOAD - Contains user identity and permissions (NEVER put secrets here!) // [!code highlight] +{ + // Standard Claims (RFC 7519) - These provide security guarantees + "sub": "user123", // Subject: Who this token represents + "iss": "https://auth.example.com", // Issuer: MUST be HTTPS URL you trust + "aud": ["api.example.com", "admin.example.com"], // Audience: APIs that accept this token + "exp": 1640995200, // Expiration: REQUIRED - limits blast radius if stolen + "nbf": 1640991600, // Not Before: Token invalid before this time + "iat": 1640991600, // Issued At: When token was created + "jti": "unique-token-id", // JWT ID: Unique identifier (helps with revocation) + + // Custom Claims - Your application-specific data + "scopes": ["users:read", "orders:write"], // Permissions: What user can do + "role": "customer", // Role-based access control + "email": "user@example.com", // PII: Consider privacy implications + "premium": true // Feature flags or user attributes +} + +// PART 3: SIGNATURE - Cryptographic proof token wasn't tampered with // [!code highlight] +RSASHA256( + base64UrlEncode(header) + "." + // Header and payload concatenated + base64UrlEncode(payload), + private_key // NEVER expose this key - stay with auth server only! +) + +// Security Notes: // [!code highlight] +// 1. JWT is NOT encrypted - anyone can read header/payload (use JWE if needed) // [!code highlight] +// 2. Signature prevents tampering but doesn't hide content // [!code highlight] +// 3. Short expiration times (15-60 minutes) limit security exposure // [!code highlight] +// 4. Always validate iss, aud, exp claims before trusting token // [!code highlight] +``` + +**Understanding each JWT component:** + +**Header:** +- **`"alg": "RS256"`** - Specifies RSA SHA-256 signature algorithm, which uses public/private key pairs for security. This prevents token tampering since only the authorization server has the private key to sign tokens. +- **`"typ": "JWT"`** - Declares this is a JWT token (helps parsers know how to handle it) + +**Payload (Claims):** +- **`"sub": "user123"`** - Subject claim identifies the user this token represents. Your API uses this to know *who* is making the request. +- **`"iss": "https://auth.example.com"`** - Issuer claim identifies which authorization server created this token. Your API should validate this matches your trusted auth server. +- **`"aud": "api.example.com"`** - Audience claim specifies which API this token is intended for. Prevents token reuse across different services. +- **`"exp": 1640995200"`** - Expiration timestamp (Unix time). Tokens automatically become invalid after this time, limiting damage if compromised. +- **`"iat": 1640991600"`** - Issued at timestamp. Helps with token lifecycle tracking and debugging. +- **`"scopes": ["users:read", "orders:write"]`** - Custom claim listing what permissions this user has. Your authorization logic checks these scopes. + +**Signature:** +- Created by signing the encoded header and payload with the authorization server's private key +- Your API validates signatures using the corresponding public key +- If signature verification fails, the token is invalid (likely tampered with or forged) + +{% /tab %} +{% tab label="OAuth2 with Scopes" %} + +### OAuth2 with scope-based authorization + +OAuth2 provides the most flexible authorization framework, supporting fine-grained permissions through scopes and multiple authentication flows. + +```yaml {% title="openapi.yaml - OAuth2 with Security Best Practices" %} +components: + securitySchemes: + oauth2Auth: + type: oauth2 + # CRITICAL: Always use Authorization Code + PKCE for security + description: "OAuth2 Authorization Code Flow with PKCE - prevents CSRF and injection attacks" + flows: + authorizationCode: + # STEP 1: Authorization URL - where users consent to permissions + authorizationUrl: https://auth.example.com/authorize # [!code highlight] HTTPS REQUIRED - never use HTTP + + # STEP 2: Token endpoint - where your app exchanges codes for tokens + tokenUrl: https://auth.example.com/token # [!code highlight] HTTPS REQUIRED - never use HTTP + + # STEP 3: Define permission scopes using principle of least privilege + scopes: + # User-level permissions (granular access control) + 'users:read': "View user profile information" # [!code focus] Read-only access + 'users:write': "Modify user profile data" # [!code warning] Write access - more sensitive + 'users:delete': "Delete user accounts" # [!code error] High-privilege operation + + # Resource-specific permissions + 'orders:read': "View order history and details" # [!code focus] Customer data access + 'orders:write': "Create and modify orders" # [!code warning] Financial operations + 'orders:refund': "Process order refunds" # [!code error] High-value operations + + # Administrative permissions (highest privilege) + 'admin:users': "Full user management access" # [!code error] Admin-only scope + 'admin:system': "System configuration access" # [!code error] Infrastructure access + +paths: + /users/{userId}: + get: + summary: "Get user profile" + # STEP 4: Require specific permissions for each operation + security: + - oauth2Auth: ['users:read'] # [!code highlight] Minimal required scope + parameters: + - name: userId + in: path + required: true + schema: + type: string + format: uuid # [!code focus] Use UUIDs to prevent enumeration attacks + responses: + '200': + description: "User profile data" + content: + application/json: + schema: + $ref: '#/components/schemas/UserProfile' + '401': # [!code error] No valid token provided + description: "Authentication required - token missing or invalid" + content: + application/json: + schema: + $ref: '#/components/schemas/UnauthorizedError' + '403': # [!code error] Valid token but insufficient permissions + description: "Insufficient permissions - requires users:read scope" + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenError' + + patch: + summary: "Update user profile" + security: + - oauth2Auth: ['users:write'] # [!code warning] Higher privilege required + # STEP 5: Document security requirements clearly + description: | + Updates user profile information. Requires 'users:write' scope. + + **Security Notes:** + - Users can only modify their own profiles unless they have admin:users scope + - Sensitive fields like email changes may require additional verification + - All changes are logged for audit purposes + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UserProfileUpdate' + responses: + '200': + description: "Profile updated successfully" + '401': # [!code error] Authentication failure + description: "Authentication required" + '403': # [!code error] Authorization failure + description: "Insufficient permissions - requires users:write scope" + '422': # [!code warning] Validation errors + description: "Invalid input data" + +# STEP 6: Define common error schemas for consistent security responses +components: + schemas: + UnauthorizedError: + type: object + properties: + error: + type: string + example: "Authentication required" + message: + type: string + example: "Please provide a valid Bearer token" + + ForbiddenError: + type: object + properties: + error: + type: string + example: "Insufficient permissions" + required_scopes: # [!code focus] Help developers understand what's needed + type: array + items: + type: string + example: ["users:write"] +``` + +**Breaking down this OAuth2 configuration:** + +**Security Scheme Definition:** +- **`type: oauth2`** - Declares this uses the OAuth2 standard for authorization +- **`authorizationCode`** flow - The most secure OAuth2 flow for web applications, involves redirecting users to the authorization server +- **`authorizationUrl`** - Where users go to grant permissions (must use HTTPS for security) +- **`tokenUrl`** - Where your app exchanges authorization codes for access tokens (must use HTTPS) + +**Scope-Based Permissions:** +- **`'users:read'`** - Allows reading user profile data but not modifying it +- **`'users:write'`** - Allows updating user profiles (typically granted to users for their own profiles) +- **`'orders:read'` & `'orders:write'`** - Separate permissions for order management +- **`'admin:users'`** - Administrative permission that overrides user-level restrictions + +**Endpoint-Level Authorization:** +- **`security: - oauth2Auth: ['users:read']`** - This endpoint requires a valid OAuth2 token with the `users:read` scope +- **Different endpoints require different scopes** - GET operations typically need `read` scopes, while PATCH/POST/DELETE need `write` scopes +- **Response codes `401` vs `403`**: + - `401` = No valid token provided (authentication problem) + - `403` = Valid token but insufficient permissions (authorization problem) + +This pattern allows fine-grained control: a user might have permission to read profiles but not edit them, while administrators have broader access. + +{% /tab %} +{% tab label="API Key" %} + +### API key authentication + +For service-to-service communication and simpler use cases, API keys provide straightforward authentication. + +```yaml {% title="openapi.yaml" %} +components: + securitySchemes: + apiKeyAuth: + type: apiKey + in: header # [!code highlight] Header-based API key (preferred) + name: X-API-Key # [!code highlight] Custom header name + description: "API key for service authentication" + +paths: + /internal/health: + get: + summary: "Internal health check" + security: + - apiKeyAuth: [] # [!code highlight] Require API key authentication + responses: + '200': + description: "Service health status" + '401': + description: "Invalid or missing API key" +``` + +**API Key configuration explained:** + +- **`type: apiKey`** - Declares this uses simple API key authentication (as opposed to OAuth2 or JWT) +- **`in: header`** - API key is sent in HTTP headers (more secure than query parameters, which get logged) +- **`name: X-API-Key`** - Specifies the exact header name clients must use: `X-API-Key: your-secret-key-here` +- **`security: - apiKeyAuth: []`** - Requires a valid API key for this endpoint + +**When to use API keys:** +- **Service-to-service communication** - When your API calls another internal service +- **Simple integrations** - Third-party services that don't need complex user permissions +- **Internal tools** - Admin dashboards or monitoring systems + +**Security considerations:** +- API keys identify the *application*, not the *user* (unlike JWT tokens) +- Keys should be long, random strings (at least 32 characters) +- Store keys securely and rotate them regularly +- Never include API keys in client-side code or URLs + +{% /tab %} +{% tab label="Mutual TLS (mTLS)" %} + +### Mutual TLS (mTLS) for service authentication + +For high-security environments and service-to-service communication, [mutual TLS](api-tls-encryption-https-best-practices#mutual-tls-mtls-two-way-authentication) provides cryptographic identity verification. + +```yaml {% title="openapi.yaml" %} +components: + securitySchemes: + mtlsAuth: + type: mutualTLS # [!code highlight] Cryptographic client authentication + description: "Client certificate authentication" + +paths: + /internal/payments: + post: + security: + - mtlsAuth: [] # [!code highlight] Requires valid client certificate + summary: "Process payment (internal service only)" + responses: + '200': + description: "Payment processed" + '401': # [!code highlight] Certificate validation failure + description: "Invalid client certificate" +``` + +**mTLS configuration explained:** + +- **`type: mutualTLS`** - Requires both server and client to present valid certificates +- **Cryptographic authentication** - More secure than API keys since certificates are harder to forge +- **Best for internal services** - High-security service-to-service communication +- **Zero-trust architecture** - No implicit trust based on network location + +{% /tab %} +{% /tabs %} + +## Automated governance for access control + +One of the most common API vulnerabilities is the accidentally public endpoint—an operation that should require authentication but doesn't have security requirements defined. Automated governance prevents this by enforcing security rules during development. + +### Security governance rules + +**Mandatory Authentication on Write Operations:** +```yaml {% title="governance-rules.yaml" %} +rules: + require-auth-on-mutations: + description: "All write operations must have security requirements" + severity: error + given: "$.paths[*][*]" + when: + function: enumerated + functionOptions: + values: ["post", "put", "patch", "delete"] + then: + field: "security" + function: truthy +``` + +**Validate Security Scheme Definitions:** +```yaml {% title="governance-rules.yaml" %} +rules: + security-schemes-defined: + description: "All security references must have corresponding definitions" + severity: error + given: "$.paths[*][*].security[*]" + then: + function: defined-security-scheme +``` + +When these rules run in your CI/CD pipeline, any endpoint without proper security definitions causes the build to fail, preventing accidentally public endpoints from reaching production. + +### Implementation example + +**Before Governance (Vulnerable):** +```yaml +paths: + /users/{userId}: + delete: + summary: "Delete user account" + # Missing security requirement - accidentally public! + responses: + '204': + description: "User deleted" +``` + +**After Governance (Secure):** +```yaml +paths: + /users/{userId}: + delete: + summary: "Delete user account" + security: + - oauth2Auth: ['admin:users'] # Required by governance rules + responses: + '204': + description: "User deleted" + '401': + description: "Authentication required" + '403': + description: "Insufficient permissions" +``` + +**Next steps:** Once you've implemented automated governance, consider setting up [comprehensive monitoring](#authentication-and-authorization-monitoring) to track security violations and [troubleshooting processes](#troubleshooting-common-issues) to handle authentication failures effectively. + +## Security definitions as configuration + +Defining security schemes in OpenAPI extends beyond documentation—it establishes configuration-as-code that drives consistency across your entire API ecosystem: + +### API gateway integration + +Modern API gateways can import OpenAPI specifications and automatically configure authentication and authorization based on your security definitions. + +**Kong Gateway Configuration:** +```yaml {% title="kong.yaml" %} +# Generated from OpenAPI securitySchemes +plugins: +- name: jwt + config: + key_claim_name: iss + secret_is_base64: false + claims_to_verify: + - exp + - iat + run_on_preflight: false + +# Generated from OAuth2 scopes +- name: openapi-validator + config: + validate_request_body: true + validate_response_body: false + api_spec: "/path/to/openapi.yaml" +``` + +**AWS API Gateway Integration:** +```yaml {% title="serverless.yml" %} +functions: + getUserProfile: + handler: users.getProfile + events: + - http: + path: users/{userId} + method: get + # Generated from OpenAPI security requirements + authorizer: + name: jwtAuthorizer + scopes: + - users:read +``` + +### Code generation + +OpenAPI security schemes enable automated generation of authentication handling in client SDKs and server stubs. + +**Generated Client SDK (TypeScript):** +```typescript +// Auto-generated from OpenAPI security schemes +class APIClient { + private bearerToken?: string; + + setBearerToken(token: string) { + this.bearerToken = token; + } + + async getUserProfile(userId: string): Promise { + const headers: Record = {}; + + // Auto-added based on security requirements + if (this.bearerToken) { + headers['Authorization'] = `Bearer ${this.bearerToken}`; + } + + const response = await fetch(`/users/${userId}`, { headers }); + + if (response.status === 401) { + throw new AuthenticationError('Bearer token required'); + } + + if (response.status === 403) { + throw new AuthorizationError('Insufficient permissions'); + } + + return response.json(); + } +} +``` + +**Development workflow:** Generated client SDKs like the one above help catch authentication issues early. When problems occur in production, use [monitoring](#authentication-and-authorization-monitoring) and [troubleshooting](#troubleshooting-common-issues) to diagnose and resolve issues quickly. + +## Advanced authorization patterns + +Choose the authorization pattern that fits your application's complexity: + +{% tabs %} + {% tab label="Role-Based Access Control (RBAC)" %} + +### Role-based access control (RBAC) + +While OpenAPI doesn't have built-in RBAC support, you can model roles through scopes or custom extensions. + +```yaml {% title="openapi.yaml" %} +components: + securitySchemes: + oauth2Auth: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://auth.example.com/authorize # [!code highlight] HTTPS required + tokenUrl: https://auth.example.com/token # [!code highlight] HTTPS required + scopes: + # Role-based scopes # [!code highlight] + 'role:admin': "Administrative access to all resources" # [!code highlight] Admin role + 'role:manager': "Management access within assigned teams" # [!code highlight] Manager role + 'role:user': "Standard user access to own resources" # [!code highlight] User role + + # Resource-based scopes # [!code highlight] + 'users:read': "Read user profiles" + 'users:write': "Modify user profiles" + 'orders:read': "View orders" + 'orders:write': "Create and modify orders" + +paths: + /admin/users: + get: + summary: "List all users (admin only)" + security: + - oauth2Auth: ['role:admin'] # [!code highlight] Admin-only endpoint + responses: + '200': + description: "List of all users" + '403': # [!code highlight] Authorization failure + description: "Admin access required" + + /users/me: + get: + summary: "Get own profile" + security: + - oauth2Auth: ['role:user', 'users:read'] # [!code highlight] Multiple scope requirement + responses: + '200': + description: "User's own profile" +``` + +{% /tab %} +{% tab label="Context-Dependent Authorization" %} + +### Context-dependent authorization + +Some authorization decisions depend on request context, such as resource ownership or dynamic policies. + +```yaml {% title="openapi.yaml" %} +paths: + /users/{userId}/orders: + get: + summary: "Get user's orders" + security: + - oauth2Auth: ['orders:read'] # [!code highlight] Base permission required + parameters: + - name: userId + in: path + required: true + schema: + type: string # [!code highlight] User ID parameter + responses: + '200': + description: "User's order history" + '403': # [!code highlight] Resource ownership check + description: "Can only access own orders unless admin" + # Custom extension for context-dependent rules # [!code highlight] + x-authorization-context: + resource-owner-check: true # [!code highlight] Check resource ownership + admin-override: true # [!code highlight] Admin can bypass ownership +``` + +{% /tab %} +{% tab label="Fine-Grained Permissions" %} + +### Fine-grained permissions + +For complex applications, you might need very specific permissions that combine multiple factors. + +```yaml {% title="openapi.yaml" %} +components: + securitySchemes: + oauth2Auth: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://auth.example.com/authorize # [!code highlight] HTTPS required + tokenUrl: https://auth.example.com/token # [!code highlight] HTTPS required + scopes: + # Operation + Resource + Condition # [!code highlight] Fine-grained permissions + 'orders:read:own': "Read own orders" # [!code highlight] Own resources only + 'orders:read:team': "Read team orders" # [!code highlight] Team scope + 'orders:read:all': "Read all orders" # [!code highlight] Global read access + 'orders:write:own': "Modify own orders" # [!code highlight] Own resources only + 'orders:write:team': "Modify team orders" # [!code highlight] Team write access + 'orders:cancel:all': "Cancel any order" # [!code highlight] Admin-level permission + +paths: + /orders/{orderId}: + patch: + summary: "Update order" + security: + - oauth2Auth: ['orders:write:own', 'orders:write:team'] # [!code highlight] Multiple scope options + responses: + '200': + description: "Order updated" + '403': # [!code highlight] Authorization failure + description: "Insufficient permissions to update order" +``` + +{% /tab %} +{% /tabs %} + +**Implementation tip:** Complex authorization patterns require robust [monitoring and troubleshooting](#troubleshooting-common-issues). The patterns above should be complemented with comprehensive logging and [best practices](#best-practices-summary) for production deployment. + +## Authentication and authorization monitoring + +Choose your monitoring approach based on your technology stack: + +{% tabs %} + {% tab label="Authentication Monitoring (JS)" %} + +### Token validation metrics + +Monitor authentication success and failure patterns to detect potential attacks and system issues. + +```javascript +// Express.js middleware for auth monitoring +const authMetrics = { + successful_auths: 0, + failed_auths: 0, + expired_tokens: 0, + invalid_signatures: 0 +}; + +app.use('/api', (req, res, next) => { + const token = req.headers.authorization?.replace('Bearer ', ''); // [!code highlight] Extract Bearer token + + if (!token) { + authMetrics.failed_auths++; // [!code highlight] Track failed attempts + return res.status(401).json({ error: 'Bearer token required' }); + } + + try { + const decoded = jwt.verify(token, publicKey, { // [!code highlight] Verify with public key + algorithms: ['RS256'], // [!code highlight] Only allow RS256 algorithm + audience: 'api.example.com', // [!code highlight] Verify intended audience + issuer: 'https://auth.example.com' // [!code highlight] Verify trusted issuer + }); + + // Check token expiration // [!code highlight] + if (decoded.exp < Date.now() / 1000) { + authMetrics.expired_tokens++; // [!code highlight] Track expired tokens + return res.status(401).json({ error: 'Token expired' }); + } + + authMetrics.successful_auths++; // [!code highlight] Track successful auths + req.user = decoded; // [!code highlight] Attach user to request + next(); + + } catch (error) { + if (error.name === 'JsonWebTokenError') { + authMetrics.invalid_signatures++; // [!code error] Track signature failures + } else { + authMetrics.failed_auths++; // [!code error] Track other failures + } + + return res.status(401).json({ error: 'Invalid token' }); + } +}); +``` + +**How this authentication monitoring works:** + +**Token Extraction:** +- **`req.headers.authorization?.replace('Bearer ', '')`** - Safely extracts the JWT token from the `Authorization: Bearer ` header +- The `?` optional chaining prevents errors if the header is missing + +**Token Validation Process:** +1. **`jwt.verify(token, publicKey, {...})`** - Uses the public key to verify the token signature wasn't tampered with +2. **`algorithms: ['RS256']`** - Only accepts RSA SHA-256 signatures (prevents algorithm confusion attacks) +3. **`audience` & `issuer` validation** - Ensures the token is intended for your API and came from your trusted auth server +4. **Expiration check** - Even if signature is valid, reject tokens past their expiration time + +**Security Metrics Collection:** +- **`successful_auths`** - Count of valid authentications (helps with usage analytics) +- **`failed_auths`** - Missing or invalid tokens (spikes might indicate attacks) +- **`expired_tokens`** - Tokens past expiration (helps tune token lifetimes) +- **`invalid_signatures`** - Tampered or forged tokens (critical security indicator) + +**What to watch for:** +- **High `invalid_signatures`** - Possible token forgery attempts +- **Many `expired_tokens`** - Token lifetimes might be too short, causing poor user experience +- **Sudden spikes in `failed_auths`** - Potential brute force or credential stuffing attacks + +{% /tab %} +{% tab label="Authorization Monitoring (JavaScript)" %} + +### Authorization failure analysis + +Track authorization failures to identify potential privilege escalation attempts or misconfigured permissions. + +```javascript +// Express.js middleware for authorization monitoring +class AuthorizationMonitor { + constructor() { + this.permissionDenials = new Map(); // [!code highlight] Track denied requests + this.scopeViolations = new Map(); // [!code highlight] Track scope failures + } + + checkScopes(requiredScopes, userScopes, endpoint) { + const requiredSet = new Set(requiredScopes); + const userSet = new Set(userScopes); + const missingScopes = [...requiredSet].filter(scope => !userSet.has(scope)); // [!code highlight] Compare scopes + + if (missingScopes.length > 0) { + // Initialize counters if endpoint is new + if (!this.scopeViolations.has(endpoint)) { + this.scopeViolations.set(endpoint, 0); + } + + this.scopeViolations.set(endpoint, this.scopeViolations.get(endpoint) + 1); // [!code error] Track security violation + + console.warn(`Scope violation at ${endpoint}`, { // [!code error] Log security event + requiredScopes, + userScopes, + missingScopes, + userId: 'unknown' // Would typically come from req.user + }); + + return false; // [!code error] Deny access + } + + return true; // [!code highlight] Allow access + } + + getViolationReport() { + return { + permissionDenials: Object.fromEntries(this.permissionDenials), + scopeViolations: Object.fromEntries(this.scopeViolations) // [!code highlight] Security metrics + }; + } +} + +// Express.js middleware usage example +const authMonitor = new AuthorizationMonitor(); + +function requireScopes(requiredScopes) { + return (req, res, next) => { + const userScopes = req.user?.scopes || []; + const endpoint = req.route.path; + + if (authMonitor.checkScopes(requiredScopes, userScopes, endpoint)) { + next(); // User has required scopes + } else { + res.status(403).json({ + error: 'Insufficient permissions', + required_scopes: requiredScopes + }); + } + }; +} +``` + +**How this authorization monitoring works:** + +**Scope-Based Authorization:** +- **`[...requiredSet].filter(scope => !userSet.has(scope))`** - Uses array filter to find missing permissions (e.g., endpoint needs `['orders:write']` but user only has `['orders:read']`) +- **`missingScopes`** - If this array has length > 0, the user lacks required permissions + +**Security Tracking:** +- **`permissionDenials`** - Counts authorization failures per endpoint (helps identify which resources are most targeted) +- **`scopeViolations`** - Tracks specific permission mismatches (helps identify privilege escalation attempts) +- **`new Map()`** - Provides efficient key-value storage for endpoint counters + +**Structured Logging:** +- **`console.warn()`** - Records security events with structured data for analysis +- **Object context** - Includes metadata like: + - Which scopes were required vs. provided + - Which specific permissions were missing + - User ID for tracking repeat offenders + - Endpoint being accessed + +**Security Analysis:** +- **High violation counts on specific endpoints** - May indicate targeted attacks +- **Users repeatedly failing scope checks** - Possible compromised accounts or privilege escalation attempts +- **Missing scopes patterns** - Could reveal permission misconfiguration (e.g., users consistently missing `read` permissions might indicate overly restrictive defaults) + +This monitoring helps distinguish between legitimate access denials (user simply doesn't have permission) and suspicious activity (repeated attempts to access unauthorized resources). + +{% /tab %} +{% /tabs %} + +### Security event logging + +Implement comprehensive logging for security events to support incident response and compliance requirements. + +```yaml {% title="logging-config.yaml" %} +# Structured logging for security events +security_events: + authentication_success: + level: INFO + fields: [user_id, client_ip, user_agent, timestamp] + + authentication_failure: + level: WARN + fields: [client_ip, user_agent, failure_reason, timestamp] + + authorization_failure: + level: WARN + fields: [user_id, endpoint, required_scopes, user_scopes, timestamp] + + token_expiration: + level: INFO + fields: [user_id, token_issued_at, token_expired_at, timestamp] +``` + +**Security operations:** When monitoring detects issues, use the structured logs above with the [troubleshooting guide below](#troubleshooting-common-issues) to quickly diagnose and resolve authentication and authorization problems. + +## Troubleshooting common issues + +### Authentication problems + +{% tabs %} +{% tab label="Missing or Invalid Bearer Token" %} + +**Error occurs when:** Client sends request without Bearer token or provides malformed token. + +```bash {% title="Testing Unauthenticated Access" %} +# Test unauthenticated access (should fail with 401) +curl -i https://api.example.com/users/me + +# Expected response: +# HTTP/1.1 401 Unauthorized +# Content-Type: application/json +# {"error": "Bearer token required"} +``` + +**Common causes:** +- Client forgot to include `Authorization` header +- Malformed header format (missing "Bearer " prefix) +- Empty or null token value +- Token contains invalid characters + +**How to fix:** +- Ensure clients include the header: `Authorization: Bearer ` +- Validate token format before sending requests +- Check your authentication middleware configuration + +{% /tab %} +{% tab label="Invalid Token Signature" %} + +**Error occurs when:** JWT token's signature doesn't match expected signature, indicating tampering or wrong issuer. + +```bash {% title="Testing Invalid Token Signature" %} +# Test with invalid token (should fail with 401) +curl -H "Authorization: Bearer invalid_token" \ + https://api.example.com/users/me + +# Expected response: +# HTTP/1.1 401 Unauthorized +# {"error": "Invalid token signature"} +``` + +**Common causes:** +- Token was manually modified or corrupted +- Wrong signing key used to verify the token +- Token was issued by a different authorization server +- Key rotation issues (old key used to verify new token) + +**How to fix:** +- Verify your JWT signing key configuration +- Check key rotation procedures +- Ensure tokens are only issued by trusted authorization servers +- Never modify JWT tokens after they're created + +{% /tab %} +{% tab label="Expired Token" %} + +**Error occurs when:** JWT token has passed its expiration time (`exp` claim), which is a security best practice. + +```bash {% title="Testing Expired Token" %} +# Test with expired token +curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." \ + https://api.example.com/users/me + +# Expected response: +# HTTP/1.1 401 Unauthorized +# {"error": "Token expired"} +``` + +**Common causes:** +- Token has passed its `exp` (expiration) time +- Client cached an old token without refreshing +- Token lifetime is too short for your use case +- Time synchronization issues between servers + +**How to fix:** +- Implement token refresh logic in your clients +- Use refresh tokens to obtain new access tokens +- Adjust token lifetime based on security vs. usability needs +- Ensure server clocks are synchronized (use NTP) +- Clear expired tokens from client storage + +{% /tab %} +{% /tabs %} + +### Authorization problems + +{% tabs %} +{% tab label="Insufficient Scopes" %} + +**Problem:** User has valid token but lacks required permissions/scopes for the operation. + +```bash {% title="Testing Scope Enforcement" %} +# Test scope enforcement (readonly token trying to write) +curl -H "Authorization: Bearer readonly_token" \ + -X POST \ + -H "Content-Type: application/json" \ + -d '{"name": "test"}' \ + https://api.example.com/users + +# Expected response: +# HTTP/1.1 403 Forbidden +# {"error": "Insufficient permissions", "required_scopes": ["users:write"]} +``` + +**Common causes:** +- Token has read-only scopes but endpoint requires write access +- User role doesn't include necessary permissions +- Scope names don't match between token and OpenAPI spec +- Token was issued for different resource/service + +**How to fix:** +- Check required scopes in your OpenAPI security definitions +- Verify user has been granted appropriate permissions +- Ensure scope names are consistent across auth server and API +- Request tokens with broader scopes if user is authorized + +{% /tab %} +{% tab label="Missing Security Requirements" %} + +**Problem:** OpenAPI specification doesn't specify security requirements for sensitive endpoints. + +```yaml {% title="Common OpenAPI Security Bug" %} +# Common issue: forgetting security on sensitive endpoints +paths: + /admin/users: + delete: + summary: "Delete all users" + # BUG: Missing security requirement! # [!code error] + # security: + # - oauth2Auth: ['admin:users'] + responses: + '204': + description: "All users deleted" +``` + +**Common causes:** +- Developer forgot to add `security:` property to endpoint +- Copy-pasted endpoint from public API without adding security +- Global security was removed but individual endpoints not updated +- New endpoints added without security review + +**How to fix:** +- Add explicit security requirements to all protected endpoints +- Use linting rules to catch missing security definitions +- Implement code review processes for new endpoints +- Consider setting global security as default with explicit overrides + +{% /tab %} +{% tab label="Configuration Mismatches" %} + +**Problem:** API gateway configuration doesn't match OpenAPI security specifications. + +```bash {% title="Testing Gateway Configuration Sync" %} +# Verify gateway is enforcing the same rules as OpenAPI spec +curl -H "Authorization: Bearer user_token" \ + -X DELETE \ + https://api.example.com/admin/users + +# If this succeeds when it should fail, gateway config is out of sync +``` + +**Common causes:** +- Gateway config was updated manually but not synced with OpenAPI +- Deployment pipeline doesn't update gateway from OpenAPI spec +- Multiple versions of API spec with different security requirements +- Gateway caching old configuration after spec changes + +**How to fix:** +- Automate gateway configuration from OpenAPI specifications +- Implement configuration drift detection between spec and gateway +- Use infrastructure-as-code to manage gateway settings +- Test security enforcement as part of deployment pipeline +- Clear gateway cache after specification updates + +{% /tab %} +{% /tabs %} + +### Debugging checklist + +1. **Verify token format and claims:** + ```bash + # Decode JWT to inspect claims (don't use in production) + echo "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." | base64 -d + ``` + +2. **Check security scheme definitions:** + ```yaml + # Ensure all referenced security schemes are defined + components: + securitySchemes: + oauth2Auth: # Must match security references + type: oauth2 + # ... configuration + ``` + +3. **Validate scope requirements:** + ```yaml + # Ensure required scopes exist in security scheme + security: + - oauth2Auth: ['users:write'] # Must be defined in scopes + ``` + +4. **Test authentication flow:** + ```bash + # Full OAuth2 flow test + # 1. Get authorization code + open "https://auth.example.com/authorize?response_type=code&client_id=..." + + # 2. Exchange code for token + curl -X POST https://auth.example.com/token \ + -d "grant_type=authorization_code&code=..." + + # 3. Use token for API access + curl -H "Authorization: Bearer access_token" \ + https://api.example.com/users/me + ``` + +## Best practices summary + +### Security scheme design +- Use JWT Bearer tokens for stateless authentication +- Implement OAuth2 with PKCE for user-facing applications +- Define granular scopes that map to business operations +- Use mTLS for high-trust service-to-service communication + +### Governance and automation +- Require security definitions on all write operations +- Validate that all security references have corresponding definitions +- Fail builds when security requirements are missing +- Generate gateway configurations from OpenAPI security schemes + +### Monitoring and observability +- Track authentication success/failure rates +- Monitor authorization violations by endpoint +- Log security events with sufficient context for incident response +- Set up alerts for unusual authentication patterns + +### Implementation +- Generate client SDKs with built-in authentication handling +- Use OpenAPI security schemes to configure API gateways +- Implement proper error responses (401 vs 403) +- Test authentication and authorization scenarios in CI/CD + +## Frequently asked questions + +### What's the difference between authentication and authorization? +Authentication verifies *who* the user is (like checking an ID card), while authorization determines *what* they can do (like checking permissions). Authentication happens first and provides identity, while authorization uses that identity to make access decisions for each request. + +### Should I use JWT or OAuth2 for my API? +JWT is a token format, while OAuth2 is an authorization framework. They work together: OAuth2 defines how to obtain tokens, and JWT defines the token format. Use OAuth2 with JWT tokens for user-facing applications, and consider simpler JWT Bearer authentication for service-to-service communication. See [Authentication Methods](#authentication-methods) for detailed implementation examples. + +### How do I implement fine-grained permissions with OpenAPI? +Use OAuth2 scopes to define specific permissions like `users:read`, `orders:write`, or `admin:users`. You can also model roles through scopes (e.g., `role:admin`) or use [advanced authorization patterns](#advanced-authorization-patterns) for complex authorization logic that depends on request context. + +### What happens if I forget to add security requirements to an endpoint? +The endpoint becomes accidentally public, which is one of the most common API vulnerabilities. [Automated governance rules](#automated-governance-for-access-control) can prevent this by failing builds when write operations (POST, PUT, PATCH, DELETE) don't have security requirements defined. + +### How do I handle authorization that depends on resource ownership? +OpenAPI security schemes handle authentication and basic authorization (scopes/roles), but context-dependent authorization (like "users can only access their own resources") typically requires custom logic in your application. See [Advanced Authorization Patterns](#advanced-authorization-patterns) for examples of documenting these requirements using custom extensions like `x-authorization-context`. + +## Resources + +### Standards and Specifications +- [OpenAPI Security Schemes](https://spec.openapis.org/oas/v3.1.0#security-scheme-object) - Official specification for defining authentication and authorization +- [JWT RFC 7519](https://tools.ietf.org/html/rfc7519) - JSON Web Token standard for secure information transmission +- [OAuth2 RFC 6749](https://tools.ietf.org/html/rfc6749) - Authorization framework for delegated access +- [OAuth2 PKCE RFC 7636](https://tools.ietf.org/html/rfc7636) - Proof Key for Code Exchange extension for public clients + +### Implementation Tools +- [Auth0](https://auth0.com/) - Managed authentication and authorization platform with OpenAPI integration +- [Keycloak](https://www.keycloak.org/) - Open-source identity and access management with OAuth2/JWT support +- [Kong](https://konghq.com/) - API gateway with native OpenAPI security scheme support +- [AWS API Gateway](https://aws.amazon.com/api-gateway/) - Managed API gateway with built-in authentication and authorization + +### Security Best Practices +- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) - Including API1:2023 (Broken Object Level Authorization) and API2:2023 (Broken Authentication) +- [NIST Digital Identity Guidelines](https://pages.nist.gov/800-63-3/) - Comprehensive guidance on authentication and identity verification +- [OAuth2 Security Best Practices](https://tools.ietf.org/html/draft-ietf-oauth-security-topics) - Latest security recommendations for OAuth2 implementations + +### Related Security Topics +- [API TLS Encryption and HTTPS Best Practices](api-tls-encryption-https-best-practices) - Secure data in transit with mTLS +- [API Input Validation and Injection Prevention](api-input-validation-injection-prevention) - Protect APIs from malicious data +- [API Rate Limiting and Abuse Prevention](api-rate-limiting-abuse-prevention) - Prevent brute force attacks on auth endpoints +- [API Security by Design: Complete Guide](/learn/security) - Overview of all API security domains \ No newline at end of file diff --git a/learn/security/index.md b/learn/security/index.md new file mode 100644 index 00000000..ef1d3b24 --- /dev/null +++ b/learn/security/index.md @@ -0,0 +1,250 @@ +--- +title: "API Security by Design: Framework and Fundamentals" +description: Build secure APIs from the ground up using OpenAPI security contracts and automated governance. +seo: + title: "API Security by Design: Framework and Fundamentals" + description: Build secure APIs from the ground up using OpenAPI security contracts and automated governance. +--- + +# API Security by Design: Framework and Fundamentals + +_Build secure APIs from the ground up using OpenAPI security contracts and automated governance._ + +--- + +## Key takeaways + +Many teams discover security vulnerabilities after they're already in production, but it doesn't have to be that way! + +This comprehensive guide shows you how to turn your OpenAPI specification into a security contract that actually gets enforced. You'll learn to implement TLS encryption, input validation, rate limiting policies, and access control. By the time you're done, you'll know how to catch security issues during the design phase instead of scrambling to fix them once they're in production. + +**What you'll learn:** +- Transform your OpenAPI specs into executable security policies +- Automate security enforcement in your CI/CD pipeline +- Reduce vulnerability discovery time (from months to minutes in some cases) +- Build APIs that are secure by design upfront + +--- + +## From reactive patching to proactive API security + +High-profile data breaches frequently trace back to insecure APIs, exposing a fundamental flaw in traditional security approaches. The conventional method—identifying and patching vulnerabilities in production—is reactive, costly, and ultimately inadequate. In its typical form, this paradigm treats security as an afterthought. + +Shifting security practices to the left in the development lifecycle, known as the "shift-left" imperative, addresses this by integrating security into the earliest stages of design and development. This proactive model prevents vulnerabilities from being introduced in the first place, rather than attempting to remediate them under pressure in production environments. + +### OpenAPI as your security contract + +The core of this strategy is treating your OpenAPI specification not merely as documentation, but as an executable security contract. This contract declaratively defines a set of security requirements, constraints, and policies before any application code is written. It becomes the single source of truth that dictates how an API must behave to be considered secure, effectively implementing a "policy-as-code" approach for APIs. + +However, a contract, much like a law, is only as strong as its enforcement. This is where automated governance and linting tools provide value by transforming your contract into dynamic, automated guardrails that validate security requirements at every stage of development. When integrated into a Continuous Integration/Continuous Deployment (CI/CD) pipeline, this automated governance acts as a gatekeeper, failing builds that violate the security contract and requiring fixes before deployment. + +## The four pillars of API security + +Building secure APIs doesn't have to feel like playing whack-a-mole with vulnerabilities. Once you shift from reactive patching to proactive design, you'll wonder why you ever did it any other way. Let's explore how to make security an automatic part of your API development process. + +```mermaid +graph TD + A["🏛️ Secure API Foundation"] --> B["🔐 TLS Encryption
Data in Transit"] + A --> C["✅ Input Validation
Schema Contracts"] + A --> D["⚡ Rate Limiting
Abuse Prevention"] + A --> E["🔑 Access Control
Auth & Authorization"] + + B --> F["• HTTPS Enforcement
• Certificate Management
• Strong Cipher Suites"] + C --> G["• JSON Schema Rules
• Type Validation
• Length Constraints"] + D --> H["• x-rateLimit Extensions
• 429 Response Headers
• Multi-tier Limits"] + E --> I["• Security Schemes
• JWT/OAuth2
• Scope Management"] + + J["📄 OpenAPI 3.1
Specification"] --> A + K["⚙️ Automated
Governance"] --> A + + style A fill:#e8f5e8 + style B fill:#e3f2fd + style C fill:#fff3e0 + style D fill:#fce4ec + style E fill:#f1f8e9 + style J fill:#e1f5fe + style K fill:#f3e5f5 +``` + +*Architecture diagram showing the four essential areas of API security (TLS encryption, input validation, rate limiting, access control) supported by OpenAPI specifications and automated governance tools.* + +## Deep dive guides + +Each security domain requires specific knowledge and implementation techniques. Choose the guide that matches your current focus: + +{% cards %} +{% card title="API TLS encryption and HTTPS best practices" to="/learn/security/api-tls-encryption-https-best-practices" %} +Protect data in transit with proper TLS configuration, certificate management, and HTTPS enforcement. + +**Key topics:** +- TLS 1.3 implementation and cipher suite selection +- OpenAPI server URL security contracts +- Mutual TLS (mTLS) for service-to-service communication +- Real-world case study: Heartbleed vulnerability and lessons learned + +**Perfect for:** Infrastructure teams, DevOps engineers, and security architects +{% /card %} + +{% card title="API input validation and injection prevention" to="/learn/security/api-input-validation-injection-prevention" %} +Stop injection attacks using OpenAPI schema validation and automated governance rules. + +**Key topics:** +- JSON Schema security constraints and validation patterns +- Mass assignment attack prevention +- SQL injection and OGNL injection defense strategies +- Real-world case study: Equifax breach analysis + +**Perfect for:** Backend developers, security engineers, and API architects +{% /card %} + +{% card title="API rate limiting and abuse prevention" to="/learn/security/api-rate-limiting-abuse-prevention" %} +Prevent DoS attacks, brute force attempts, and business logic abuse through strategic rate limiting. + +**Key topics:** +- Rate limiting algorithms and implementation patterns +- OpenAPI x-rateLimit extensions and documentation +- Multi-tier rate limiting strategies +- Real-world case study: Facebook phone number scraping incident + +**Perfect for:** API product managers, DevOps teams, and security operations +{% /card %} + +{% card title="Authentication and authorization with OpenAPI" to="/learn/security/authentication-authorization-openapi" %} +Implement secure access control using OpenAPI security schemes and modern authentication patterns. + +**Key topics:** +- OpenAPI security schemes (JWT, OAuth2, API Keys, mTLS) +- Authentication vs authorization flow patterns +- Scope-based access control and permission systems +- Security scheme governance and automation + +**Perfect for:** Identity and access management teams, full-stack developers, and security engineers +{% /card %} +{% /cards %} + +## Understanding design-time vs runtime security + +It's important to understand that OpenAPI-based security governance operates at **design-time**, not runtime. This governance approach excels at preventing configuration errors, missing security controls, and specification inconsistencies before they reach production. That said, it cannot prevent runtime vulnerabilities in the underlying implementation. + +### API security implementation timeline + +```mermaid +timeline + title API Security Implementation Timeline + + section Design Phase + OpenAPI Spec : Security schemes defined + : Input validation rules + : Rate limiting policies + + section Build Phase + Code Generation : Security middleware + : Validation logic + CI/CD Pipeline : Governance checks + : Security linting + + section Runtime Phase + Production : TLS termination + : Authentication + : Rate limiting + : Input validation + Monitoring : Attack detection + : Performance metrics +``` + +*Timeline showing how API security spans from design-time specification through build automation to runtime enforcement, with different security controls applied at each phase.* + +**Design-time security governance prevents:** +- Accidentally public endpoints (missing security requirements) +- Insecure server configurations (HTTP instead of HTTPS) +- Missing input validation constraints +- Inconsistent rate limiting policies +- Data leakage through unused components + +**Runtime security still requires:** +- Patch management for frameworks and libraries (like the Heartbleed OpenSSL vulnerability) +- Secure coding practices and parameterized queries +- Infrastructure security monitoring and alerting +- Penetration testing and vulnerability scanning + +True "secure by design" requires both: design-time contracts enforced through OpenAPI governance *and* runtime security posture management as part of a comprehensive DevSecOps practice. + +## API security maturity model + +Implementing comprehensive API security is a journey. Organizations typically progress through distinct maturity levels as they build more sophisticated security practices: + +```mermaid +graph TD + A[Level 0: Basic] --> B[Level 1: Structured] --> C[Level 2: Automated] --> D[Level 3: Proactive] + + A --> A1[Manual reviews
Basic HTTPS
Simple auth] + B --> B1[OpenAPI specs
Schema validation
Rate limiting] + C --> C1[Automated governance
CI/CD integration
Policy enforcement] + D --> D1[Threat modeling
Zero-trust architecture
Continuous monitoring] + + style A fill:#ffcdd2 + style B fill:#fff59d + style C fill:#c8e6c9 + style D fill:#a5d6a7 +``` + +*API security maturity progression showing the evolution from basic manual practices to proactive, automated security governance with comprehensive threat detection and prevention.* + +**Level 0 - Basic Security:** +- Manual code reviews for obvious security issues +- HTTPS enabled but not enforced through specifications +- Basic authentication (API keys or simple passwords) +- Ad-hoc security practices without consistent standards + +**Level 1 - Structured Security:** +- OpenAPI specifications document all APIs with security requirements +- Schema-based input validation prevents basic injection attacks +- Rate limiting implemented on authentication and sensitive endpoints +- Consistent security patterns across API teams + +**Level 2 - Automated Security:** +- Automated governance tools enforce security standards in CI/CD pipelines +- Security policies defined as code and validated automatically +- Breaking changes to security configurations fail builds +- Security metrics tracked and monitored systematically + +**Level 3 - Proactive Security:** +- Comprehensive threat modeling integrated into the design process +- Zero-trust architecture with mutual TLS for service-to-service communication +- Continuous security monitoring with behavioral analysis and anomaly detection +- Security feedback loops drive iterative improvements to governance policies + +Most organizations find that advancing one level at a time provides the most sustainable improvement path. The techniques covered in this guide primarily support progression from Level 0 to Level 2, with Level 3 requiring additional infrastructure and organizational maturity. + +## Frequently asked questions + +### What is design-first API security? +Design-first API security means defining security requirements in your OpenAPI specification before writing code, then using automated governance tools to enforce those requirements throughout the development lifecycle. This prevents vulnerabilities from reaching production rather than patching them after discovery. + +### How does OpenAPI prevent injection attacks? +OpenAPI specifications define precise data schemas with type validation, format constraints, and length limits. When enforced by governance tools, these schemas automatically reject malformed inputs that could contain injection payloads, stopping attacks before they reach your application logic. + +### Why is rate limiting important for API security? +Rate limiting prevents denial-of-service attacks, brute-force authentication attempts, and data scraping. It ensures fair resource usage among legitimate users while blocking malicious automation. Without rate limits, a single bad actor can overwhelm your API infrastructure. + +### Can I implement all four security areas with just OpenAPI? +Yes, OpenAPI 3.1 supports all four security areas: TLS enforcement through server URLs, input validation via JSON schemas, rate limiting through extensions like `x-rateLimit`, and access control via security schemes. Combined with governance automation, your specification becomes an executable security contract. + +### What's the difference between authentication and authorization in APIs? +Authentication verifies *who* the user is (like checking an ID card), while authorization determines *what* they can do (like checking permissions). Both are essential for API security, and OpenAPI provides security schemes to define and enforce both concepts through your specification. + +## Resources + +### Security standards and guidelines +- OWASP API Security Top 10 - Comprehensive vulnerability guide including injection attacks (API3:2023), resource consumption (API4:2023), and business logic abuse (API6:2023) +- NIST SP 800-52 Rev. 2 - Official guidelines for secure TLS implementation and configuration requirements +- IETF RFC 8446 - TLS 1.3 protocol specification and security requirements + +### Practical implementation tools +- Mozilla SSL Configuration Generator - Generate secure, up-to-date TLS configurations for various web servers and security levels +- OpenAPI Generator - Code generation tool for creating secure client SDKs and server stubs from OpenAPI specifications +- OpenAPI Specification - Official OpenAPI 3.2 specification including security scheme definitions + +### DevSecOps and API governance +- OWASP API Security Project - Community-driven API security best practices and threat modeling +- OpenAPI Security Schemes - Official specification for defining authentication and authorization in OpenAPI \ No newline at end of file diff --git a/learn/security/sidebars.yaml b/learn/security/sidebars.yaml new file mode 100644 index 00000000..c97575e2 --- /dev/null +++ b/learn/security/sidebars.yaml @@ -0,0 +1,5 @@ +- page: ./index.md +- page: ./api-tls-encryption-https-best-practices.md +- page: ./api-input-validation-injection-prevention.md +- page: ./api-rate-limiting-abuse-prevention.md +- page: ./authentication-authorization-openapi.md diff --git a/pages/learning-center/cards.ts b/pages/learning-center/cards.ts index 61ccb907..818b4989 100644 --- a/pages/learning-center/cards.ts +++ b/pages/learning-center/cards.ts @@ -95,22 +95,24 @@ export const cards = [ { title: 'Tools for API Testing in 2025', link: '/learn/testing/tools-for-api-testing-in-2025' }, ], }, - // { - // id: 7, - // key: 'api-security', - // title: 'API Security', - // description: - // 'Gain insights into securing your APIs with essential resources, tools, and best practices to protect your applications.', - // thumbnail: apiSecurityThumbnail, - // moreItems: ' more topics', - // landingPage: '/', - // items: [ - // { title: 'Introduction to API Security', link: '' }, - // { title: 'Common API Vulnerabilities', link: '' }, - // { title: 'Implementing Authentication and Authorization examples', link: '' }, - // { title: 'Best Practices for Securing APIs', link: '' }, - // ], - // }, + { + id: 6, + key: 'api-security', + title: 'API Security', + description: + 'Gain insights into securing your APIs with essential resources, tools, and best practices to protect your applications.', + thumbnail: apiSecurityThumbnail, + moreItems: '2 more topics', + landingPage: '/learn/security', + items: [ + { title: 'API Security by Design: Complete Guide', link: '/learn/security' }, + { title: 'API TLS Encryption and HTTPS Best Practices', link: '/learn/security/api-tls-encryption-https-best-practices' }, + { title: 'API Input Validation and Injection Prevention', link: '/learn/security/api-input-validation-injection-prevention' }, + { title: 'API Rate Limiting and Abuse Prevention', link: '/learn/security/api-rate-limiting-abuse-prevention' }, + { title: 'Authentication and Authorization with OpenAPI', link: '/learn/security/authentication-authorization-openapi' }, + { title: 'Automated Security Validation - Interactive Walkthrough', link: '/learn/security/automated-security-validation-walkthrough' }, + ], + }, // { // id: 8, // key: 'graphql',