CORS configuration in Supabase - Deep Dive

Overview - CORS configuration

What is it?

CORS configuration is a way to control which websites can talk to your Supabase backend. It sets rules that tell browsers if a web page from one site can access resources from another site. This helps keep your data safe by only allowing trusted websites to connect. Without CORS, any website could try to use your backend, which can cause security problems.

Why it matters

Without CORS, your backend could be accessed by any website, including harmful ones. This could lead to data leaks, unauthorized actions, or misuse of your services. CORS protects your backend by making sure only allowed websites can send requests. This keeps your users' data safe and your service reliable.

Where it fits

Before learning CORS configuration, you should understand how web browsers and servers communicate, especially HTTP requests and responses. After mastering CORS, you can explore advanced security topics like authentication, authorization, and API gateway rules.

Mental Model

Core Idea

CORS configuration is a gatekeeper that tells browsers which websites are allowed to access your backend resources.

Think of it like...

Imagine your backend is a private club. CORS is the bouncer who checks the guest list and only lets in people from approved websites.

┌───────────────┐       ┌───────────────┐
│  Browser on   │       │   Supabase    │
│  Website A    │──────▶│   Backend     │
│ (Allowed)     │       │ (Checks CORS) │
└───────────────┘       └───────────────┘
         │                      ▲
         │                      │
         │                      │
         ▼                      │
┌───────────────┐              │
│  Browser on   │              │
│  Website B    │──────────────┘
│ (Blocked)     │

Build-Up - 6 Steps

1

Foundation

What is CORS and Why It Exists

Concept: Introduce the basic idea of CORS and why browsers enforce it.

Web browsers have a security rule called Same-Origin Policy. It stops a web page from one site from reading data from another site. CORS (Cross-Origin Resource Sharing) is a way to relax this rule safely. It lets servers say which other sites can access their data.

Result

You understand that CORS is a security feature that controls cross-site data access.

Understanding the browser's security limits explains why CORS is necessary to allow safe sharing.

2

Foundation

How CORS Works in Browser Requests

Concept: Explain the role of HTTP headers in CORS communication.

When a browser sends a request to a different site, it adds an Origin header showing where the request comes from. The server replies with Access-Control-Allow-Origin header listing allowed sites. If the origin is allowed, the browser lets the web page access the response. Otherwise, it blocks it.

Result

You see how browsers and servers talk using headers to enforce CORS rules.

Knowing the headers involved helps you understand how CORS decisions are made.

3

Intermediate

Configuring CORS in Supabase Settings

🤔Before reading on: Do you think Supabase allows setting multiple allowed origins or just one? Commit to your answer.

Concept: Learn how to set allowed origins in Supabase to control access.

Supabase lets you specify a list of allowed origins in its project settings under API configuration. You enter URLs of websites that can access your backend. Wildcards are not supported for security reasons. Only requests from these URLs will be accepted by Supabase.

Result

You can control which websites can use your Supabase backend by listing their URLs.

Understanding Supabase's strict origin list prevents accidental exposure to unwanted sites.

4

Intermediate

Handling Preflight Requests in CORS

🤔Before reading on: Do you think all cross-origin requests trigger a preflight OPTIONS request? Commit to your answer.

Concept: Explain the special OPTIONS request browsers send before some cross-origin requests.

For some requests like POST with JSON, browsers send a preflight OPTIONS request to check if the server allows it. Supabase responds to these automatically if the origin is allowed. This step ensures the actual request is safe to send.

Result

You understand why browsers sometimes send extra requests and how Supabase handles them.

Knowing about preflight requests helps you debug CORS errors that happen before your main request.

5

Advanced

Security Risks of Misconfigured CORS

🤔Before reading on: Is it safe to set Access-Control-Allow-Origin to '*' in Supabase? Commit to your answer.

Concept: Explore what happens if CORS is too open or misconfigured.

If you allow all origins with '*', any website can access your backend, risking data leaks or abuse. Supabase does not allow '*' for this reason. You must list trusted sites explicitly. Also, allowing origins with user input can lead to security holes.

Result

You see why strict CORS settings protect your backend from attacks.

Understanding the dangers of open CORS helps you avoid common security mistakes.

6

Expert

CORS and Authentication Tokens Interaction

🤔Before reading on: Do you think CORS settings alone protect your authentication tokens from being stolen? Commit to your answer.

Concept: Discuss how CORS works with cookies and tokens in Supabase authentication.

CORS controls which sites can make requests, but it does not encrypt or protect tokens themselves. If your frontend sends tokens like JWT or cookies, CORS ensures only allowed sites can send requests with them. However, you must also use HTTPS and secure token storage to fully protect user data.

Result

You understand that CORS is one layer of security and must be combined with other practices.

Knowing CORS's limits in token security prevents overreliance and encourages comprehensive protection.

Under the Hood

Browsers enforce CORS by checking the Origin header in requests and comparing it to the Access-Control-Allow-Origin header in responses. If the origin is not allowed, the browser blocks the response from reaching the web page's code. Supabase's backend inspects incoming requests' origins and includes the appropriate headers in responses to signal permission. For complex requests, browsers send a preflight OPTIONS request to confirm permissions before the actual request.

Why designed this way?

CORS was designed to balance security and flexibility. Browsers needed a way to prevent malicious websites from stealing data from other sites while still allowing legitimate cross-site interactions like APIs and CDNs. The header-based approach is simple, standardized, and works with existing HTTP infrastructure. Supabase enforces strict origin lists to avoid risks from wildcard permissions, reflecting modern security best practices.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Browser sends │──────▶│ Supabase      │──────▶│ Browser checks │
│ request with  │       │ backend checks│       │ Access-Control│
│ Origin header │       │ Origin header │       │ -Allow-Origin │
└───────────────┘       └───────────────┘       └───────────────┘
         │                      │                      │
         │                      │                      │
         │                      │                      ▼
         │                      │               ┌───────────────┐
         │                      │               │ Allow or block│
         │                      │               │ response to   │
         │                      │               │ web page      │
         │                      │               └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does setting Access-Control-Allow-Origin to '*' mean your backend is fully open and safe? Commit yes or no.

Common Belief: Setting Access-Control-Allow-Origin to '*' is safe and lets anyone use your API without risk.

Reality: Using '*' allows any website to access your backend, which can expose sensitive data or allow misuse. Supabase disallows this for security.

Why it matters: Believing this can lead to accidental data leaks and unauthorized access, harming users and your service.

Quick: Do you think CORS settings alone prevent all unauthorized access to your backend? Commit yes or no.

Common Belief: If CORS blocks a request, the backend is fully protected from unauthorized users.

Reality: CORS only controls browser-based cross-origin requests. Other clients like curl or Postman can bypass CORS. Backend authentication is still needed.

Why it matters: Relying only on CORS leaves your backend vulnerable to direct attacks or misuse.

Quick: Do you think all cross-origin requests trigger a preflight OPTIONS request? Commit yes or no.

Common Belief: Every cross-origin request sends a preflight OPTIONS request first.

Reality: Only some requests with special methods or headers trigger preflight. Simple GET requests usually do not.

Why it matters: Misunderstanding this can cause confusion when debugging CORS errors.

Quick: Can you use wildcards like '*.example.com' in Supabase CORS settings? Commit yes or no.

Common Belief: You can use wildcards in Supabase CORS to allow many subdomains easily.

Reality: Supabase requires exact origins; wildcards are not supported to avoid security risks.

Why it matters: Trying to use wildcards leads to failed requests and security gaps.

Expert Zone

1

Supabase's CORS checks happen before authentication, so misconfigured origins can block legitimate users even if they have valid tokens.

2

CORS headers are sent per response, so dynamic origin checking in backend code can allow flexible but secure access control.

3

Preflight requests do not carry authentication tokens, so backend must allow OPTIONS requests without strict auth to enable CORS.

When NOT to use

CORS configuration is not a substitute for backend authentication and authorization. For non-browser clients or internal services, use network-level controls like VPNs or API gateways. Also, if you need to allow many dynamic origins, consider token-based authentication instead of broad CORS rules.

Production Patterns

In production, teams list only their frontend URLs in Supabase CORS settings. They combine this with JWT authentication and HTTPS. For multi-environment setups, each environment (dev, staging, prod) has its own allowed origins. Monitoring CORS errors helps detect misconfigurations or malicious access attempts.

Connections

HTTP Headers

CORS uses specific HTTP headers to communicate permissions between browsers and servers.

Understanding HTTP headers deeply helps grasp how CORS controls cross-site requests and how to debug related issues.

Web Security Policies

CORS is part of a broader set of browser security policies like Content Security Policy (CSP).

Knowing CORS in context with other policies helps design layered defenses for web applications.

Access Control in Physical Security

CORS is like physical access control systems that check IDs before allowing entry.

Recognizing CORS as an access control mechanism clarifies its role in protecting resources from unauthorized access.

Common Pitfalls

#1 Allowing all origins with '*' in Supabase CORS settings.

Wrong approach:

Access-Control-Allow-Origin: *

Correct approach:

Access-Control-Allow-Origin: https://your-allowed-website.com

Root cause:

Misunderstanding that '*' is insecure and not supported by Supabase leads to exposing backend to all websites.

#2 Not including the correct frontend URL in the allowed origins list.

Wrong approach:

Allowed origins: https://wrong-url.com

Correct approach:

Allowed origins: https://your-frontend-url.com

Root cause:

Confusing URLs or forgetting to update origins after deployment causes legitimate requests to be blocked.

#3 Expecting CORS to protect backend from all unauthorized access.

Wrong approach:

Relying only on CORS without authentication or authorization.

Correct approach:

Implement backend authentication and authorization alongside CORS.

Root cause:

Believing CORS is a security barrier rather than a browser-enforced policy leads to incomplete protection.

Key Takeaways

CORS configuration controls which websites can access your Supabase backend by setting allowed origins.

Browsers enforce CORS using HTTP headers to protect users from malicious cross-site requests.

Supabase requires explicit origin URLs and does not support wildcards to maintain strong security.

CORS is one layer of security and must be combined with authentication and secure token handling.

Misconfiguring CORS can lead to blocked legitimate requests or dangerous data exposure.