Cross-Origin Resource Sharing (CORS) Configuration

Control cross-origin access, security policies, and browser compatibility settings

Allowed Origins

Allowed Origins define which domains are permitted to make cross-origin requests to your IdentitySuite server. This is the primary security control for CORS and determines which client applications can access your authentication services.

Origin Configuration:

Exact Domain Matching: Origins must match exactly including protocol (https://), subdomain, and port number. For example, https://app.example.com is different from http://app.example.com or https://example.com.
Development vs Production: Include localhost origins for development (e.g., http://localhost:3000) but remove them in production environments for security.
Multiple Applications: Add each client application domain that needs to authenticate through IdentitySuite, including web apps, mobile app domains, and admin panels.

Security Best Practices:

  • • Never use wildcards (*) in production - specify exact domains
  • • Remove development origins (localhost) from production configurations
  • • Regularly audit and remove unused origins
  • • Use HTTPS origins whenever possible for secure communication

Common Configuration Examples:

• https://myapp.com - Production web application
• https://admin.myapp.com - Admin interface
• http://localhost:3000 - Development server (React/Angular)
• http://localhost:5173 - Vite development server

Allowed Headers

Allowed Headers specify which HTTP headers client applications can include in their cross-origin requests. These headers are essential for authentication, content negotiation, and custom application functionality.

Standard Headers for Authentication:

Authorization: Required for Bearer token authentication. Client applications need this to send JWT tokens in API requests.
Content-Type: Essential for POST requests with JSON payloads during login, registration, and token refresh operations.
Accept: Allows clients to specify preferred response formats (JSON, XML, etc.) for proper content negotiation.

Common Header Examples:

• Authorization - Bearer tokens and API keys
• Content-Type - application/json, application/x-www-form-urlencoded
• Accept - Response format preferences
• X-Requested-With - AJAX request identification
• X-Custom-Header - Application-specific headers
💡

Best Practice Guidelines:

  • • Include only headers that your applications actually use
  • • Standard headers (Authorization, Content-Type) are typically required
  • • Be cautious with custom headers - only add what's necessary
  • • Review headers periodically and remove unused ones

Exposed Headers

Exposed Headers determine which response headers from IdentitySuite can be accessed by client-side JavaScript. By default, browsers only expose standard headers to cross-origin requests, requiring explicit configuration for custom headers.

Headers Commonly Exposed:

Location: Useful for redirect responses and newly created resource URLs. Important for OAuth flows and registration confirmations.
X-Total-Count: Common for paginated API responses, allowing clients to display total record counts and implement proper pagination controls.
X-Rate-Limit-*: Rate limiting headers that help clients understand their API usage limits and implement proper throttling.

Default Exposed Headers (Always Available):

Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma

Implementation Notes:

  • • Only expose headers that client applications need to read
  • • Custom application headers typically require explicit exposure
  • • Security-sensitive headers should not be exposed unless necessary
  • • Consider the security implications of exposing internal system headers

Allowed Methods

Allowed Methods specify which HTTP methods can be used in cross-origin requests to IdentitySuite. These methods correspond to different authentication and user management operations.

Standard Methods for Authentication Systems:

GET: Retrieve user information, check authentication status, fetch public configuration, and access discovery endpoints.
POST: Essential for login, registration, token refresh, password reset, and most authentication operations that submit credentials or sensitive data.
PUT/PATCH: Update user profiles, change passwords, modify account settings. PATCH is preferred for partial updates, PUT for complete resource replacement.
DELETE: Account deletion, logout operations, and revoking tokens or sessions. Important for GDPR compliance and security operations.

Method Usage by Operation:

Authentication: POST (login), DELETE (logout)
Registration: POST (create account)
Profile Management: GET, PUT, PATCH
Token Operations: POST (refresh), DELETE (revoke)
Password Reset: POST (request), PUT (update)
Account Deletion: DELETE

Security Considerations:

  • • Only enable methods that your applications actually use
  • • DELETE method should be carefully considered for security implications
  • • GET requests should never modify data or authentication state
  • • Monitor for unusual method usage that might indicate attacks

Credentials and Preflight Settings

These settings control advanced CORS behavior including credential handling and preflight request optimization. Proper configuration is crucial for security and performance in authentication scenarios.

DisallowCredentials Setting:

When Disabled (Off): Cookies, authorization headers, and TLS client certificates can be included in cross-origin requests. This is typically required for authentication systems that use session cookies or require credential headers.
When Enabled (On): Blocks credentials from being sent in cross-origin requests. Use this only if your authentication system is purely stateless and doesn't require cookies or credential headers.
Security Impact: Enabling this setting prevents credential-based attacks but may break authentication flows that depend on cookies or authorization headers.

PreflightMaxAge (600 seconds):

Purpose: Specifies how long browsers can cache preflight request results. This reduces network overhead by avoiding repeated preflight requests for the same cross-origin operations.
Default Value (600): 10 minutes is a balanced setting that reduces network traffic while allowing reasonable flexibility for configuration changes.
Optimization: Higher values improve performance but delay the effect of CORS configuration changes. Lower values increase responsiveness but generate more preflight requests.
💡

Recommended Settings:

  • • Authentication Systems: Keep DisallowCredentials OFF to support tokens and cookies
  • • Development: Use lower PreflightMaxAge (300s) for faster configuration testing
  • • Production: Higher PreflightMaxAge (3600s) for better performance
  • • High-Security: Consider enabling DisallowCredentials only if using purely stateless authentication

Common Configuration Scenarios:

SPA + API:
DisallowCredentials OFF, PreflightMaxAge 3600 (supports JWT in headers)
Session-based:
DisallowCredentials OFF, PreflightMaxAge 1800 (supports authentication cookies)
Public API:
DisallowCredentials ON, PreflightMaxAge 7200 (no credentials needed)