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 o uso de cookies seguros em navegadores, em que é necessário configurar explicitamente o site de desenvolvimento para se comportar como HTTPS para 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.

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

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

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

Para usar 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 em que seu dispositivo e navegador confiam, chamada de autoridade de certificação (CA) 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 de 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, elas são mais complexas e menos confiáveis do que o mkcert, além de não serem necessariamente multiplataforma, o que as torna menos acessíveis para equipes de desenvolvedores maiores.

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 (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 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 do 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 o servidor para usar HTTPS com o certificado TLS que você acabou de criar.

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

    👩🏻‍💻 Com o Node:

    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 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 o package.json da seguinte forma 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 seu site:

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

    Em seguida, 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:

  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 do mkcert

Referência rápida do mkcert

Para executar o site de desenvolvimento local com HTTPS:

  1. Configure o mkcert.

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

    brew install mkcert

    Consulte instalar o mkcert para ver as instruções do Windows e do 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

</div>

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

Veja a seguir outras maneiras de configurar seu certificado. Em geral, elas são mais complicadas ou arriscadas do que usar o mkcert.

Certificado autoassinado

Você também pode decidir não usar uma autoridade de certificação local, como o mkcert, e assinar seu certificado por conta própria. Essa abordagem tem algumas armadilhas:

  • Os navegadores não confiam em você como uma autoridade de certificação, então eles vão mostrar avisos que você precisa ignorar manualmente. No Chrome, use a flag #allow-insecure-localhost para ignorar esse aviso automaticamente em 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 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 do servidor. Esquecer de reativá-lo na produção causa problemas de segurança.
Capturas de tela dos avisos que os navegadores mostram quando um certificado autoassinado é usado.
Os avisos que os navegadores mostram quando um certificado autoassinado é usado.

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

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

Certificado assinado por uma autoridade certificadora comum

Também é possível usar um certificado assinado por uma CA oficial. Isso traz as seguintes complicações:

  • Você tem mais trabalho de configuração do que quando usa uma técnica de CA local, como mkcert.
  • Você precisa usar um nome de domínio válido que você controla. Isso significa que não é possível usar CAs oficiais para o seguinte:

Proxy reverso

Outra opção para acessar um site em execução local com HTTPS é usar um proxy reverso, como o ngrok. Os riscos estão listados a seguir:

  • 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 sensíveis.
  • Alguns serviços de proxy reverso cobram pelo uso, então o preço pode ser um fator na sua escolha de serviço.
  • Novas medidas de segurança nos navegadores podem afetar o funcionamento dessas ferramentas.

Se você estiver usando um nome do host personalizado, como mysite.example, no Chrome, use 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 é 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, então não é possível depurar em vários navegadores.

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

Anterior
Quando usar HTTPS para desenvolvimento local