Capítulo 6.2: Configurações CORS

Tempo de estudo: 30 minutos

---

1. CORS: O que é e para que serve?

Como descobrimos, CORS (Cross-Origin Resource Sharing) — é uma política de segurança do navegador. Ela previne situações em que um site malicioso evil-site.com, em seu nome (usando seus cookies), faz requisições para your-bank.com e rouba dados.

Como funciona?

1. O Frontend (navegador) do domínio A quer obter dados do domínio B.
2. O navegador envia para o domínio B uma requisição "prévia" especial (preflight request) com o método OPTIONS, perguntando: "Ei, domínio B, posso eu, domínio A, fazer uma requisição GET para você?"
3. O Backend (servidor no domínio B) deve responder com cabeçalhos HTTP especiais, por exemplo: Access-Control-Allow-Origin: A.
4. Se a resposta do servidor permitir a requisição, o navegador envia a requisição GET principal. Caso contrário, ele a bloqueia e exibe um erro CORS.

💡 Analogia espacial:

Antes de teletransportar o capitão para uma estação alienígena (enviar uma requisição POST), a nave (navegador) envia um drone (requisição OPTIONS) com a pergunta: "Estação, vocês aceitam teletransporte da nave 'Enterprise'?". A estação (API) responde: "Sim, a recepção da 'Enterprise' é permitida" (cabeçalho Access-Control-Allow-Origin). Somente depois disso o teletransporte começa.

---

2. Configuração CORS no Laravel (Abordagem moderna para Laravel 11+)

No Laravel 11+, a configuração CORS tornou-se significativamente mais simples e não exige a publicação do arquivo config/cors.php, se você precisar de configurações básicas. Tudo é gerenciado através do arquivo .env e bootstrap/app.php.

Passo 1: Configuração via variáveis de ambiente

Abra seu arquivo .env. O Laravel já fornece variáveis padrão para gerenciar o CORS para a API.

# .env

# ... outras variáveis

# Especifique os caminhos para os quais o CORS será aplicado.
# 'api/*' - valor padrão para todas as rotas de API.
CORS_PATHS=api/*

# Especifique as origens (domínios) permitidas.
# Para desenvolvimento, especifique o endereço do seu frontend.
# Podem ser listados separados por vírgulas, sem espaços.
CORS_ALLOWED_ORIGINS=http://localhost:5500,http://127.0.0.1:5500

# Outras configurações (geralmente podem ser deixadas como padrão)
CORS_ALLOWED_METHODS=*
CORS_ALLOWED_HEADERS=*
CORS_EXPOSED_HEADERS=
CORS_MAX_AGE=0
CORS_SUPPORTS_CREDENTIALS=false

Variáveis chave:

• CORS_ALLOWED_ORIGINS: A variável mais importante. Aqui você lista os domínios dos quais as requisições são permitidas. * permite a todos, mas isso é

extremamente inseguro para produção.

• CORS_PATHS: Caminhos aos quais estas regras se aplicam. api/* significa tudo que começa com /api/.

Após alterar o .env não é necessário reiniciar o servidor, se você estiver usando php artisan serve. As alterações serão carregadas automaticamente.

Passo 2 (Opcional): Configuração avançada em bootstrap/app.php

Se você precisar de uma lógica mais complexa (por exemplo, permitir subdomínios usando padrões), ainda precisará publicar o arquivo de configuração e configurar o middleware. Mas para 95% dos casos, o arquivo .env é suficiente.

O comando php artisan install:api configura automaticamente o middleware CORS básico para rotas de API no arquivo bootstrap/app.php. Fica assim:

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    // Esta linha já será adicionada pelo comando install:api
    // Ela inclui o tratamento CORS para todas as rotas de API
    $middleware->api(base_path('routes/api.php'));
})

Dentro de ->api(), o Laravel já utiliza o middleware HandleCors, que lê as configurações do seu .env. É simples e funciona "out of the box".

⚠️ Importante! Não use CORS_ALLOWED_ORIGINS='*' em um servidor de produção, se sua API não for totalmente pública. Isso abre uma potencial vulnerabilidade. Sempre liste os domínios específicos do seu frontend.

---

3. Configuração CORS no FastAPI

FastAPI usa o conceito de Middleware (software intermediário) para lidar com tarefas transversais como CORS.

Passo 1: Abra o arquivo principal da sua aplicação

Este é o arquivo onde você cria uma instância do FastAPI (geralmente main.py).

Passo 2: Adicione CORSMiddleware

FastAPI fornece um middleware pronto para configurar o CORS.

# main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware # 1. Importa o middleware

app = FastAPI(
    title="SpaceAPI",
    description="API para gerenciar planetas na galáxia",
    version="1.0.0"
)

# 2. Lista de origens permitidas
origins = [
    "http://localhost:5500",
    "http://127.0.0.1:5500",
    # Em produção, aqui estará o domínio do seu frontend
    # "https://my-awesome-app.com",
]

# 3. Adiciona o middleware à aplicação
app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,  # Permite as origens especificadas
    allow_credentials=True, # Permite cookies (necessário para autenticação)
    allow_methods=["*"],    # Permite todos os métodos (GET, POST, etc.)
    allow_headers=["*"],    # Permite todos os cabeçalhos
)

# ... aqui seus roteadores e o restante do código

Passo 3: Reinicie o servidor Uvicorn O servidor Uvicorn geralmente recarrega automaticamente quando o código é alterado. Se não, reinicie-o manualmente. Agora, seu servidor FastAPI responderá corretamente às requisições OPTIONS do frontend.

---

Quiz para fixação

1. A requisição que o navegador envia antes da principal para verificar o CORS é chamada de:

a) CHECK request b) Preflight request c) Handshake request

2. No Laravel moderno (11+), as configurações básicas de CORS são definidas principalmente em:

a) Arquivo bootstrap/app.php b) Arquivo .env c) Arquivo routes/api.php

3. No FastAPI, para configurar o CORS, utiliza-se:

a) O decorador @app.cors() b) A classe Security embutida c) O Middleware

4. Qual valor para CORS_ALLOWED_ORIGINS é o mais seguro para produção?

a) CORS_ALLOWED_ORIGINS='*' b) CORS_ALLOWED_ORIGINS=http://my-frontend.com,https://my-frontend.com` c) Não definir esta variável

Verificar

---

🚀 Resumo do Capítulo:

Você se tornou um "diplomata de comunicações interestelares"! Suas APIs agora podem interagir com segurança com aplicativos externos, utilizando abordagens modernas e corretas. - ✅ Entendemos o mecanismo de funcionamento do CORS e das solicitações preflight. - 🔧 Configuramos o CORS para Laravel 11+ através do arquivo .env. - ⚙️ Configuramos o CORS para FastAPI usando CORSMiddleware. - 🛰️ Estabelecemos com sucesso a comunicação entre o frontend e o backend.

A ponte de comunicação está construída e protegida. Agora podemos pensar em como permitir a passagem nesta ponte apenas de "pessoal autorizado".

📌 Verificação:

• O principal critério de sucesso é a ausência de erros CORS no console do navegador ao solicitar dados do frontend.
• Na aba "Network" (Rede) nas ferramentas do desenvolvedor, você pode ver duas solicitações para sua API: a primeira com o método OPTIONS (status 200/204) e a segunda com o método GET (status 200). Esta é uma demonstração clara do funcionamento do CORS.