Usar HTTPS para desenvolvimento local

Maud Nalpas

Na maioria das vezes, http://localhost se comporta como HTTPS para fins de desenvolvimento. No entanto, há alguns casos especiais, como nomes de host personalizados ou o uso de cookies seguros em navegadores, em que é necessário configurar explicitamente o site de desenvolvimento para se comportar como HTTPS e representar com precisão como o site funciona na produção. Se o site de produção não usar HTTPS, priorize a mudança para HTTPS.

Esta página explica como executar seu site localmente com HTTPS.

Observação: Nesta postagem, as declarações sobre localhost também são válidas para 127.0.0.1 e [::1], porque ambas descrevem o endereço do computador local (também chamado de endereço de loopback). Para simplificar, estas instruções não especificam números de porta. Portanto, quando você vir http://localhost, leia como http://localhost:{PORT} ou http://127.0.0.1:{PORT}.

Para instruções breves, consulte Referência rápida do mkcert.**

Executar seu site localmente com HTTPS usando o mkcert (recomendado)

Para usar o HTTPS com seu site de desenvolvimento local e acessar https://localhost ou https://mysite.example (nome de host personalizado), você precisa de um certificado TLS assinado por uma entidade confiável para seu dispositivo e navegador, chamada de autoridade certificadora (AC) confiável. O navegador verifica se o certificado do servidor de desenvolvimento está assinado por uma CA confiável antes de criar uma conexão HTTPS.

Recomendamos o uso do mkcert, uma CA multiplataforma, para criar e assinar seu certificado. Para outras opções úteis, consulte Executar seu site localmente com HTTPS: outras opções.

Muitos sistemas operacionais incluem bibliotecas para criar certificados, como openssl. No entanto, eles são mais complexos e menos confiáveis do que o mkcert e não são necessariamente multiplataforma, o que os torna menos acessíveis a equipes de desenvolvimento maiores.

Cuidado:

• Nunca exporte ou compartilhe o arquivo rootCA-key.pem que o mkcert cria automaticamente quando você executa mkcert -install. Um invasor que tiver acesso a esse arquivo poderá criar ataques no caminho para qualquer site que você visitar. Eles podem interceptar solicitações seguras da sua máquina para qualquer site: seu banco, prestador de cuidados de saúde ou redes sociais. Se você precisar saber onde rootCA-key.pem está localizado para garantir que ele esteja seguro, execute mkcert -CAROOT.
• Use o mkcert apenas para fins de desenvolvimento e, por extensão, nunca peça aos usuários finais para executar comandos do mkcert.
• Equipes de desenvolvimento: todos os membros da equipe precisam instalar e executar o mkcert separadamente (não armazenar e compartilhar a AC e o certificado).

Configuração

1. Instale o mkcert (apenas uma vez).

   Siga as instruções para instalar o mkcert no seu sistema operacional. Por exemplo, no macOS:

   brew install mkcert
   brew install nss # if you use Firefox
   

2. Adicione o mkcert às CAs raiz locais.

   No terminal, execute o seguinte comando:

   mkcert -install
   

   Isso gera uma autoridade certificadora (AC) local. A CA local gerada pelo mkcert só é confiável localmente, no seu dispositivo.

3. Gere um certificado para seu site, assinado pelo mkcert.

   No terminal, navegue até o diretório raiz do site ou qualquer diretório em que você queira manter o certificado.

   Depois, execute:

   mkcert localhost
   

   Se você estiver usando um nome de host personalizado, como mysite.example, execute:

   mkcert mysite.example
   

   Esse comando faz duas coisas:

   • Gera um certificado para o nome do host especificado.
   • Permite que o mkcert assine o certificado.

   Seu certificado agora está pronto e assinado por uma autoridade certificadora confiável para o navegador localmente.

4. Configure o servidor para usar o certificado HTTPS TLS que você acabou de criar.

   Os detalhes de como fazer isso dependem do seu servidor. Confira alguns exemplos:

   👩🏻‍💻 Com o nó:

   server.js (substitua {PATH/TO/CERTIFICATE...} e {PORT}):

   const https = require('https');
   const fs = require('fs');
   const options = {
     key: fs.readFileSync('{PATH/TO/CERTIFICATE-KEY-FILENAME}.pem'),
     cert: fs.readFileSync('{PATH/TO/CERTIFICATE-FILENAME}.pem'),
   };
   https
     .createServer(options, function (req, res) {
       // server code
     })
     .listen({PORT});
   

   👩🏻‍💻 Com o http-server:

   Inicie o servidor da seguinte maneira (substitua {PATH/TO/CERTIFICATE...}):

   http-server -S -C {PATH/TO/CERTIFICATE-FILENAME}.pem -K {PATH/TO/CERTIFICATE-KEY-FILENAME}.pem
   

   -S executa o servidor com HTTPS, enquanto -C define o certificado e -K define a chave.

   👩🏻‍💻 Com um servidor de desenvolvimento do React:

   Edite seu package.json da seguinte maneira e substitua {PATH/TO/CERTIFICATE...}:

   "scripts": {
   "start": "HTTPS=true SSL_CRT_FILE={PATH/TO/CERTIFICATE-FILENAME}.pem SSL_KEY_FILE={PATH/TO/CERTIFICATE-KEY-FILENAME}.pem react-scripts start"
   

   Por exemplo, se você criou um certificado para localhost no diretório raiz do site:

   |-- my-react-app
       |-- package.json
       |-- localhost.pem
       |-- localhost-key.pem
       |--...
   

   O script start vai ficar assim:

   "scripts": {
       "start": "HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem react-scripts start"
   

   👩🏻‍💻 Outros exemplos:

   • Servidor de desenvolvimento do Angular
   • Python

5. Abra https://localhost ou https://mysite.example no navegador para verificar se você está executando o site localmente com HTTPS. Você não vai receber avisos do navegador, porque ele confia no mkcert como uma autoridade de certificação local.

Referência rápida do mkcert

Referência rápida do mkcert

Para executar seu site de desenvolvimento local com HTTPS:

1. Configure o mkcert.

   Se ainda não fez isso, instale o mkcert, por exemplo, no macOS:

   brew install mkcert
   
   
   

   Confira as instruções de instalação do mkcert para Windows e Linux.

   Em seguida, crie uma autoridade certificadora local:

   mkcert -install

2. Crie um certificado confiável.

   mkcert {YOUR HOSTNAME e.g. localhost or mysite.example}

   Isso cria um certificado válido que o mkcert assina automaticamente.

3. Configure o servidor de desenvolvimento para usar HTTPS e o certificado que você criou na etapa 2.

Agora você pode acessar https://{YOUR HOSTNAME} no navegador, sem avisos.

Cuidado: faça isso apenas para fins de desenvolvimento e nunca exporte ou compartilhe o arquivo rootCA-key.pem. Se você precisar saber onde esse arquivo está localizado para garantir que ele esteja seguro, execute mkcert -CAROOT.

</div>

Executar seu site localmente com HTTPS: outras opções

Confira outras maneiras de configurar seu certificado. Elas geralmente são mais complicadas ou arriscadas do que usar o mkcert.

Certificado autoassinado

Você também pode decidir não usar uma autoridade certificadora local, como o mkcert, e assinar o certificado sozinho. Essa abordagem tem algumas desvantagens:

• Os navegadores não confiam em você como uma autoridade certificadora. Por isso, eles vão mostrar avisos que você precisa ignorar manualmente. No Chrome, você pode usar a flag #allow-insecure-localhost para ignorar esse aviso automaticamente no localhost.
• Isso não é seguro se você estiver trabalhando em uma rede não segura.
• Não é necessariamente mais fácil ou rápido do que usar uma CA local, como o mkcert.
• Os certificados autoassinados não se comportam exatamente da mesma maneira que os certificados confiáveis.
• Se você não estiver usando essa técnica em um contexto de navegador, será necessário desativar a verificação de certificado do servidor. Esquecer de reativá-la na produção causa problemas de segurança.

Os avisos que os navegadores mostram quando um certificado autoassinado é usado.

Se você não especificar um certificado, as opções HTTPS do servidor de desenvolvimento do React e do Vue vão criar um certificado autoassinado. Isso é rápido, mas vem com os mesmos avisos do navegador e outras desvantagens dos certificados autoassinados. Felizmente, você pode usar a opção HTTPS integrada dos frameworks de front-end e especificar um certificado confiável localmente criado usando o mkcert ou semelhante. Para mais informações, consulte o exemplo do mkcert com o React.

Por que os navegadores não confiam em certificados autoassinados?

Se você abrir o site em execução localmente no navegador usando HTTPS, o navegador vai verificar o certificado do servidor de desenvolvimento local. Quando ele vê que você assinou o certificado sozinho, vai verificar se você está registrado como uma autoridade certificadora confiável. Como você não está, o navegador não pode confiar no certificado e mostra um aviso informando que sua conexão não é segura. Ele ainda cria a conexão HTTPS se você continuar, mas isso é feito por sua conta e risco.

Por que os navegadores não confiam em certificados autoassinados.

Certificado assinado por uma autoridade certificadora normal

Você também pode usar um certificado assinado por uma CA oficial. Isso vem com as seguintes complicações:

• Você precisa fazer mais trabalho de configuração do que ao usar uma técnica de CA local, como o mkcert.
• É necessário usar um nome de domínio válido que você controla. Isso significa que você não pode usar CAs oficiais para o seguinte:
  • localhost e outros nomes de domínio reservados , como example ou test.
  • Qualquer nome de domínio que você não controla.
  • Domínios de nível superior inválidos. Para mais informações, consulte a lista de domínios de nível superior válidos.

Proxy reverso

Outra opção para acessar um site em execução localmente com HTTPS é usar um proxy reverso, como o ngrok. Isso vem com os seguintes riscos:

• Qualquer pessoa com quem você compartilhar o URL do proxy reverso poderá acessar seu site de desenvolvimento local. Isso pode ser útil para demonstrar seu projeto aos clientes, mas também pode permitir que pessoas não autorizadas compartilhem informações confidenciais.
• Alguns serviços de proxy reverso cobram pelo uso. Portanto, o preço pode ser um fator na sua escolha de serviço.
• Novas medidas de segurança nos navegadores podem afetar a maneira como essas ferramentas funcionam.

Flag (não recomendado)

Se você estiver usando um nome de host personalizado, como mysite.example, no Chrome, poderá usar uma flag para forçar o navegador a considerar mysite.example seguro. Evite fazer isso pelos seguintes motivos:

• Você precisa ter 100% de certeza de que mysite.example sempre será resolvido para um endereço local. Caso contrário, você corre o risco de vazar credenciais de produção.
• Essa flag só funciona no Chrome. Portanto, não é possível depurar em navegadores.

Agradecemos muito as contribuições e o feedback de todos os revisores e colaboradores, especialmente Ryan Sleevi, Filippo Valsorda, Milica Mihajlija e Rowan Merewood. 🙌

Imagem principal de fundo por @anandu no Unsplash, editada.