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.
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.
Instalação
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
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.
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.
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:
Abra
https://localhost
ouhttps://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
Para executar seu site de desenvolvimento local com HTTPS:
-
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
-
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.
-
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
</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 emlocalhost
. - 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.
![Capturas de tela dos avisos que os navegadores mostram quando um certificado autoassinado é usado.](https://web.dev/static/articles/how-to-use-local-https/image/screenshots-the-warnings-953f06ad1aebc.jpg?authuser=6&hl=pt)
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.
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: um diagrama.](https://web.dev/static/articles/how-to-use-local-https/image/why-browsers-dont-trust-9aa014d2da64b.jpg?authuser=6&hl=pt)
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, comoexample
outest
.- 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.