Configuring TLS

About Transport Layer Security

TLS, which replaced SSL, is enabled and configured with a self-signed certificate when GitHub Enterprise Server is started for the first time. As self-signed certificates are not trusted by web browsers and Git clients, these clients will report certificate warnings until you disable TLS or upload a certificate signed by a trusted authority, such as Let's Encrypt.

The GitHub Enterprise Server appliance will send HTTP Strict Transport Security headers when SSL is enabled. Disabling TLS will cause users to lose access to the appliance, because their browsers will not allow a protocol downgrade to HTTP. For more information, see "HTTP Strict Transport Security (HSTS)" on Wikipedia.

Aviso: no término das conexões HTTPS em um balanceador de carga, as solicitações do balanceador de carga para o GitHub Enterprise Server também precisam usar HTTPS. O downgrading da conexão para HTTP não é suportado.

To allow users to use FIDO U2F for two-factor authentication, you must enable TLS for your instance. For more information, see "Configurar a autenticação de dois fatores."

Prerequisites

To use TLS in production, you must have a certificate in an unencrypted PEM format signed by a trusted certificate authority. To use a certificate signed by an internal certificate authority, you must install the root certificate and any intermediate certificates. For more information, see "Troubleshooting TLS errors."

Your certificate will also need Subject Alternative Names configured for the subdomains listed in "Enabling subdomain isolation" and will need to include the full certificate chain if it has been signed by an intermediate certificate authority. For more information, see "Subject Alternative Name" on Wikipedia.

You can generate a certificate signing request (CSR) for your instance using the ghe-ssl-generate-csr command. For more information, see "Utilitários de linha de comando."

Your key must be an RSA key and must not have a passphrase. For more information, see "Troubleshooting TLS errors".

Uploading a custom TLS certificate

Aviso: a configuração do TLS gera uma pequena quantidade de tempo de inatividade no sua instância do GitHub Enterprise Server.

Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .
Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.
Na barra lateral " Administrador do site", clique em Console de Gerenciamento .
Na barra lateral Configurações, clique em Privacidade.
Selecione Somente TLS (recomendado) .
Under "TLS Protocol support", select the protocols you want to allow.
Under "Certificate", click Choose File, then choose a TLS certificate or certificate chain (in PEM format) to install. This file will usually have a .pem, .crt, or .cer extension.
Under "Unencrypted key", click Choose File, then choose an RSA key (in PEM format) to install. This file will usually have a .key extension.
Na barra lateral "Configurações", clique em Salvar configurações.

Observação: 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.
Aguarde a conclusão da execução de suas configurações.

About Let's Encrypt support

Let's Encrypt is a public certificate authority that issues free, automated TLS certificates that are trusted by browsers using the ACME protocol. You can automatically obtain and renew Let's Encrypt certificates on your appliance without any required manual maintenance.

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.

When you enable automation of TLS certificate management using Let's Encrypt, sua instância do GitHub Enterprise Server will contact the Let's Encrypt servers to obtain a certificate. To renew a certificate, Let's Encrypt servers must validate control of the configured domain name with inbound HTTP requests.

You can also use the ghe-ssl-acme command line utility on sua instância do GitHub Enterprise Server to automatically generate a Let's Encrypt certificate. For more information, see "Utilitários de linha de comando."

Configuring TLS using 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.

Aviso: a configuração do TLS gera uma pequena quantidade de tempo de inatividade no sua instância do GitHub Enterprise Server.

Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .
Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.
Na barra lateral " Administrador do site", clique em Console de Gerenciamento .
Na barra lateral Configurações, clique em Privacidade.
Selecione Somente TLS (recomendado) .
Select Enable automation of TLS certificate management using Let's Encrypt.
Na barra lateral "Configurações", clique em Salvar configurações.

Observação: 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.
Aguarde a conclusão da execução de suas configurações.
Na barra lateral Configurações, clique em Privacidade.
Click Request TLS certificate.
Wait for the "Status" to change from "STARTED" to "DONE".
Click Save configuration.

Troubleshooting TLS with Let's Encrypt

You can troubleshoot issues that affect your TLS certificate from Let's Encrypt.

Error: "Security error prevented the resource from being loaded"

In some cases, end users may report that pages for services on sua instância do GitHub Enterprise Server respond with the following error in a browser's developer tools.

Security error prevented the resource from being loaded

To resolve these errors, you must update the Subject Alternative Names (SANs) your Let's Encrypt certificate by reissuing the certificate. Replacement of an instance's certificate requires user-facing downtime.

Communicate the upcoming downtime to your users, and consider enabling maintenance mode. For more information, see the following articles.
- "Personalizar mensagens de usuário para sua empresa"
- "Habilitar e programar o modo de manutenção"
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
```
```
ssh -p 122 admin@HOSTNAME
```
To disable Let's Encrypt, run the following command.
Shell
```
ghe-ssl-acme -d
```
```
ghe-ssl-acme -d
```
To clear the existing settings for Let's Encrypt, run the following command.
Shell
```
ghe-ssl-acme -x
```
```
ghe-ssl-acme -x
```
To request and install a new certificate from Let's Encrypt, run the following command.
Shell
```
ghe-ssl-acme -e
```
```
ghe-ssl-acme -e
```
Para aplicar a configuração, execute o comando a seguir.

Observação: 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
```
```
ghe-config-apply
```
Aguarde a conclusão da execução de suas configurações.
If you configured a user message or maintenance mode, remove the message and disable maintenance mode.