Configurar o TLS

Sobre o protocolo Transport Layer Security

O TLS, protocolo que substituiu o SSL, fica habilitado e configurado com um certificado autoassinado quando o GitHub Enterprise Server é iniciado pela primeira vez. Como os certificados autoassinados não são considerados confiáveis por navegadores da web e clientes Git, esses clientes reportarão avisos de certificados até você desabilitar o TLS ou fazer upload de um certificado assinado por uma autoridade confiável, como o Let's Encrypt.

O appliance do GitHub Enterprise Server enviará os headers de HTTP Strict Transport Security quando o SSL for habilitado. Desabilitar o TLS fará os usuários perderem o acesso ao appliance, pois seus navegadores não permitirão o downgrade de protocolo para HTTP. Para obter mais informações, confira "HSTS (HTTP Strict Transport Security)" na Wikipédia.

Para permitir que os usuários usem o FIDO U2F para autenticação de dois fatores ou implantem sites do GitHub Pages com GitHub Actions, você deve habilitar o TLS para sua instância. Para obter mais informações, confira "Configurar a autenticação de dois fatores".

Pré-requisitos

Para usar o TLS em produção, você deve ter um certificado em formato PEM não criptografado assinado por uma autoridade de certificação confiável. Para usar um certificado assinado por uma autoridade de certificação interna, você deve instalar o certificado raiz e todos os certificados intermediários. Para obter mais informações, confira "Solução de problemas relacionados a erros do TLS".

Seu certificado também precisará ter nomes alternativos da entidade configurados para os subdomínios listados em "Habilitar isolamento de subdomínio" e precisará incluir a cadeia de certificados completa se tiver sido assinada por uma autoridade de certificação intermediária. Para obter mais informações, confira "Nome alternativo da entidade" na Wikipédia.

Você pode gerar uma CSR (solicitação de assinatura de certificado) para sua instância usando o comando ghe-ssl-generate-csr. Para obter mais informações, confira "Utilitários de linha de comando".

A chave precisa ser uma chave RSA e não pode ter uma frase secreta. Para obter mais informações, confira "Solução de problemas relacionados a erros do TLS".

Fazer upload de um certificado TLS personalizado

1. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

2. Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.

3. Na barra lateral " Administrador do site", clique em Console de Gerenciamento .

4. Na barra lateral "Configurações", clique em Privacidade e desmarque modo de privacidade.

5. Selecione Somente TLS (recomendado) .

6. Em "TLS Protocol support" (Suporte ao protocolo TLS), selecione os protocolos que deseja permitir.

7. Em "Certificado", clique em Escolher Arquivo e escolha um certificado TLS ou uma cadeia de certificados (no formato PEM) para instalação. Em geral, esse arquivo terá uma extensão .pem, .crt ou .cer.

8. Em "Chave não criptografada", clique em Escolher Arquivo e escolha uma chave RSA (no formato PEM) para instalação. Em geral, esse arquivo terá uma extensão .key.

9. Na barra lateral "Configurações", clique em Salvar configurações.

   Note

   Se você salvar as configurações no Console de Gerenciamento, isso reiniciará os serviços do sistema, o que poderá resultar em tempo de inatividade visível pelo usuário.

10. Aguarde a conclusão da execução de suas configurações.

Sobre o suporte Let's Encrypt

Let's Encrypt é uma autoridade de certificação pública que emite certificados TLS gratuitos, automatizados e reconhecidos como confiáveis pelos navegadores usando o protocolo ACME. Você pode obter e renovar automaticamente os certificados Let's Encrypt no seu appliance sem depender de manutenção manual.

Para usar a automação Let's Encrypt, seu appliance deve ser configurado com um nome de host acessível ao público por HTTP. O appliance deve também ser autorizado a estabelecer conexões HTTPS de saída.

Quando você habilitar a automação do gerenciamento de certificados TLS usando o Let's Encrypt, o sua instância do GitHub Enterprise Server entrará em contato com os servidores do Let's Encrypt para obter um certificado. Para renovar um certificado, os servidores do Let's Encrypt devem validar o controle do nome de domínio configurado com solicitações HTTP de entrada.

Use também o utilitário de linha de comando ghe-ssl-acme do sua instância do GitHub Enterprise Server para gerar automaticamente um certificado Let's Encrypt. Para obter mais informações, confira "Utilitários de linha de comando".

Configurar o TLS usando Let's Encrypt

Para usar a automação Let's Encrypt, seu appliance deve ser configurado com um nome de host acessível ao público por HTTP. O appliance deve também ser autorizado a estabelecer conexões HTTPS de saída.

1. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

2. Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.

3. Na barra lateral " Administrador do site", clique em Console de Gerenciamento .

4. Na barra lateral "Configurações", clique em Privacidade e desmarque modo de privacidade.

5. Selecione Somente TLS (recomendado) .

6. Selecione Habilitar a automação do gerenciamento de certificados TLS usando o Let's Encrypt.

7. Na barra lateral "Configurações", clique em Salvar configurações.

   Note

   Se você salvar as configurações no Console de Gerenciamento, isso reiniciará os serviços do sistema, o que poderá resultar em tempo de inatividade visível pelo usuário.

8. Aguarde a conclusão da execução de suas configurações.

9. Na barra lateral "Configurações", clique em Privacidade e desmarque modo de privacidade.

10. Clique em Solicitar certificado TLS.

11. Espere o "Status" mudar de "INICIADO" para "Concluído".

    

12. Clique em Salvar configuração.

Solução de problemas de TLS com Let's Encrypt

Você pode solucionar problemas que afetam seu certificado TLS do Let's Encrypt.

Erro: "Erro de segurança impediu que o recurso fosse carregado"

Em alguns casos, os usuários finais podem relatar que as páginas de serviços em sua instância do GitHub Enterprise Server respondem com o seguinte erro nas ferramentas para desenvolvedores de um browser.

Security error prevented the resource from being loaded

Para resolver esses erros, você deve atualizar os nomes alternativos da entidade (SANs) seu certificado Let's Encrypt reemitindo o certificado. A substituição do certificado de uma instância requer tempo de inatividade voltado para o usuário.

1. Comunique o próximo tempo de inatividade aos usuários e considere habilitar o modo de manutenção. Para obter mais informações, consulte os seguintes artigos.

   • "Personalizar mensagens de usuário para sua empresa"
   • "Habilitar e programar o modo de manutenção" 1. Conecte-se via SSH ao sua instância do GitHub Enterprise Server. Se sua instância for composta por vários nós, por exemplo, se a alta disponibilidade ou a replicação geográfica estiver configurada, efetue SSH no nó primário. Se você usar um cluster, poderá efetuar SSH em qualquer nó. Substitua HOSTNAME pelo nome do host da instância ou pelo nome do host ou endereço IP de um nó. Para obter mais informações, confira "Acesar o shell administrativo (SSH)".
   Shell

   ssh -p 122 admin@HOSTNAME
   

2. Para desabilitar o Let’s Encrypt, execute o seguinte comando:

   Shell

   ghe-ssl-acme -d
   

3. Para limpar as configurações existentes para Let's Encrypt, execute o seguinte comando.

   Shell

   ghe-ssl-acme -x
   

4. Para solicitar e instalar um novo certificado do Let's Encrypt, execute o seguinte comando.

   Shell

   ghe-ssl-acme -e
   

5. Para aplicar a configuração, execute o comando a seguir.

   Note

   Durante uma execução de configuração, os serviços do sua instância do GitHub Enterprise Server podem ser reiniciados, o que pode causar um breve tempo de inatividade para os usuários.

   Shell

   ghe-config-apply
   

6. Aguarde a conclusão da execução de suas configurações.

7. Se você configurou uma mensagem de usuário ou um modo de manutenção, remova a mensagem e desabilite o modo de manutenção.