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.

To allow users to use FIDO U2F for two-factor authentication, you must enable TLS for your instance. For more information, see "2단계 인증 구성."

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 "명령줄 유틸리티."

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

1. 페이지의 오른쪽 상단에 있는 GitHub Enterprise Server의 관리 계정에서 을 클릭합니다.

2. “Site admin”(사이트 관리자) 페이지에 아직 없는 경우 왼쪽 상단에서 Site admin(사이트 관리자)을 클릭합니다.

3. " 사이트 관리자" 사이드바에서 관리 콘솔 을 클릭합니다.

4. 설정에서 사이드바의 프라이버시 탭을 클릭하세요.

5. TLS only (recommended)(TLS만(권장))를 선택합니다.

6. Under "TLS Protocol support", select the protocols you want to allow.

7. 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.

8. Under "Unencrypted key", click Choose File, then choose an RSA key (in PEM format) to install. This file will usually have a .key extension.

9. "설정" 사이드바에서 설정 저장을 클릭합니다.

   참고: 관리 콘솔에 설정을 저장하면 시스템 서비스가 다시 시작되어 사용자에게 표시되는 가동 중지 시간이 발생할 수 있습니다.

10. 구성 실행이 완료될 때까지 기다립니다.

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.

Let's Encrypt 자동화를 사용하려면 HTTP를 통해 공개적으로 액세스할 수 있는 호스트 이름으로 어플라이언스를 구성해야 합니다. 또한 어플라이언스에서 아웃바운드 HTTPS 연결을 만들 수 있어야 합니다.

When you enable automation of TLS certificate management using Let's Encrypt, 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 GitHub Enterprise Server 인스턴스 to automatically generate a Let's Encrypt certificate. For more information, see "명령줄 유틸리티."

Configuring TLS using Let's Encrypt

Let's Encrypt 자동화를 사용하려면 HTTP를 통해 공개적으로 액세스할 수 있는 호스트 이름으로 어플라이언스를 구성해야 합니다. 또한 어플라이언스에서 아웃바운드 HTTPS 연결을 만들 수 있어야 합니다.

1. 페이지의 오른쪽 상단에 있는 GitHub Enterprise Server의 관리 계정에서 을 클릭합니다.

2. “Site admin”(사이트 관리자) 페이지에 아직 없는 경우 왼쪽 상단에서 Site admin(사이트 관리자)을 클릭합니다.

3. " 사이트 관리자" 사이드바에서 관리 콘솔 을 클릭합니다.

4. 설정에서 사이드바의 프라이버시 탭을 클릭하세요.

5. TLS only (recommended)(TLS만(권장))를 선택합니다.

6. Select Enable automation of TLS certificate management using Let's Encrypt.

7. "설정" 사이드바에서 설정 저장을 클릭합니다.

   참고: 관리 콘솔에 설정을 저장하면 시스템 서비스가 다시 시작되어 사용자에게 표시되는 가동 중지 시간이 발생할 수 있습니다.

8. 구성 실행이 완료될 때까지 기다립니다.

9. 설정에서 사이드바의 프라이버시 탭을 클릭하세요.

10. Click Request TLS certificate.

11. Wait for the "Status" to change from "STARTED" to "DONE".

    

12. 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 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.

1. Communicate the upcoming downtime to your users, and consider enabling maintenance mode. For more information, see the following articles.

   • "엔터프라이즈에 대한 사용자 메시지 사용자 지정"
   • "유지 관리 모드 사용 설정 및 예약"

2. 에 SSH합니다. 인스턴스가 여러 노드로 구성된 경우(예: 고가용성 또는 지역 복제가 구성된 경우) 주 노드에 대한 SSH를 수행합니다. 클러스터를 사용하는 경우 임의 노드에 대해 SSH를 수행할 수 있습니다. HOSTNAME을 인스턴스의 호스트 이름 또는 노드의 호스트 이름이나 IP 주소로 바꿉니다. 자세한 내용은 "관리 셸(SSH)에 액세스"을(를) 참조하세요.

   Shell

   ssh -p 122 admin@HOSTNAME
   

3. To disable Let's Encrypt, run the following command.

   Shell

   ghe-ssl-acme -d
   

4. To clear the existing settings for Let's Encrypt, run the following command.

   Shell

   ghe-ssl-acme -x
   

5. To request and install a new certificate from Let's Encrypt, run the following command.

   Shell

   ghe-ssl-acme -e
   

6. 구성을 적용하려면 다음 명령을 실행합니다.

   참고: 구성을 실행하는 동안 의 서비스가 다시 시작될 수 있으므로 짧은 가동 중지 시간이 발생할 수 있습니다.

   Shell

   ghe-config-apply
   

7. 구성 실행이 완료될 때까지 기다립니다.

8. If you configured a user message or maintenance mode, remove the message and disable maintenance mode.