動的接続

暗号化されたJSON認証を使用して、Keeper Connection Managerを外部データソースと連携

概要

Keeper Connection Managerは、暗号化されたJSONファイルを使用して、任意のカスタムソフトウェアまたはサードパーティ製アプリケーションと連携するように設定できます。このJSONファイルは、同時にユーザーを認証し、リモート接続へのアクセスを許可します。

インストール

動的接続機能を使用するには、Keeper Connection Manager用の暗号化JSON認証モジュールをインストールする必要があります。この機能を有効にするには、keeper/guacamoleイメージ内のDocker ComposeファイルのJSON_*パラメータを更新します。

JSON_SECRET_KEY

JSON_TRUSTED_NETWORKS

これらのパラメータを有効にすると、Keeper Connection Managerの認証拡張機能がロードされます。この拡張機能は、HMAC/SHA-256を使用して署名され、AES-128 CBCで暗号化されたJSONを使用してユーザーを認証します。このJSONには、認証しているユーザーを表す情報がすべて（アクセス可能なすべての接続を含む）含まれているため、この拡張機能は、Keeper Connection Managerを外部アプリケーションと連携する簡単な手段となります。

JSON_SECRET_KEYは128ビットで、以下のように32桁の16進値で指定する必要があります。

4c0b569e4c96df157eee1b65dd0e4d41

この鍵は、予測不能である限り、基本的に何でも指定できます。このような鍵を生成する簡単な方法は、「md5sum」ユーティリティにパスフレーズをechoコマンドで入力することです。これは、パスフレーズから128ビット鍵を生成するためにOpenSSL自体が使用している手法です。以下に例を示します。

$ echo -n "ThisIsATest" | md5sum
4c0b569e4c96df157eee1b65dd0e4d41  -

暗号化されたJSONを既知のマシングループやプライベートサブネットからしか受信しない場合は、JSON_TRUSTED_NETWORKSプロパティを使用して、受信したJSONの受け入れを信頼できるマシンのみにさらに制限することをお勧めします。このフィールドは、信頼できるIPアドレスやCIDRサブネットのコンマ区切りのリストです。以下に例を示します。

127.0.0.0/8, 10.0.0.0/8

JSON形式

JSONの一般的な形式（暗号化されて、署名され、Keeper Connection Managerに送信される前）は以下のとおりです。

{

    "username" : "arbitraryUsername",
    "expires" :TIMESTAMP,
    "connections" : {
        "Connection Name" : {
            "protocol" :"PROTOCOL",
            "parameters" : {
                "name1" : "value1",
                "name2" : "value2",
                ...
            }
        },

        ...

    }

}

...ここで、TIMESTAMPは、ミリ秒の解像度を持つ標準のUNIXエポックタイムスタンプ（UTCの1970年1月1日深夜からの経過ミリ秒数）で、PROTOCOLは、vnc、rdp、sshなどの、Guacamoleがサポートするいずれかのプロトコルの内部名です。

サーバーの時刻がタイムスタンプの時刻を過ぎると、JSONは有効として受け入れられなくなります。タイムスタンプが指定されていない場合、データは失効しません。これは望ましいことですが、慎重に検討せずに指定を省くべきではありません。通常は、タイムスタンプを指定して、暗号化されたJSONの使用を適切な時間間隔に制限し、リプレイ攻撃を防ぐことが重要です。

Keeper Connection Managerに送信する必要のある最上位のJSONオブジェクトには、以下のプロパティがあります。

プロパティ名	型	説明
username	string	JSONによって認証されたユーザーの一意のユーザー名。ユーザーが匿名の場合は、空の文字列（""）にする必要があります。
expires	number	署名が有効であっても、ミリ秒の解像度を持つ標準のUNIXエポックタイムスタンプ（UTCの1970年1月1日深夜からの経過ミリ秒数）として、JSONが受け入れられなくなる絶対時間。
connections	object	対応する一意の名前でユーザーに公開する必要がある接続のセット。ユーザーに公開される接続がない場合は、単に空のオブジェクト（{}）で構いません。

送信された各JSONオブジェクト内で定義された各接続には、以下のプロパティがあります。

プロパティ名	型	説明
protocol	string	サポートされているプロトコルの内部名（vnc、rdp、sshなど）。
parameters	object	Guacamoleのマニュアルに記載されたとおり、接続に適用する接続パラメータの名前と値のペアを表すオブジェクト。

暗号化されたJSONの生成

上記のJSON形式でユーザーを認証するには、Docker ComposeファイルのJSON_SECRET_KEY値で指定された128ビットの同じ秘密鍵を使用して、JSONに署名と暗号化の両方を行う必要があります。

1. 上記の形式でのJSONを生成します。

2. HMAC/SHA-256の秘密鍵（JSON_SECRET_KEYプロパティに格納されているのと同じ128ビット鍵）を使用してJSONに署名します。署名されたプレーンテキストのJSONの先頭に署名プロセスのバイナリの結果を追加します。

3. CBCモードでAESを使用し、初期ベクトル（IV）をすべて0バイトに設定して、上記(2)の結果を暗号化します。

4. 暗号化された結果をbase 64でエンコードします。

5. 暗号化された結果を、dataという名前のHTTPパラメータの値として、/api/tokensRESTエンドポイントにPOSTします（または、dataという名前のクエリパラメータとしてKeeper Connection ManagerページのURLに含めます）。

たとえば、Keeperがkcm.example.comで実行されており、BASE64_RESULTが上記のプロセスの結果である場合、「curl」ユーティリティで実行すると、以下のようになります。

$ curl --data-urlencode "data=BASE64_RESULT" https://kcm.example.com/api/tokens

/api/tokensにPOSTする前、またはURLに含める前に、必ずbase64でエンコードされた結果をURLエンコードしてください。Base64には、URL内で特別な意味を持つ「+」と「=」の両方の文字を使用できます。

データが何らかの形で無効である場合、署名が一致しない場合、復号化または署名の検証が失敗した場合、または送信されたデータの有効期限が切れている場合、RESTサービスは無効なクレデンシャルエラーを返し、ユーザーに説明を表示せずに失敗します。発生したエラーの詳細は、KCMのログに記録されます。