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. [サイト管理者] ページにまだ表示されていない場合は、左上隅の [サイト管理者] をクリックします。

3. [ サイト管理者] サイドバーで [Management Console] をクリックします。

4. [設定] サイドバーで [プライバシー] をクリックします。

5. [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. [設定] サイドバーで [設定の保存] をクリックします。

   注: [Management Console] に設定を保存すると、システム サービスが再起動され、ユーザーに表示されるダウンタイムが発生する可能性があります。

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. [サイト管理者] ページにまだ表示されていない場合は、左上隅の [サイト管理者] をクリックします。

3. [ サイト管理者] サイドバーで [Management Console] をクリックします。

4. [設定] サイドバーで [プライバシー] をクリックします。

5. [TLS のみ] (推奨) を選択します。

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

7. [設定] サイドバーで [設定の保存] をクリックします。

   注: [Management Console] に設定を保存すると、システム サービスが再起動され、ユーザーに表示されるダウンタイムが発生する可能性があります。

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.

   • "Enterprise のユーザメッセージをカスタマイズする"
   • "メンテナンスモードの有効化とスケジューリング"

2. お使いの GitHub Enterprise Server インスタンス に SSH で接続します。 インスタンスが複数のノードで構成されている場合は (高可用性や geo レプリケーションが構成されている場合など)、プライマリ ノードに 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. 構成を適用するには、次のコマンドを実行します。

   注: 構成の実行中に、お使いの GitHub Enterprise Server インスタンス 上のサービスが再起動する可能性があり、これによりユーザーに短時間のダウンタイムが発生する場合があります。

   Shell

   ghe-config-apply
   

7. 設定の実行が完了するのを待ってください。

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