Usar HTTPS para desenvolvimento local

Maud Nalpas

Na maioria das vezes, o http://localhost se comporta como HTTPS para fins de desenvolvimento. No entanto, há alguns casos especiais, como nomes de host personalizados ou uso de cookies seguros em todos os navegadores, em que você precisa configurar explicitamente seu site de desenvolvimento para se comportar como HTTPS e representar com precisão como seu site funciona na produção. Se o site de produção não usa HTTPS, defina como prioridade a mudança para HTTPS.

Nesta página, explicamos como executar seu site localmente com HTTPS.

Observação: nesta postagem, as instruçõ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. Então, quando aparecer http://localhost, leia como http://localhost:{PORT} ou http://127.0.0.1:{PORT}.

Para instruções, consulte a referência rápida do mkcert (em inglês).**

Executar seu site localmente com HTTPS usando mkcert (recomendado)

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

Recomendamos usar mkcert, uma AC 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 criação de certificados, como openssl (link em inglês). 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 para equipes de desenvolvedores maiores.

Atenção:

• Nunca exporte ou compartilhe o arquivo rootCA-key.pem criado automaticamente pelo mkcert ao executar mkcert -install. Um invasor se apropriar desse arquivo pode criar ataques no caminho para qualquer site que você estiver visitando. Eles podem interceptar solicitações seguras da sua máquina para qualquer site, como um banco, um prestador de cuidados de saúde ou redes sociais. Se você precisar saber onde rootCA-key.pem está localizado para ter certeza de que ele é seguro, execute mkcert -CAROOT.
• Use o mkcert apenas para fins de desenvolvimento e, por extensão, nunca peça para os usuários finais executarem comandos do mkcert.
• Equipes de desenvolvimento: todos os membros da equipe devem instalar e executar o mkcert separadamente (e não armazenar e compartilhar a CA e o certificado).

Instalação

1. Instale o mkcert (apenas uma vez).

   Siga as instructions (em inglês) 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 arquivo mkcert às CAs raiz locais.

   No terminal, execute o seguinte comando:

   mkcert -install
   

   Isso gera uma autoridade de certificação (CA) local. A CA local gerada pelo mkcert é confiável apenas localmente no seu dispositivo.

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

   No seu terminal, navegue até o diretório raiz do site ou qualquer diretório em que você quer 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 em que seu navegador confia localmente.

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

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

   👩🏻 {0} Com 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});
   

   👩🏻 target Com http-server:

   Inicie o servidor desta forma (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.

   👩🏻 {0} Com um servidor de desenvolvimento React:

   Edite seu package.json da seguinte maneira, substituindo {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 ficará assim:

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

   👩🏻 {0}Outros exemplos:

   • Servidor de desenvolvimento do Angular
   • Python

5. Abra https://localhost ou https://mysite.example no navegador para verificar se o site está sendo executado localmente com HTTPS. Você não verá nenhum aviso do navegador porque ele confia no mkcert como uma autoridade de certificação local.

Referência rápida de mkcert

Referência rápida de mkcert

Para executar seu site de desenvolvimento local com HTTPS:

1. Configure o arquivo mkcert.

   Instale o mkcert, por exemplo, no macOS, caso ainda não tenha feito isso:

   brew install mkcert
   
   
   

   Consulte install mkcert para instruções para Windows e Linux.

   Em seguida, crie uma autoridade de certificação 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 criado na Etapa 2.

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

Atenção : 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 ter certeza de que ele é seguro, execute mkcert -CAROOT.

</div>

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

Veja a seguir outras maneiras de configurar seu certificado. Geralmente, eles são mais complicados ou mais arriscados do que usar o mkcert.

Certificado autoassinado

Também é possível decidir não usar uma autoridade de certificação local, como o mkcert, e assinar seu certificado. Essa abordagem tem algumas armadilhas:

• Os navegadores não confiam em você como uma autoridade de certificação, 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 em localhost.
• Isso não é seguro se você estiver trabalhando em uma rede sem segurança.
• Não é necessariamente mais fácil ou mais rápido do que usar uma AC local, como mkcert.
• Os certificados autoassinados não se comportarão exatamente da mesma forma 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 para seu servidor. Esquecer de reativá-la na produção causa problemas de segurança.

Os avisos que aparecem quando um certificado autoassinado é usado é exibido nos navegadores.

Se você não especificar um certificado, as opções de HTTPS do servidor de desenvolvimento do React's e Vue criarão um certificado autoassinado em segundo plano. Esse processo é rápido, mas inclui os mesmos avisos do navegador e outras armadilhas dos certificados autoassinados. Felizmente, é possível usar a opção HTTPS dos frameworks de front-end e especificar um certificado confiável localmente criado com o mkcert ou similar. Para saber mais, consulte o exemplo de mkcert com 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 verificará o certificado do servidor de desenvolvimento local. Quando você detecta que você assinou o certificado, ele verifica se você está registrado como uma autoridade de certificação confiável. Como você não é, o navegador não pode confiar no certificado e ele mostra um aviso informando que sua conexão não é segura. Se você continuar, ele ainda criará a conexão HTTPS, mas isso é feito por sua conta e risco.

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

Certificado assinado por uma autoridade certificadora regular

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

• Você tem mais trabalho de configuração a fazer do que usando uma técnica de AC local, como mkcert.
• Use um nome de domínio válido controlado por você. Isso significa que não é possível usar ACs oficiais para:
  • 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 obter 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 local com HTTPS é usar um proxy reverso, como o ngrok (link em inglês). Isso traz 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 para clientes, mas também pode permitir que pessoas não autorizadas compartilhem informações sensíveis.
• Alguns serviços de proxy reverso cobram pelo uso, portanto, o preço pode ser um fator na sua escolha de serviço.
• As novas medidas de segurança nos navegadores podem afetar o funcionamento dessas ferramentas.

Sinalizar (não recomendado)

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

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

Agradecemos muito pelas contribuições e pelo feedback a todos os avaliadores e colaboradores, especialmente Ryan Sleevi, Filippo Valsorda, Milica Mihajlija e Rowan Merewood. 🙌

Plano de fundo da imagem principal de @anandu no Unsplash, editado.