Configurando CORS (Compartilhamento de Recursos entre Origens Diferentes) em seu site no ServBay

No desenvolvimento web moderno, aplicações front-end (normalmente executadas sob um domínio) frequentemente precisam acessar APIs backend ou outros serviços (que podem rodar em diferentes domínios ou portas). Por padrão, a política de mesma origem dos navegadores bloqueia essas requisições cross-origin por motivos de segurança. O mecanismo conhecido como CORS (Compartilhamento de Recursos entre Origens Diferentes) permite ao servidor declarar quais origens podem acessar seus recursos, viabilizando interações seguras entre domínios distintos.

Este artigo orienta você a configurar e ativar o CORS para seu site no ambiente local de desenvolvimento web do ServBay, de forma simples por meio da interface gráfica do ServBay.

O que é CORS?

CORS (Cross-Origin Resource Sharing/Compartilhamento de Recursos entre Origens Diferentes) é um mecanismo baseado em cabeçalhos HTTP que permite ao servidor indicar quais origens (domínios, protocolos ou portas) diferentes da sua própria podem carregar recursos. Quando uma página web tenta requisitar recursos de uma origem diferente da sua, o navegador executa uma "requisição HTTP cross-origin". Segundo a política de mesma origem, tais requisições normalmente são bloqueadas por padrão. O CORS fornece a comunicação entre servidor e navegador para decidir se a requisição cross-origin será permitida.

Por que o desenvolvedor precisa configurar o CORS?

Ao construir uma aplicação com front-end e back-end separados (por exemplo, front-end em app.servbay.demo e API em api.servbay.demo) ou quando o seu front-end precisa chamar APIs de terceiros, o navegador irá bloquear essas requisições por política de mesma origem. Configurar o CORS informa ao navegador que o servidor permite que as requisições originadas do seu front-end acessem esses recursos, resolvendo assim falhas de acesso causadas pela política de mesma origem.

Entendendo os principais cabeçalhos de resposta HTTP do CORS

Quando um servidor responde a uma requisição cross-origin, inclui alguns cabeçalhos HTTP específicos Access-Control-*. O navegador cliente recebe esses cabeçalhos e decide, a partir dos valores fornecidos, se permitirá ou não a requisição. Veja a seguir os principais parâmetros do CORS que podem ser configurados via ServBay (cada um corresponde a um desses cabeçalhos HTTP):

1. Access-Control-Allow-Origin

   • Função: Este é o cabeçalho mais importante do CORS, especifica quais origens (um ou mais domínios) podem acessar o recurso.
   • Valores possíveis:
     • *: Permite requisições de qualquer origem. Atenção: Apesar de prático, não é recomendado em produção pois expõe o recurso a qualquer website, trazendo riscos de segurança.
     • https://servbay.demo: Permite somente a requisições vindas desta origem específica.
     • https://servbay.demo https://api.servbay.demo: Permite de múltiplas origens determinadas, separadas por espaço.
   • Observação: Se a requisição cross-origin precisa transmitir Cookie ou informações de autenticação (com Access-Control-Allow-Credentials: true), então Access-Control-Allow-Origin NÃO PODE estar em * — deve ser especificada a origem exata.

2. Access-Control-Allow-Methods

   • Função: Especifica quais métodos HTTP são permitidos em requisições cross-origin (GET, POST, PUT, DELETE, OPTIONS, etc).
   • Valores possíveis: Exemplo: GET, POST, PUT, DELETE, OPTIONS. Separe múltiplos métodos com vírgulas.
   • Observação: Para "requisições não simples" (como aquelas usando PUT/DELETE ou cabeçalhos personalizados), o navegador envia previamente um "Preflight Request" usando o método OPTIONS. O servidor deve responder a essa preflight request incluindo Access-Control-Allow-Methods no cabeçalho de resposta para informar os métodos permitidos. Por isso, incluir OPTIONS na configuração é geralmente essencial.

3. Access-Control-Allow-Headers

   • Função: Indica quais cabeçalhos HTTP personalizados podem ser enviados em requisições cross-origin.
   • Valores possíveis: Exemplo: Content-Type, Authorization, X-Requested-With. Separe por vírgulas.
   • Observação: Quando seu front-end utiliza cabeçalhos fora dos "simples" (Accept, Accept-Language, Content-Language, Content-Type quando for application/x-www-form-urlencoded, multipart/form-data ou text/plain), haverá preflight e você precisará listar explicitamente aqui todos os cabeçalhos permitidos.

4. Access-Control-Allow-Credentials

   • Função: Indica se requisições cross-origin podem incluir credenciais como Cookie, certificados SSL do cliente ou autenticação HTTP.
   • Valores possíveis: true ou false.
   • Observação: Quando ativado (true), como dito acima, o valor de Access-Control-Allow-Origin NÃO pode ser *. O código cliente (JavaScript) deve também configurar a opção de envio de credenciais (ex: xhr.withCredentials = true ou fetch(url, { credentials: 'include' })).

Como habilitar e configurar o CORS no ServBay

O ServBay oferece uma interface gráfica intuitiva para configurar CORS de forma independente em cada site. Siga os passos abaixo:

1. Abra o ServBay e acesse a lista de sites: Inicie o aplicativo ServBay. No menu lateral esquerdo da interface principal, clique em "Sites". Você verá uma lista dos sites locais já cadastrados no ServBay.

2. Selecione o site em que deseja configurar o CORS: Na lista, localize o site no qual deseja ativar e configurar o CORS. Clique no nome do site para acessar sua tela de configuração.

3. Encontre e ative a opção de CORS: Na área central da página de configuração, role para baixo até a seção "CORS". Por padrão, o CORS está desativado no ServBay. Clique no botão deslizante ao lado desta seção para alternar de "Off" para "On". Com o CORS ativado, as opções de configuração ficarão disponíveis para edição.

4. Configure o Access-Control-Allow-Origin: No campo "Access-Control-Allow-Origin", insira uma ou mais origens (URLs) autorizadas a acessar o recurso do site. Para múltiplas origens, separe com espaço. Exemplo: https://frontend.servbay.demo https://anotherapp.servbay.demo. Evite usar o * em ambientes de produção.

5. Configure o Access-Control-Allow-Methods: No campo "Access-Control-Allow-Methods", insira uma lista dos métodos HTTP permitidos, separados por vírgulas. Exemplo: GET, POST, PUT, DELETE, OPTIONS. Certifique-se de incluir todos os métodos realmente necessários pela sua aplicação, e normalmente inclua OPTIONS para suportar requisições preflight.

6. Configure o Access-Control-Allow-Headers: No campo "Access-Control-Allow-Headers", insira uma lista dos cabeçalhos HTTP personalizados permitidos, separados por vírgulas. Exemplo: Content-Type, Authorization, X-Custom-Header. Inclua apenas os cabeçalhos personalizados realmente utilizados pela sua aplicação.

7. Configure o Access-Control-Allow-Credentials (opcional): Para permitir o envio de Cookie ou autenticação, ative o botão ao lado de "Allow-Credentials". Reforçando: Com esta opção ativada, o campo Access-Control-Allow-Origin (passo 4) NÃO PODE ser *.

8. Salve as configurações: Após configurar todas as opções necessárias do CORS, clique no botão "Salvar" no canto inferior direito da página para aplicar as mudanças. O ServBay irá atualizar automaticamente a configuração do servidor web (Caddy ou Nginx), sem necessidade de reiniciar serviços manualmente.

Exemplo de configuração

A imagem abaixo mostra um exemplo de configuração de CORS para o site “ServBay Demo Website” no ServBay:

Com esta configuração:

• Access-Control-Allow-Origin: https://frontend.servbay.demo https://api.servbay.demo
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization
• Allow-Credentials: habilitado (true)

Isso significa que apenas requisições vindas de https://frontend.servbay.demo e https://api.servbay.demo poderão acessar os recursos do “ServBay Demo Website”. Estas requisições podem utilizar os métodos GET, POST, PUT, DELETE e OPTIONS, enviar os cabeçalhos Content-Type e Authorization, e também transmitir credenciais como Cookie.

Observações e melhores práticas

• Priorize segurança: Utilizar Access-Control-Allow-Origin: * em ambientes de desenvolvimento e testes é rápido, mas em produção limite sempre às origens estritamente necessárias para a aplicação.
• Preflight Requests: Compreender o funcionamento das preflight requests (OPTIONS) é fundamental para resolver problemas de CORS. Certifique-se de que o servidor (via configuração do ServBay) responda com os cabeçalhos necessários.
• Cache do navegador: O navegador pode armazenar em cache as respostas CORS. Se enfrentar problemas após modificar a configuração no ServBay, limpe o cache do navegador ou utilize o modo anônimo para testar.
• CORS na aplicação: Alguns frameworks ou bibliotecas web (Laravel, Express.js, Spring Boot, etc.) também permitem configuração de CORS em nível de aplicação. A configuração feita pelo ServBay é aplicada no servidor web (Caddy/Nginx) e costuma prevalecer. Em cenários complexos, verifique e coordene as regras de ambos.
• Ferramentas de depuração: Acompanhe as requisições e respostas HTTP pelo painel de Rede das ferramentas do desenvolvedor do navegador (geralmente abertas com F12). Isso ajuda a identificar se o CORS está configurado corretamente e localizar o motivo de eventuais falhas.

Perguntas Frequentes (FAQ)

P: Configurei o CORS seguindo os passos, mas as requisições ainda falham. O que posso verificar?

R: Siga esta lista de verificação:

1. Inspecione o console e a aba de rede do navegador: Mensagens de erro relacionadas a CORS e cabeçalhos das requisições aparecem aqui. Verifique se a resposta inclui corretamente Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers e se os valores correspondem às requisições realizadas pelo seu front-end.
2. Confirme a origem exata: Certifique-se de que o valor em Access-Control-Allow-Origin (incluindo protocolo, domínio e porta) corresponde exatamente à origem do front-end.
3. Verifique métodos e cabeçalhos: Confirme que Access-Control-Allow-Methods inclua o método HTTP usado, assim como Access-Control-Allow-Headers todos os cabeçalhos personalizados utilizados.
4. Problemas com credenciais: Se estiver enviando Cookie ou outras credenciais, garanta que Allow-Credentials esteja ativado no ServBay e que Access-Control-Allow-Origin não esteja em *. O código do cliente deve também estar configurado para enviar credenciais (withCredentials = true).
5. Requisições preflight: Para requisições não simples, analise se o navegador enviou a preflight request OPTIONS e se a resposta traz os cabeçalhos CORS corretos.
6. Salvamento na configuração do ServBay: Após qualquer ajuste, lembre-se sempre de clicar em "Salvar".

P: É possível definir uma política global de CORS para todos os sites?

R: No ServBay, a configuração de CORS é feita individualmente em cada site, proporcionando mais flexibilidade e segurança. Atualmente, a interface do ServBay não permite definir uma regra global. Portanto, se precise de configurações similares em diversos sites, repita o processo em cada um deles.

P: Como o ServBay implementa a configuração do CORS?

R: Internamente, o ServBay utiliza o Caddy ou Nginx como servidor web. As opções de CORS que você configura na interface do ServBay são automaticamente convertidas em instruções correspondentes do Caddyfile ou do arquivo de configuração do Nginx. O ServBay gerencia estes arquivos e garante o reload automático dos servidores — não é necessário editar arquivos manualmente.

Resumo

Com a interface gráfica do ServBay, é fácil habilitar e configurar o CORS em sites do seu ambiente local de desenvolvimento, solucionando eficazmente problemas de acesso entre domínios. Entender e configurar corretamente cabeçalhos como Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers e Access-Control-Allow-Credentials é fundamental para um fluxo de desenvolvimento web seguro e fluido. Siga este guia e as boas práticas aqui apresentadas para maximizar a eficiência do seu desenvolvimento local.