keeper/guacamole-ssl-nginx

SSLターミネーションのためのKeeperコネクションマネージャーを使用したNGINXのDockerによるデプロイ

イメージ: keeper/guacamole-ssl-nginx

keeper/guacamole-ssl-nginxはNGINXのDocker化されたデプロイで、Dockerの公式Nginxイメージで構築され、GuacamoleにSSLターミネーションを提供するように事前に設定されています。以下の機能をサポートしています。

このイメージは、Keeperコネクションマネージャーの一部として作成され、同じEULAで利用できるようになっています。通常は、keeper/guacamoleイメージを使用して、コンテナにSSLターミネーションを提供するために使用します。

サポートされているSSL証明書の種類

keeper/guacamole-ssl-nginxでは、既存のSSL証明書を生成、取得、使用するためのメカニズムがいくつかサポートされています。使用されるメカニズムは、Dockerコンテナの作成時に指定した環境変数によって異なります。

これらのメカニズム固有の環境変数に加えて、必ず指定する必要のある以下の環境変数のセットがあります

  • ACCEPT_EULA - KeeperコネクションマネージャーのEULAに同意するか否か (このイメージを使用するにはEULAに同意する必要があります)。

  • GUACAMOLE_HOSTNAME - Guacamoleインスタンスのホスト名とアドレス。

  • SSL_HOSTNAME - Guacamoleへのアクセスに使用される公開ドメイン名。

Let's Encrypt

既存の証明書が指定されず、自己署名証明書の生成も求められない場合は、Let's Encryptがデフォルトで使用されます。keeper/guacamole-ssl-nginxイメージは、「certbot」ツールを使用してLet's Encryptサービスに接続し、SSL証明書を取得します。

Let's Encrypt証明書を使用する場合は、以下のLet's Encrypt固有の環境変数が必須となります。

  • LETSENCRYPT_ACCEPT_TOS - Let's Encryptの利用規約に同意するか否か (サービスを使用するには、Let's Encryptの利用規約に同意する必要があります)。

利用規約への同意に加えて、証明書に関する重要なアラートを受信できるようにメールアドレスの登録が強く推奨されています。登録しない理由がない限り、メールアドレスを登録するようにしましょう。

  • LETSENCRYPT_EMAIL - 証明書を要求する際にLet's Encryptに提出するメールアドレス。

Let's Encryptの使用方法をテストするだけの場合は、本番環境ではなくLet's Encryptのステージング (テスト) 環境を使用する必要があります。

  • LETSENCRYPT_STAGING - 本番環境ではなく、Let's Encryptのステージング環境を使用するには、「Y」に設定します。

取得した証明書は必要に応じてこのイメージによって自動的に更新されます。取得に失敗した場合、コンテナは停止し、失敗の詳細がログに記録され、次にコンテナが起動したときに取得プロセスが再試行されます。

keeper/guacamole-ssl-nginxイメージでは、Dockerボリュームを使用してLet's Encryptの証明書や状態を保存し、コンテナを再作成してもそれらが失われないようにします。

たとえば、以下の例では、docker-compose.ymlファイルにLet's Encrypt証明書が生成されます。

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA:"Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            LETSENCRYPT_ACCEPT_TOS:"Y"
            LETSENCRYPT_EMAIL: you@company.com

任意のCAから取得した既存の証明書

認証局から取得した証明書がすでにある場合は、環境変数CERTIFICATE_FILEおよびPRIVATE_KEY_FILEで関連するファイルを指定することで、その証明書を使用できます。関連するファイルは、Dockerボリュームマウントを使用してイメージに開示する必要があります。

  • CERTIFICATE_FILE - 証明書PEMファイルへのフルパス。

  • PRIVATE_KEY_FILE - 秘密鍵PEMファイルへのフルパス。

CAによる証明書の更新時期が来たら、証明書と秘密鍵を交換してNGINXをリロードする必要があります。証明書が更新されたら、Docker Composeを停止して起動します。

Docker Composeの設定に関する以下の例では、鍵を保持する共有ボリュームからカスタム証明書を読み込みます。

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA:"Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            CERTIFICATE_FILE: "/path/in/container/mycert.pem"
            PRIVATE_KEY_FILE: "/path/in/container/mykey.pem"
        volumes:
            - "/local/path/to/keys:/path/in/container/"

自己署名証明書

テスト用にデプロイする場合、独自の自己署名証明書を自動的に生成して維持することができます。

  • SELF_SIGNED - 「Y」に設定すると、テスト用に自己署名証明書を自動的に生成します。

keeper/guacamole-ssl-nginxイメージが、起動時に自己署名証明書を再生成します。証明書は生成後30日で期限切れになるため、証明書が期限切れにならないように21日ごとに自動的に再生成します。

証明書の有効期限とフィンガープリントは、証明書が再生成されるたびにログに記録されるため、基本的なサーバーIDの検証が可能になります。

環境変数

公式のNGINXイメージがベースとなっているため、以下に記載した環境変数に加えて、公式のDocker Nginxイメージでサポートされているすべての環境変数が利用できます。

ACCEPT_EULA

環境変数ACCEPT_EULAは「Y」に設定して、KeeperコネクションマネージャーのEULAに同意したことを示す必要があります。このDockerイメージは、EULAの条件に従わないと使用できません。

SSL_HOSTNAME

Dockerをホストするサーバーの公開ホスト名。この環境変数は必須であり、インターネット経由でGuacamoleにアクセスする際に使用される完全な公開ドメイン名を指定する必要があります。このドメイン名は、Dockerおよびこのイメージをホスティングしているサーバーに到達するIPアドレスに既に関連付けられている必要があります。

GUACAMOLE_HOSTNAME

Guacamoleサーバーの内部ホスト名またはIPアドレスを指定します。この環境変数は必須であり、接続を処理する際にNGINXが内部的に接続するホスト名またはアドレスを設定する必要があります。

なお、ここで指定するGuacamoleサービスのホスト名やアドレスは内部ネットワークからのみ到達可能でなければなりません。外部に公開されるのは、SSLター未ネーションサービス (このイメージ) のみです。

GUACAMOLE_PORT

Guacamoleサーバーの待ち受けTCPポート番号。この環境変数はオプションで、省略した場合は標準ポート8080がデフォルトで使用されます。

GUACAMOLE_CONTEXT_PATH

Guacamoleサービスが提供されているパス。この環境変数はオプションです。デフォルトでは空白になり、Guacamoleサービスがルートパスから提供されていることを示します。keeper/guacamoleイメージのGUACAMOLE_CONTEXT_PATH環境変数と同様に、このパラメータにスラッシュは使用できません。

たとえば、Guacamoleがhttp://some-host/guacamole/で内部的に実行されている場合は、GUACAMOLE_CONTEXT_PATHguacamoleに設定してください。

SELF_SIGNED

「Y」に設定すると、SSL_HOSTNAMEに対する自己署名証明書の自動生成が要求され、既存の証明書の使用やLet's Encryptからの新しい証明書の取得は要求されません。

自己署名証明書は基本的に安全ではありません。このオプションはテストにのみご使用ください。

CERTIFICATE_FILEおよびPRIVATE_KEY_FILE

SSL証明書と関連する秘密鍵のそれぞれのPEMファイルのパス。これらは、Dockerコンテナのファイルシステムに対するパスです。外部から取得したSSL証明書のPEMファイルは、Dockerボリュームマウントを使用してコンテナ内で開示する必要があります。

これらの環境変数は、独自の証明書を設定する場合のみ必要となります。SELF_SIGNEDを使用して自己署名証明書でテストする場合、これらは無視されます。

LETSENCRYPT_ACCEPT_TOS

Let's Encryptを使用する場合は、Let's Encryptの利用規約に同意したことを示すために、LETSENCRYPT_ACCEPT_TOS環境変数を「Y」に設定します。Let's Encryptは、該当する利用規約に同意しないと利用できません。

この環境変数は、Let's Encryptを使用する場合のみ必要となります。CERTIFICATE_FILEおよびPRIVATE_KEY_FILEを使用して独自の証明書を設定する場合やSELF_SIGNEDで自己署名証明書を使用してテストする場合は無視されます。

LETSENCRYPT_EMAIL

証明書を要求するときにLet's Encryptに登録するメールアドレス。この環境変数はオプションで、CERTIFICATE_FILEおよびPRIVATE_KEY_FILEを使用して独自の証明書を設定する場合やSELF_SIGNEDで自己署名証明書を使用してテストする場合は無視されます。

この環境変数はオプションですが、Let's Encryptのサービスを使用して証明書を取得する場合は、メールアドレスの登録が強く推奨されています。certbotツールのヘルプには以下のように記載されています。

鍵の紛失やアカウントの侵害が発生した場合、アカウントへのアクセスを永久に失うことになるため、決してお勧めできません。また、証明書の失効または取り消しが近いことを知らせる通知も受信できなくなります。それでも利用規約の更新が適用され、ウェブサイトに更新が投稿されてから14日後にその効力が発生します。

LETSENCRYPT_STAGING

「Y」に設定した場合、本番環境ではなくLet's Encryptのステージング環境を使用してSSL証明書を取得するように要求します。Let's Encryptの機能をテストするだけの場合は、このオプションをご使用ください。

コンテンツセキュリティポリシー (CSP)

コンテンツセキュリティポリシー (CSP) は、ブラウザ機能の一つで、KCMのようなウェブアプリケーションが、そのウェブアプリケーションの文脈内で許可される操作の種類をブラウザに宣言できる仕組みです。特にCSPを使用することで、ウェブアプリケーションが安全でない、または予期しないとみなすリソースの読み込みやスクリプトの実行をブラウザにブロックするよう要求できます。具体的にはHTTPレスポンスにContent-Security-Policyヘッダを追加することで実現されます。

デフォルトのContent-Security-Policyヘッダは、既知の初期値で設定されており、特別な設定がない限り、keeper/guacamole-ssl-nginxイメージによって自動的に適用されます。この設定は、CONTENT_SECURITY_POLICY環境変数を使用して変更できます。

通常、この環境変数を設定する必要はありませんが、カスタムのKCM/Guacamole拡張機能がより緩やかなポリシーを必要とする場合に限り設定が必要となります。

デフォルトのポリシーを上書きする必要がある場合はご注意ください。過度に厳しいCSPを設定すると、KCMがグラフィカルデータのデコードや独自のREST APIへのリクエストといった重要なタスクを実行できなくなる可能性があります。

CONTENT_SECURITY_POLICY

Nginxから送信されるレスポンスに含まれるContent-Security-Policyヘッダの値を設定します。

  • 「Y」に設定した場合: ほとんどのKCMインストール環境で動作することが確認されている適切なデフォルト値が設定されます。 デフォルト値: script-src 'self' 'unsafe-eval'; default-src 'self' data:; style-src 'self' 'unsafe-inline'; この構成により、KCMと同じドメインからのアセットの読み込み、翻訳用のeval()の使用、JavaScriptによる動的なCSSの読み込みが許可されます。

  • 「N」に設定した場合: ヘッダはレスポンスに追加されません。

  • 他の値に設定された場合: 環境変数に設定された値がそのままレスポンスのヘッダとして送信されます。

HTTP Strict Transport Security (HSTS)

HTTP Strict Transport Security (HSTS) は、ドメイン所有者がブラウザに対して接続をHTTPSのみに限定するよう通知するためのブラウザ機能です。HSTSを有効にすると、HTTP接続は送信される前に自動的にHTTPSにアップグレードされます。

HSTSはすべてのKCMのデプロイメントに適しているというわけではありません。特に、KCMが他のすべてが HTTPSをサポートしていないウェブアプリケーションとドメインを共有する場合には適していません。そのため、KCMのインストールではデフォルトでHSTSが有効になっていません。

HSTSを有効にするには、STRICT_TRANSPORT_SECURITY環境変数に値を設定する必要があります。便利な推奨デフォルト値が用意されています。

STRICT_TRANSPORT_SECURITY

Nginxが送信するレスポンスに含まれるStrict-Transport-Securityヘッダの値を設定します。

  • 「Y」に設定した場合: 推奨されるデフォルト値 max-age=31536000; includeSubDomains; preload; が常に設定されます。この値は https://https.cio.gov/hsts/に基づいて推奨されています。

  • 「N」に設定された場合: ヘッダはレスポンスに追加されません。

  • その他の値が設定された場合: 設定された値がそのままレスポンスに含まれるヘッダとして送信されます。

Dockerシークレット

環境変数でデータを直接渡すのではなく、このイメージでサポートされている任意の環境変数に_FILEサフィックスを付加して、コンテナ内の指定されたファイルからその変数を強制的に読み込ませることができます。Dockerシークレットは機密データをコンテナ内の/run/secrets/配下のファイルに格納するため、これを使用して機密データをDockerシークレットから読み込めます。

たとえば、DockerシークレットからLet's Encryptアカウントのメールを読み込むには、以下のようにします。

docker run --name some-guacamole-ssl \
    -e ACCEPT_EULA=Y \
    -e LETSENCRYPT_ACCEPT_TOS=Y \
    -e LETSENCRYPT_EMAIL_FILE=/run/secrets/letsencrypt-email \
    -d keeper/guacamole-ssl-nginx

高度な設定

このセクションの環境変数は、非標準のポートから KCM を提供する場合や、古い暗号スイートや SSL バージョンを有効にする必要がある特殊なケースでのみ必要です。これらの変数を設定する場合は、その必要性を十分に理解したうえで行ってください。

SSL_CIPHERS

Nginx インスタンスで許可される SSL 暗号スイートを設定します。このパラメータの許可される値については、Nginx のドキュメントを参照してください。値が指定されない場合、デフォルトで "HIGH:!aNULL:!MD5" が使用されます。

SSL_PROTOCOLS

Nginx インスタンスで許可される SSL プロトコルを設定します。このパラメータの許可される値については、Nginx のドキュメントを参照してください。値が指定されない場合、TLS 1.2 および 1.3 が有効になります。

SSL_EXTERNAL_PORT

Nginx が KCM Web アプリケーションにリクエストを送信する際に使用する X-Forwarded-Port ヘッダーの値を設定します。このヘッダーは、非標準ポートで SSL リクエストを受信していることを KCM サーバーに通知します。

非標準ポートを使用する場合、そのポートは標準ポートにマッピングする必要があります(例: -p 8443:443)。この変数を設定しても、イメージ内で Nginx が内部的に使用するポートには影響しません。

値が指定されない場合、KCM は受信リクエストが標準 HTTPS ポート (443) から来ていると想定します。

ADDITIONAL_CONFIG

この変数は、イメージによって生成されたNginx設定ファイル内で KCMウェブアプリケーションを指すserverブロックに任意の構成を追加するためのものです。

この変数は、keeper/guacamole-ssl-nginxイメージで対応する環境変数が用意されていないNginx設定オプションを適用するための汎用的な手段として機能します。

ADDITIONAL_CONFIG環境変数で指定された値は、KCMウェブアプリケーションを指すメインserverブロックに含まれます。ただし、Nginxがserverブロック内で受け入れる設定オプションのみを記述します。

Last updated