シークレットマネージャーの構成

Keeperシークレットマネージャーの構成ファイルに関する情報

概要

KeeperシークレットマネージャーSDKおよび各種インテグレーションでは、「構成」を使用して、接続トークン、暗号化キー、識別子、ドメイン情報などを保持します。これらの情報は、KeeperシークレットマネージャーAPIとの認証およびデータ復号に使用されます。

シークレットマネージャーの構成はワンタイムアクセストークンから作成され、各クライアントデバイスと1対1の関係にあります。

構成フォーマットの統一性

すべてのKeeperシークレットマネージャーSDKおよびインテグレーションは、共通の構成フォーマットを使用します。構成の実体はJSON形式ですが、一部のインテグレーションではbase64形式でも受け付けられます。

シークレットマネージャー構成の作成

Keeperボルトで作成する場合

Keeperボルトで新しいシークレットマネージャーデバイスを作成する際に、シークレットマネージャー構成を作成できます。

まず、シークレットマネージャータブに移動し、一覧からアプリケーションを選択します。

次に、右側のアプリケーションペインにある [デバイス] タブを選択し、[編集] をクリックして編集モードに入ります。

編集ビューから [デバイスの追加] をクリックすると、そのアプリケーションに新しいシークレットマネージャーデバイスを作成できます。

[デバイスの追加] メニューが表示されるので、このデバイスの名前を入力し、方法のドロップダウンから [構成ファイル] を選択します。

「構成ファイル」を選択すると、構成の受け取り方法を選択できます。Base64形式またはJSON形式で構成を生成し、ファイルとしてダウンロードするか、クリップボードにコピーするかを選択できます。

ほとんどのシークレットマネージャー統合機能ではBase64文字列が使用されますが、状況によってはJSONファイルが必要になる場合もあります。

準備ができたら、[ダウンロード] または [コピー] ボタンをクリックして構成を取得します。なお、初回にこの操作を行った時点でデバイスが作成されます。構成は複数回ダウンロードまたはコピーすることができます。

SDK・インテグレーションの使用

多くのKeeperシークレットマネージャーSDKおよびインテグレーションでは、独自の構成ファイルを作成できます。ワンタイムアクセストークンを渡すと、構成が自動的に生成されます。

SDKの例

以下は、Python SDKを使用して構成ファイルを作成する例です。シークレットマネージャーは、ワンタイムアクセストークンを使用して初期化されると、そのタイミングで構成が作成されます。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('config.json')
)

この例では、構成は「config.json」という名前のファイルに保存されています。

SDKを使用して構成ファイルを作成する場合、初期化と構成ファイルの作成は一度だけで構いません。構成ファイルが作成された後は、そのファイルを使用してSDKを初期化できるようになり、ワンタイムアクセストークンは削除しても問題ありません。

統合の例

以下は、KeeperシークレットマネージャーのJenkinsプラグインを使用する例です。

Jenkinsプラグインは、ワンタイムアクセストークンを使用して初期化され、構成ファイルが自動的にバックグラウンドで作成されます。この例では、フォームにワンタイムアクセストークンを入力し、[OK] をクリックするだけで完了します。

CLIツールを使用

シークレットマネージャーの構成は、シークレットマネージャーCLIやコマンダーCLIツールを使用して、ワンタイムアクセストークンから初期化することも可能です。一部のKeeperシークレットマネージャー統合機能では、事前に初期化された構成が必要となるため、そのような場合にはCLIツールを使用して構成を作成する必要があります。

シークレットマネージャーCLI

シークレットマネージャーCLI (KSM) は、ワンタイムアクセストークンから構成を初期化し、構成を作成できます。

そのためには init コマンドを実行します。

形式

# 構成をJSON形式で初期化して表示
$ ksm init default <One Time Access Token>

# 構成をk8s形式で初期化して表示
$ ksm init k8s <One Time Access Token>

# JSON構成を初期化してファイルに保存
$ ksm init default --plain <One Time Access Token> > <FILENAME>

例

コマンダーCLI

コマンダーCLIを使用すると、ワンタイムアクセストークンから構成を初期化し、シークレットマネージャーの構成を作成できます。

構成を作成するには、secrets-manager client add コマンドに --config-init オプションを付けて実行します。構成はJSON形式またはBase64形式で作成できるほか、一部の統合機能では専用形式にも対応しています (各統合機能で使用できる形式については、統合機能のページをご参照ください)。

形式

my vault> secrets-manager client add --app <APP NAME> --config-init <FORMAT>

例

コマンダーで構成を初期化する際は、通常 --unlock-ip オプションをコマンドに含める必要があります。このオプションを指定しない場合、クライアントデバイスはコマンダー実行時のIPアドレスに固定されてしまいます。

バインディングライフサイクル

構成は3つの状態をたどります。ローカルファイル以外の場所に構成を保存する場合は、最初の成功呼び出し後に内容が変わるため、現在どの状態にあるかを把握することが重要です。

• 初期化済み: コンストラクターは実行済みですが、ネットワーク呼び出しはまだ行われていません。構成にはワンタイムトークンが持つ情報のみが含まれます。トークンはまだ引き換えられていません。

• バインド済み: 最初のAPI呼び出し (例: 最初の get_secrets) でワンタイムトークンが引き換えられます。サーバーからの応答が構成に書き戻され、アプリケーションキーとクライアント識別子が追加され、ワンタイムトークンは削除されます。トークンは消費され、再利用できません。

• 再利用: 以降の呼び出し、およびバインド済み構成を読み込む後続プロセスは、保存されたキーで認証し、引き換え処理を省略します。

コンストラクターはKeeperに接続しません。ワンタイムトークンはクライアント作成時ではなく、最初のAPI呼び出しで引き換えられます。そのため、「後で使う」構成を生成する場合は、トークンをバインドするために少なくとも1回の読み取り操作が必要です。

各状態で構成が保持する内容

以下はJSON構成キーです。各キーの暗号化の役割については、セキュリティおよび暗号化モデルをご参照ください。

構成キー	初期化済み	バインド済み	備考
hostname	はい	はい	Keeperリージョン。構成作成時に設定
clientKey	はい	削除	ワンタイムトークンの秘密値 (コンストラクターに渡すトークンは REGION:clientKey)。最初の呼び出しで clientId の導出と appKey のアンラップに使用され、その後削除
privateKey	はい	はい	クライアントデバイスの秘密鍵。すべてのリクエストに署名。削除されない
serverPublicKeyId	任意	はい	伝送ラッパーに使用するKeeper公開鍵を識別
clientId	—	追加	引き換えられたトークンから導出されるクライアントデバイス識別子
appKey	—	追加	シークレットを復号するアプリケーションキー。最初の呼び出しで返却
appOwnerPublicKey	—	返却時に追加	レコードの作成および更新に使用する所有者公開鍵

バインド済み構成の永続化と再構築

構成がローカルファイルではなく外部ストア (データベース、クラウドシークレット、KMSでラップしたBlobなど) に保存される場合は、バインド後に永続化してください。

1. ワンタイムトークンでクライアントを構築します。

2. 1回呼び出します (例: get_secrets) してバインドします。

3. バインド済み構成を読み出し、ストアに保存します。

4. 後続プロセスでは、ストアからバインド済み構成を読み込み、それを使ってクライアントを構築します。トークンは不要です。

初期化済みのままの構成を保存し、そのコピーから2つ目のクライアントを構築すると、両方のクライアントが同じワンタイムトークンの引き換えを試み、成功するのは1つだけです。まず1回成功する呼び出しを行い、バインド後に永続化してください。

import json
from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import InMemoryKeyValueStorage

# my_store is your external store (database, cloud secret, KMS-wrapped blob)

# First run: redeem the token, then read the bound configuration back out
config = InMemoryKeyValueStorage()
sm = SecretsManager(token="US:ONE_TIME_TOKEN", config=config)
sm.get_secrets()                              # binds; the token is consumed here

bound = config.read_storage()                 # dict keyed by configuration field names
my_store.save("ksm-config", json.dumps(bound))

# Later process: rebuild from the bound configuration, no token required
restored = InMemoryKeyValueStorage(my_store.load("ksm-config"))
sm = SecretsManager(config=restored)
secrets = sm.get_secrets()

各SDKページにも、同じ永続化と再構築の手順が、言語ごとのストレージクラスを用いて記載されています。