PIV/CAC/スマートカード
PIV/CACデバイスを使用してKeeperコネクションマネージャーにログイン
KCMでは、DoDの共通アクセスカード (Common Access Card、CAC) を使用したウェブアプリケーションによる認証だけでなく、個人識別確認 (Personal Identity Verification、PIV) などのSSLクライアント認証用にブラウザで対応している任意のスマートカードによる認証も可能です。
このサポートは、KCMバージョン2.12.0に追加された機能である、SSL/TLS認証を提供するSSLターミネーションインスタンスを必要とします。
PIV/CACの一般的な設定は以下のようになります。
2つのホスト名が設定されたSSLターミネーションインスタンス。1つは通常のアクセス用 (
kcm.example.netなど) で、もう1つはSSLクライアント認証の処理専用で、ワイルドカードドメイン (*.login.kcm.example.netなど) が望ましいでしょう。SSLクライアント認証設定には、PIV/CACカードを提供するCAの証明書が含まれます。PIV/CACサポートのインストールと設定。
*.login.kcm.example.netに対してユーザーを認証し、準備ができたらkcm.example.netにリダイレクトするように設定します。SSOを利用したユーザーのユーザーアカウントを自動的に作成するように設定されたデータベースバックエンド。
PIV/CACからシングルサインオンするユーザーの承認を要求するように設定されたユーザー作成ワークフロー。
PIV/CACの設定オプション
PIV/CACのサポートは、SSL/TLSクライアント認証に対するKeeperの新しいサポートを使用して設定します。このサポートは、kcm-guacamole-auth-sso-ssl としてパッケージ化されている「guacamole-auth-sso-ssl」拡張機能によって提供されます。どの SSL_* 変数を設定しても、kcm-guacamole-auth-sso-ssl パッケージが暗黙的に含まれます。
以下のオプションは、keeper/guacamoleのDockerコンテナ定義 (または、Linuxディストリビューションの場合はguacamole.properties) で設定する必要があります。
ssl-client-auth-uri
SSL_CLIENT_AUTH_URI
必須。このGuacamoleインスタンスを指し、SSL/TLSクライアント認証を要求するワイルドカードURI。
ssl-primary-uri
SSL_PRIMARY_URI
必須。このGuacamoleインスタンスを指し、SSL/TLSクライアント認証を要求「しない」ワイルドカードを使用しないURI。
ssl-subject-base-dn
SSL_SUBJECT_BASE_DN
有効なサブジェクトDNをすべて含むベースDN。指定した場合、このベースDNの下にあるサブジェクトDNを明示する証明書のみが受け入れられます。
デフォルトでは、すべてのDNが受け入れられます。
ssl-subject-username-attribute
SSL_SUBJECT_USERNAME_ATTRIBUTE
ユーザーのX .509証明書のサブジェクトDN内でユーザー名を表示すために使用できる1つまたは複数のLDAP属性。サブジェクトDNの最下位属性がこれらの属性のいずれでもない場合、証明書は拒否されます。
デフォルトでは、任意の属性が受け入れられます。
以下のオプションも使用できますが、設定が必要になることはめったにないでしょう。
ssl-client-certificate-header
SSL_CLIENT_CERTIFICATE_HEADER
SSL/TLSクライアント認証を提供するSSLターミネーションサービスから受信したHTTPリクエストから取得した、URLエンコードされたクライアント証明書を取得するために使用するヘッダーの名前。
keeper/guacamole-ssl-nginx イメージのデフォルト値はこのオプションのデフォルト値と一致するため、通常は設定する必要はないはずです。
X-Client-Certificate
ssl-client-verified-header
SSL_CLIENT_VERIFIED_HEADER
SSL/TLSクライアント認証を提供するSSLターミネーションサービスからHTTPリクエストが受信した証明書の検証ステータスを取得するために使用するヘッダーの名前。証明書が正常に検証された場合、このヘッダーの値は「SUCCESS」 (すべて大文字) である必要があります。
keeper/guacamole-ssl-nginx イメージのデフォルト値はこのオプションのデフォルト値と一致するため、通常は設定する必要はないはずです。
X-Client-Verified
ssl-max-domain-validity
SSL_MAX_DOMAIN_VALIDITY
SSL/TLS認証のために一時的に生成された一意のサブドメインの有効時間 (分単位)。
このサブドメインは、各SSL/TLS認証が新たな試行であり、ブラウザやOSがキャッシュした過去の認証試行を再利用するおそれがないようにするために使用されます。この間隔は、SSL/TLSクライアント認証を強制するSSLターミネーションサービスでユーザーを認証する際のネットワーク遅延を計算に入れた十分な長さであることが必要ですが、使用されていないドメインが不要なサーバーリソースを消費することなく、そのサブドメインがまだ有効であるか推測できないかもしれないほど十分短い必要があります。これらのサブドメインは、128ビットのセキュアなランダム値です。
これは通常は設定する必要はないはずですが、管理者はこの値を減らしたいと考えるかもしれません。
5
ssl-max-token-validity
SSL_MAX_TOKEN_VALIDITY
SSL/TLS認証のために一時的な認証トークンの有効時間 (分単位)。
このトークンは、SSLターミネーションサービスによって検証された後、ユーザーの明示されたIDを示すために使用されます。この間隔は、トークンを受信する際のネットワーク遅延を計算に入れた十分な長さであることが必要ですが、使用されていないトークンが不要なサーバーリソースを消費することなく、そのトークンがまだ有効であるか推測できないかもしれないほど十分短い必要があります。これらのトークンは、256ビットのセキュアなランダム値です。
これは通常は設定する必要はないはずですが、管理者はこの値を減らしたいと考えるかもしれません。
5
PIV/CACのSSL (NGINX) 設定オプション
ブラウザを使用したPIV/CAC (または任意のスマートカード) による認証では、SSL/TLSクライアント認証を使用しています。この機能をPIV/CAC用にさらに強化するために、証明書がOCSPまたはCRLを使用して取り消されたかどうかをテストするための便利な設定オプションが追加されました。参考までに、keeper/guacamole-ssl-nginxのDockerイメージで現在対応しているSSL/TLSクライアント認証に関連するすべてのオプションを以下に示します。
ADDITIONAL_PROXY_CONFIG
NGINXがGuacamoleのプロキシとして機能するように設定する location ブロック内に含める必要のある、任意の追加のNGINX設定ステートメント。
CLIENT_CERTIFICATE_FILE
SSL/TLSクライアントが提示した証明書をNGINXが検証するために使用する必要のある証明書。
CLIENT_CRL_FILE
NGINXがクライアントの証明書が失効しているかどうかを確認するために使用する証明書失効リスト (Certificate Revocation List、CRL) ファイルを管理します。NGINXの ssl_crl ディレクティブで設定します。このファイルはPEM形式であることが必要で、複数のCRLを指定できます。省略した場合、CRLファイルは使用されません。
CLIENT_CERTIFICATE_FILE が指定されていない場合、この変数は無視されます。
使用可能な場合は、CRLファイルを使用するよりもOCSPを使用する方が望ましい場合が多いです。
CLIENT_OCSP
NGINXがOCSPを使用してクライアントの証明書が失効しているかどうかを確認するか否かを管理します。NGINXの ssl_ocsp ディレクティブで設定します。この変数を on に設定すると、OCSPを使用してクライアント証明書がチェックされます。
CLIENT_CERTIFICATE_FILE が指定されていない場合、この変数は無視されます。
有効な場合、RESOLVER も指定する必要があります。
off
RESOLVER
NGINXがドメイン名を解決するために使用するDNSサーバー。これは、OCSPが有効な場合にのみ必要です。
SSL_VERIFY_CLIENT
NGINXがクライアント (ブラウザ) が提示する証明書を要求および検証する方法とその要否を管理します。NGINXの ssl_verify_client ディレクティブで設定します。
on
SSL_VERIFY_DEPTH
NGINXがクライアントの証明書を検証しようとするときに、クライアントの証明書チェーンを確認する深さを管理します。NGINXの ssl_verify_depth ディレクティブで設定します。
1
PIV/CACの設定例
以下の docker-compose.yml の例では、以下のプレースホルダーを使用しています。
プレースホルダー
説明
PasswordForPostgresAdmin
PostgreSQLの postgres ユーザー (PostgreSQLデータベースの一般的なルートユーザー) に割り当てるのに適したパスワード。このアカウントは、管理者が psql などのツールを使用して手動でデータベースに接続する必要がある場合にのみ使用されます。
guacamole_db
PostgreSQL内のGuacamoleデータベースの名前。この値は kcm-setup.run によって自動的に使用され、Keeperのドキュメントとアップストリームの両方で適切な値として記載されているため、ここで他の値を使用することはほとんどありません。
guacamole_user
Guacamoleがデータベースに対してクエリを実行するために使用する、権限が制限されたPostgreSQLユーザー。この値は kcm-setup.run によって自動的に使用され、Keeperのドキュメントとアップストリームの両方で適切な値として記載されているため、ここで他の値を使用することはほとんどありません。
PasswordForGuacamole
Guacamoleが権限が制限された guacamole_user アカウントとしてデータベースで認証し、クエリを実行するために使用するPostgreSQLユーザーに割り当てる適切なパスワード。
ou=test department,o=u.s. government,c=us
SSL/TLSクライアント認証 (ブラウザを使用したスマートカード認証) を使用して提示された場合に受け入れる必要があるサブジェクトDNのベースDN。
kcm.example.net
ユーザーがKCMを使用するためにブラウザでアクセスするドメイン。
/path/to/pki
クライアント認証などのSSLに使用される証明書と秘密鍵を格納するDockerホスト上のパス。
/pki
NGINXがコンテナのファイルにアクセスできるように、/path/to/pki をマウントする必要のあるDockerコンテナ内のパス。
cac-certificate.pem
ユーザーがスマートカードで認証しようとするときに、NGINXがユーザーから受け取る証明書を検証するために使用するPEM形式の証明書のファイル名。
実際には、これらの値はユーザーがMySQLとPostgreSQLのどちらを選択するかによって異なります。以下は、PostgreSQLを使用して作成した例です。
KCMのユーザー作成ワークフローを設定
ユーザーワークフローを設定する前に、必ず REQUIRE_ACCOUNT_APPROVAL キーを適切な認証メソッドに設定してください。
PIV/CACの場合は、以下のように ssl に設定してください。
設定が正常に完了すると、以下に示すように、アプリケーションのログイン画面に「Use Certificate or Smart Card」 (証明書またはスマートカードを使用する) リンクが新たに表示されるようになります。
ユーザー作成ワークフローの詳しくは、このページをご参照ください。
認証局のインストール
Keeperコネクションマネージャーにアクセスする必要があるエンドユーザーのクライアントデバイスごとに、信頼できる認証局として内部CAをユーザーのブラウザにインストールすることが必要な場合があります。信頼された認証局のインストールは、プラットフォームによって異なります。
最終更新