# Ansibleプラグイン ![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-MkdG-_u0H2AJBEVfeYf%2F-MkdG4aCrzLanoVIXeNo%2Fansible-plugin-header.jpg?alt=media\&token=70c9a583-5939-48cc-990b-65c60094663a) ## 機能 * Keeperボルトからシークレットを取得し、Ansible Playbookで利用 * AnsibleからKeeperボルト内のシークレットの値を更新 * Ansibleからレコードを作成 * Keeperボルトからファイルをコピー {% hint style="info" %} Keeperシークレットマネージャーの機能一覧については、[概要ページ](/keeperpam/jp/secrets-manager/overview.md)をご参照ください。 {% endhint %} ## 要件 このページでは、KeeperシークレットマネージャーのAnsible連携について説明します。この連携を利用するには、次のものが必要です。 * Keeperシークレットマネージャーへのアクセス (詳細は[クイックスタートガイド](/keeperpam/jp/secrets-manager/quick-start-guide.md)をご参照ください) * Keeperアカウントでシークレットマネージャーアドオンが有効になっていること * シークレットマネージャーの適用ポリシーが有効なロールのメンバーであること * シークレットが共有されているKeeperの[シークレットマネージャーアプリケーション](/keeperpam/jp/secrets-manager/about/terminology.md#application) * アプリケーションの作成手順は、[クイックスタートガイド](https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/ansible/pages/-MeRAVfQmDBzKQBC0f_c#2.-create-an-application)をご参照ください * 初期化済みのKeeperの[シークレットマネージャー構成](/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md) * Ansible連携では、Base64形式およびJSON形式のいずれの構成も利用できます。 ## インストール Ansibleは柔軟性が高いため、プラグインのインストール先は、使用しているAnsibleの構成やPlaybookの配置場所によって異なります。 ### Keeper Ansibleモジュールのインストール #### Ansible Galaxyを使用したインストール このコレクションは、[Ansible Galaxyのサイト](https://galaxy.ansible.com/ui/repo/published/keepersecurity/keeper_secrets_manager/)で公開されています。次のコマンドでコレクションをインストールできます。 ```bash $ ansible-galaxy collection install keepersecurity.keeper_secrets_manager ``` Ansible Galaxyのコレクションでは長いプラグイン名が使用されます。名前は、コレクション名とプラグイン名を組み合わせたものになります。たとえば、`keeper_copy` プラグインをAnsible Galaxyで使用する場合の名前は `keepersecurity.keeper_secrets_manager.keeper_copy` です。短いプラグイン名を使いたい場合は、Playbookの `collections` ブロックに `keepersecurity.keeper_secrets_manager` を追加します。 ```yaml - name: Keeper Copy hosts: my_hosts collections: - keepersecurity.keeper_secrets_manager tasks: - name: Copy a password keeper_copy: uid: RECORD UID ... ``` {% hint style="info" %} Ansible Galaxyを使用したインストールでは、あらかじめAnsibleがインストールされていることを前提とします。Ansible Galaxyでは依存関係をインストールできません。次の依存関係は、Ansibleが使用するPythonのライブラリまたは仮想環境に対して、pipなどで手動でインストールする必要があります。 * keeper-secrets-manager-core>=17.2.0 * keeper-secrets-manager-helper>=1.1.0 {% endhint %} #### PyPIからのインストール Keeper用のAnsibleモジュールは、次のコマンドでインストールします。モジュールのインストール先のパスを控えておいてください。Ansible Playbookの設定で必要になります。 ```bash $ pip3 install -U keeper_secrets_manager_ansible ``` {% hint style="info" %} Python 3.9以降が必要です。 {% endhint %} 詳細は、[PyPIのページ](https://pypi.org/project/keeper-secrets-manager-ansible/)をご参照ください。 KeeperシークレットマネージャーのAnsibleプラグインのソースコードは、[GitHubリポジトリ](https://github.com/Keeper-Security/secrets-manager/tree/master/integration/keeper_secrets_manager_ansible)で確認できます。 KeeperのAnsibleプラグインは、使用中のPythonのバージョンまたは現在の仮想環境の `site-packages` ディレクトリにインストールされます。次のコマンドでプラグインの場所を確認できます。 ```bash $ keeper_ansible --config # actionプラグインとlookupプラグインへのディレクトリパス ANSIBLE_ACTION_PLUGINS=...site-packages/keeper_secrets_manager_ansible/plugins/action_plugins ANSIBLE_LOOKUP_PLUGINS=...site-packages/keeper_secrets_manager_ansible/plugins/lookup_plugins ``` これらのパスは、*ansible.cfg* で使用できます。 ```ini [defaults] action_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/action_plugins lookup_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/lookup_plugins ``` ### 構成ファイルの生成 このガイドに進む前に、[要件](#prerequisites)をすべて満たし、次のものを用意してください。 * KSMアプリケーションおよび対応する[ワンタイムアクセストークン](/keeperpam/jp/secrets-manager/quick-start-guide.md) * [Keeper Ansibleモジュール](#keeper-ansiblemojrunoinsutru)がインストールされていること Keeperシークレットマネージャー用のAnsibleプラグインを使用するには、[Keeperの構成ファイル](/keeperpam/jp/secrets-manager/about/secrets-manager-configuration.md)が必要です。構成ファイルを取得したら、その値を[Ansibleの変数](#ansible-variables)ファイルに記述できます。これらの変数ファイルはAnsible Vaultで暗号化できます。 Keeper Ansibleモジュールと生成済みのワンタイムアクセストークンを使って、次のコマンドで構成ファイルを生成します。 ```bash $ keeper_ansible --token XX:XXXXXX Config file create at location client-config.json ``` 現在のディレクトリにKeeperのJSON構成ファイルが生成されます。 Pythonモジュールのbinディレクトリが**PATH**環境変数に含まれていない場合は、次のコマンドでも構成ファイルを作成できます。 ```bash $ python3 -m keeper_secrets_manager_ansible --token XX:XXXXXX Config file create at location client-config.json ``` JSON構成ファイルのデフォルト名は `client-config.json` です。内容の例は次のとおりです。 ```json { "appKey" : "XXXXXXXX", "appOwnerPublicKey": "XXXXXXX", "clientId": "XXXXXXXX", "hostname": "XXXXX", "privateKey": "XXXXXXXX", "serverPublicKeyId": "XX" } ``` この構成ファイルにより、Ansible Playbookが認証し、ボルトから指定したシークレットを取得できます。 ### Ansible変数 Keeperシークレットマネージャーのプラグインでは、複数の構成方法を使用できます。たとえば、Base64でエンコードされた構成を利用することも可能です。 ```yaml --- keeper_config: U09NRVRFc2R ... GFzZGFzZGFzZHNhWFQK== ``` Ansibleでは、`client-config.json` を構成ファイルとして直接使用できます。Ansibleの変数で `keeper_config_file` という変数キーを指定します。 ```yaml --- keeper_config_file: /path/to/client-config.json ``` 別の方法として、`client-config.json` に含まれる値をAnsibleの変数ファイルに置けます。たとえば、\_group\_vars、host\_vars、またはタスクファイル\_内に記述できます。 ```yaml --- keeper_app_key: XXXXX keeper_client_id: XXXXX keeper_token: XXXXX keeper_private_key: XXXXX keeper_app_owner_public_key: XXXXX keeper_server_public_key_id: XX ``` セキュリティのため、*group\_vars* または *host\_vars* ファイルはansible-vaultで暗号化できます。 以下は、Keeperプラグインで使用できる有効なAnsible変数です。
Ansible変数JSONキー説明
Ansible変数JSONキー説明
keeper_config--Base64エンコードされた構成文字列です。
keeper_config_file--JSON構成ファイルのパスとファイル名を指定します。現在のディレクトリ以外にある場合や、ファイル名がclient-config.json以外の場合に使用します。
keeper_tokenclientKeyワンタイムアクセストークン(クライアントキーとも呼ばれます)です。構成の初期化時にのみ使用されます。
keeper_client_idclientIdワンタイムアクセストークン使用後にシークレットマネージャーが返すクライアントIDです。必須です。
keeper_app_keyappKeyワンタイムアクセストークン使用後にシークレットマネージャーが返すアプリケーションキーです。必須です。
keeper_private_keyprivateKeyワンタイムアクセストークン使用後にシークレットマネージャーが返す秘密鍵です。必須です。
keeper_app_owner_public_keyappOwnerPublicKeyレコード作成時に使用される公開鍵です。keeper_createプラグインを使用する場合に必須です。
keeper_server_public_key_idserverPublicKeyIdサーバー接続時に使用する公開鍵を指定します。サーバー側で異なる公開鍵が必要な場合はSDKが自動で切り替えます。必須ではありませんが、ウェブサービス呼び出し回数の削減に役立ちます。
keeper_hostnamehostnameシークレットマネージャーのバックエンドホスト名です。デフォルトはUSです。Keeperのデータセンターの場所に応じて、US、EU、AU、US_GOVを指定できます。必須です。
keeper_log_level--SDKのログレベルを設定します。指定可能な値はDEBUG、INFO、WARNING、ERROR、CRITICALです。デフォルトはERRORです。
keeper_record_cache_secret--keeper_cache_recordsアクションで必須です。キャッシュ内のレコードを暗号化するために使用されます。この値はPlaybook内で生成できます。アクションの例をご参照ください。
keeper_use_cache--ボルトのキャッシュを使用します。デフォルトはFalseです。キャッシュファイルは、ネットワーク障害時のバックアップとしてのみ使用されます。
keeper_cache_dir--キャッシュファイルの読み書きを行うディレクトリを指定します。
keeper_record_types--Keeperコマンダーのレコードタイプ定義の一覧です。
{% hint style="info" %} プラグインには2種類のキャッシュ方法があります。同じものではありません。\ \ `keeper_record_cache_secret` は、Playbookの実行中にレコードをキャッシュするために使用します。Playbookの実行が終わるとキャッシュは削除されます。キャッシュは暗号化された状態でメモリに保持されます。このキャッシュにより、KeeperシークレットマネージャーサービスへのAPI呼び出し回数を減らせます。メモリに保持されるため、取得するレコードが増えるほど、消費するメモリ量も増えます。\ \ `keeper_use_cache` と `keeper_cache_dir` は、Keeperボルトの障害時バックアップ用キャッシュに使います。Keeperシークレットマネージャーに接続できないときの取得先として使われます。キャッシュは暗号化されたままディスクに保存されます。 {% endhint %} ### **コマンドライン変数** 任意の方法として、`ansible-playbook` の実行時に値を渡せます。例を次に示します。 ```bash $ ansible-playbook my_playbook.yml \ -e "keeper_app_key=XXXXX" \ -e "keeper_client_id=XXXXX" \ -e "keeper_token=XXXXX" \ -e "keeper_private_key=XXXXX" ``` ## Ansibleプラグインの使用方法 Keeperには、11個のアクションプラグインと1つのルックアッププラグインがあります。 すべてのプラグインに共通する引数は次のとおりです。`uid` または `title` の指定が必要です。 * `uid` - 取得したいレコードのレコードUID * `title` - 取得したいレコードのレコードタイトル * `field` - レコードから、指定したラベルの値を取得します * `custom_field` - レコードから、指定したカスタムフィールド名の値を取得します * `file` - レコードから、指定した名前のファイルを取得します プラグインによっては、`uid` に加えて `field` または `file` の指定も必要です。 {% hint style="info" %} 特定のボルトシークレットで利用可能なフィールドやカスタムフィールドを確認するには、KeeperシークレットマネージャーCLIの `ksm secret get -u XXXX` コマンドを使います。詳細は[こちら](/keeperpam/jp/secrets-manager/secrets-manager-command-line-interface/secret-command.md#secret-command)をご参照ください。 {% endhint %} {% hint style="info" %} プラグインの例では短いプラグイン名を使用しています。Ansible Galaxy経由でコレクションをインストールした場合は、長いプラグイン名を使うか、Playbookで使用するコレクションの一覧にコレクション名を追加する必要があります。 {% endhint %} アクションでは、[Keeper表記法](/keeperpam/jp/secrets-manager/about/keeper-notation.md)を使うか、レコードのUIDまたはタイトルと、タスク属性の `array_index` および `value_key` を組み合わせて、特定の値を取得できます。 たとえば、電話番号のように複雑な値は、オブジェクトの配列として表現されます。 ```json [ { 'number': '(555) 123-1234', 'type': 'Work', 'ext': '11' }, { 'region': 'AD', 'number': '111-2223333', 'ext': '5555', 'type': 'Mobile' } ] ``` 次の例では、**Keeper表記法**と `array_index` および `value_key` を使って、同じ結果を得る方法を示します。 ```yaml --- - name: Keeper Get hosts: my_hosts # Include line below if installed via ansible galaxy or use long plugin names. # collections: # - keepersecurity.keeper_secrets_manager tasks: - name: Get the second phone number using Keeper Notation keeper_get: notation: "RECORD UID/field/phone[1][number]" register: second_number_notation - name: Get the second phone number using array_index and value_key keeper_get: uid: "RECORD UID" field: phone array_index: 1 value_key: "number" register: second_number_non_notation ``` ### プラグイン: `keeper_cache_records` `keeper_cache_records` プラグインは、指定した数のレコードを取得してキャッシュに保存します。このキャッシュは、後続の他のアクションから利用できます。あらかじめ必要なレコードをまとめて取得しておくことで、API呼び出しの回数を抑えることが目的です。 ```yaml --- - name: Cache records hosts: my_hosts # Include line below if installed via ansible galaxy or use long plugin names. # collections: # - keepersecurity.keeper_secrets_manager tasks: - name: Generate a Keeper Record Cache secret keeper_password: length: 64 register: generated_password no_log: True - name: Store the Keeper Record Cache secret into variables. set_fact: keeper_record_cache_secret: "{{ generated_password.password }}" no_log: True - name: Cache records. Will use keeper_record_cache_secret from above. keeper_cache_records: uids: - RECORD UID - RECORD UID titles: - My Record Title - My Record Title Too register: my_records no_log: True - name: Copy a file keeper_copy: cache: "{{ my_records.cache }}" uid: RECORD UID file: my_cert_file.crt dest: /etc/special.crt owner: root group: root mode: "0644" backup: yes ``` レコードは、レコードUIDまたはレコードタイトルを指定して取得できます。アクションの実行結果は、レコードを暗号化してシリアライズしたデータとして返されます。この結果は、他のアクションから利用できるように、Ansibleの `register` 変数に保存してください。暗号化されたシリアライズデータは非常に長くなる場合があります。セキュリティの確保とログ出力の抑制のため、`no_log` を**True**に設定することを推奨します。 `keeper_cache_records` はレコードのみをキャッシュします。添付ファイルはキャッシュされません。キャッシュから取得したレコードに含まれる添付ファイルを別のアクションで取得しようとした場合、その際にAPI呼び出しが行われ、ファイルがダウンロードされます。 他のアクションでは、テンプレートで属性を設定します (例: `cache: "{{ my_records.cache }}"`)。 `keeper_cache_records` を使用するには、`keeper_record_cache_secret` が設定されている必要があります。この値は、ホスト変数、グループ変数、タスク変数として設定するか、タスク内で生成した後にfact (変数) として設定できます。上記の例では、`keeper_password` アクションでパスワードを生成し、それを `keeper_record_cache_secret` として保存しています。シークレットがログに出力されないよう、`no_log` を**True**に設定しています。 キャッシュの内容は自動的には更新されません。キャッシュ生成後に作成または更新されたレコードは含まれません。新しいレコードや変更内容を反映させるには、再度 `keeper_cache_records` を実行する必要があります。 #### 必須属性 * `uids` - Keeperボルト内のレコードUIDのリスト。 * `titles` - Keeperボルト内のレコードタイトルのリスト `uids` と `titles` は同時に指定できますが、いずれか一方は必ず設定する必要があります。 ### プラグイン: `keeper_copy` `keeper_copy` はAnsibleの[組み込みcopyプラグイン](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/copy_module.html)を拡張したものです。以下はその例です。 ```yaml --- - name: Keeper Copy hosts: my_hosts # Include line below if installed via ansible galaxy or use long plugin names. # collections: # - keepersecurity.keeper_secrets_manager tasks: - name: Copy a password. keeper_copy: uid: RECORD UID field: password dest: /tmp/my_password mode: "0600" - name: Copy a file keeper_copy: uid: RECORD UID file: my_cert_file.crt dest: /etc/special.crt owner: root group: root mode: "0644" backup: yes - name: Copy record notes to file keeper_copy: uid: RECORD UID notes: yes dest: /tmp/record_notes.txt mode: "0600" ``` これらの例では、Keeperボルトのレコードに保存されているパスワードを取得し、リモートシステム上の `/tmp/my_password` に書き込みます。Ansible組み込みのcopyプラグインの `mode` 属性でファイルの権限を変更します。 最後のタスク例では、Keeperボルトのレコードから「*my\_cert\_file.crt*」を取得し、「*/tmp/special.crt*」の場所に保存します。組み込みcopyプラグインの複数の機能がファイルに適用されます。 #### 必須属性 * `uid` - Keeperボルト内のレコードUID * `title` - Keeperボルト内のレコードのタイトル * `notation` - Keeper表記法を使ってレコード内のフィールドを取得します `uids` と `titles` は同時に指定できますが、少なくともいずれか一方を設定する必要があります。 #### 任意属性 * `cache` - `keeper_cache_records` アクションで作成したレコードキャッシュ * `field` - Keeperボルトの標準レコードから内容を取得します * `custom_field` - Keeperボルトのカスタムレコードから内容を取得します * `file` - Keeperボルトのレコードに添付されたファイルのうち、ファイルタイトルで内容を取得します * `notes` - `yes` に設定すると、レコードのノート欄をコピーします。ノート欄にはレコードに添付されたテキストノートが含まれます。ノートはシングルトンフィールド（レコードにつき1つ）のため、フィールド名ではなくブールフラグを使います。v1.3.0で追加。 * `array_index` - 既定値は0です。フィールドの値に複数の要素がある場合に、返す要素を選択します。最初の要素は `array_index` **0**、次は**1**、というように指定します。 * `value_key` - フィールドの値が複雑なオブジェクトの場合に、返すキーと値のペアのうちどのキーを選ぶかを指定します。 その他の任意属性は、[組み込みcopyプラグイン](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/copy_module.html)と同じものを指定できます。`src`、`remote_src`、`content` は使用できず、指定しても無視されます。 ### プラグイン: `keeper_get` {% hint style="success" %} **v1.3.0の新機能**: `notes` パラメータでレコードのノートを取得できるようになりました。 {% endhint %} `keeper_get` プラグインは、Keeperボルトのレコードからフィールドまたはファイルを取得します。以下はその例です。 ```yaml --- - name: Keeper Get hosts: my_hosts # Include line below if installed via ansible galaxy or use long plugin names. # collections: # - keepersecurity.keeper_secrets_manager tasks: - name: Get login name. Loading record from Keeper Vault. keeper_get: uid: RECORD UID field: login register: my_login - name: Print login name debug: var: my_login.value verbosity: 0 - name: Make a sudoer copy: dest: "/etc/sudoers.d/{{ my_login.value }}" content: | # Auto added by Ansible {{ my_login.value }} ALL=(ALL:ALL) ALL - name: Get record notes keeper_get: uid: RECORD UID notes: yes register: my_notes - name: Display notes debug: var: my_notes.value - name: Write notes to file copy: content: "{{ my_notes.value }}" dest: /tmp/record_notes.txt ``` `keeper_get` プラグインはディクショナリを返します。ディクショナリの `value` キーに、取得したフィールドまたはファイルの内容が入ります。通常はAnsibleの `register` と組み合わせ、返された値をメモリに保持し、他のタスクから参照します。 上記の例では、ユーザーのログイン名を含むレコードを取得し、ログイン名を `my_login` に保存します。2つ目のタスクはデバッグ用にコンソールへ出力し、3つ目のタスクはそのログイン名でsudoersエントリを追加します。 #### 必須属性 * `uid` - Keeperボルト内のレコードUID。 * `title` - Keeperボルト内のレコードのタイトル。 * `notation` - Keeper表記法を使ってレコード内のフィールドを取得します。 `uids` と `titles` は同時に指定できますが、少なくともいずれか一方を設定する必要があります。 #### 任意属性 * `cache` - `keeper_cache_records` アクションで作成したレコードキャッシュ。 * `field` - Keeperボルトの標準レコードから値を取得します。 * `custom_field` - Keeperボルトのカスタムレコードから値を取得します。 * `file` - Keeperボルトのレコードに添付されたファイルのうち、ファイルタイトルで値を取得します。 * `notes` - `yes` に設定すると、レコードのノート欄を取得します。ノート欄にはレコードに添付されたテキストノートが含まれます。他のフィールドとは異なり、ノートはシングルトンフィールド（レコードにつき1つ）のため、フィールド名ではなくブールフラグを使います。v1.3.0で追加。 * `allow_array` - 既定値は**False**です。**True**にすると値を配列で返します。電話番号のようにフィールドに複数の値がある場合に必要です。**True**のとき、`array_index` と `value_key` は無視されます。 * `array_index` - 既定値は0です。フィールドの値に複数の要素がある場合に、返す要素を選びます。最初の要素は0、次は1、というように指定します。 * `value_key` - フィールドの値が複雑なオブジェクトの場合に、返すキーと値のペアのうちどのキーを選ぶかを指定します。 {% hint style="info" %} レコードのノートを**更新**するには、[`keeper_set`](#plugin-keeper_set) プラグインで `notes: yes` と `value:` を指定します。 {% endhint %} ### プラグイン: `keeper_get_record` `keeper_get_record` プラグインは、レコードに含まれるすべてのフィールドを取得し、ディクショナリ形式で返します。使用例は次のとおりです。 ```yaml --- - name: Keeper Get Record hosts: my_hosts # Include line below if installed via ansible galaxy or use long plugin names. # collections: # - keepersecurity.keeper_secrets_manager tasks: - name: Get a record from the vault. keeper_get_record: uid: RECORD UID allow: - login - password register: my_record - name: Print login name debug: var: my_record.record.login[0] verbosity: 0 ``` `keeper_get_record` プラグインは、ディクショナリ形式の結果を返します。ディクショナリのキーには、正規化されたフィールドラベルまたはタイプが使用され、英数字とアンダースコアで構成されます。同じキーが重複する場合は、キーの末尾に番号が付加されます。 上記の例では、UIDを指定してレコードを取得し、そのフィールドを `register` を使ってメモリ上のディクショナリとして保存しています。`allow` 属性を指定しているため、ディクショナリには**login**と**password**のみが含まれます。各フィールドの値は、Ansibleの通常のテンプレート構文で参照できます。なお、`phone` のように複数の値を返すフィールドがあるため、値は配列として格納されます。 #### 必須属性 * `uid` - Keeperボルト内のレコードUID。 * `title` - Keeperボルト内のレコードタイトル。 `uid` または `title` のいずれかを必ず指定する必要があります。 #### 任意属性 * `cache` - `keeper_cache_records` アクションで作成したレコードキャッシュを指定します。 * `allow` - 取得を許可するキーのリストを指定します。この属性を設定した場合、リストに含まれないキーはディクショナリに含まれません。 ### プラグイン: `keeper_set` `keeper_set` プラグインは、既存のKeeperボルトのレコードに値を書き込めます。 {% hint style="success" %} **v1.3.0の新機能**: `keeper_set` で `notes: yes` と `value:` を指定すると、レコードのノート欄を更新できます。 {% endhint %} {% hint style="info" %} レコードのノートを**取得**するには、[`keeper_get`](#plugin-keeper_get) プラグインで `notes: yes` を指定します。 {% endhint %} 例を次に示します。 ```yaml --- - name: Keeper Set hosts: my_hosts # Include line below if installed via ansible galaxy or use long plugin names. # collections: # - keepersecurity.keeper_secrets_manager tasks: - name: Get login name of new user. keeper_get: uid: RECORD UID field: login register: my_login - name: Add new user of remote machine. user: name: "{{ my_login.value }}" comment: "User {{ my_login.value }}" register: new_user - name: Update record with user's home directory in the Keeper Vault keeper_set: uid: RECORD UID custom_field: my_home_directory value: "{{ new_user.home }}" - name: Update Record Notes keeper_set: uid: RECORD UID notes: yes value: "Updated by Ansible on {{ ansible_date_time.iso8601 }}" ``` この例では、新しいユーザーのログイン名を取得します。そのログイン名でリモートにユーザーを作成し、続いてリモートマシンのホームディレクトリをレコードに書き戻します。 `keeper_set` アクションは、配列や複雑な値の一部だけを更新する機能はありません。既存の値を新しい値で置き換えます。たとえば**Hostname and Port**フィールドタイプではポートだけを更新することはできず、**hostName**を含むオブジェクト全体を指定する必要があります。 `keeper_set` はボルト内のレコードを更新しますが、使用中のキャッシュは更新しません。キャッシュを更新するには、変更したレコードの**UID**または**Title**で `keeper_cache_records` を再度実行します。 #### 必須属性 * `uid` - Keeperボルト内のレコードUID。 * `title` - Keeperボルト内のレコードのタイトル。 * `notation` - Keeper表記法を使ってレコード内のフィールドを指定します。 `uids` と `titles` は同時に指定できますが、少なくともいずれか一方を設定する必要があります。 #### 任意属性 * `field` - 既存のKeeperボルトの標準フィールドを更新します。 * `custom_field` - 既存のKeeperボルトのカスタムフィールドを更新します。 * `notes` - `yes` に設定すると、レコードのノート欄を更新します。ノート欄にはレコードに添付されたテキストノートが含まれます。ノートはシングルトンフィールド（レコードにつき1つ）のため、フィールド名ではなくブールフラグを使います。v1.3.0で追加。 * `value` - レコードのフィールドに書き込む新しい値。 ### プラグイン: `keeper_create` `keeper_create` プラグインは、Keeperボルトにレコードを作成します。利用可能なレコードタイプとレコードを構成するフィールドタイプは、[フィールド/レコードタイプ](/keeperpam/jp/secrets-manager/about/field-record-types.md)をご参照ください。作成に成功すると、アクションプラグインは `record_uid` を返します。 {% hint style="info" %} レコードを作成するには、Ansible変数 `keeper_app_owner_public_key` が必要です。`client-config.json` では JSON キー `appOwnerPublicKey` に対応します。このキーが構成に含まれていない場合は、新しいワンタイムアクセストークンを作成して初期化してください。 {% endhint %} 例を次に示します。 ```yaml --- - name: Keeper Create hosts: my_hosts tasks: - name: "Create A Record" keeper_create: shared_folder_uid: XXXXXX record_type: login generate_password: True password_complexity: length: 64 allow_symbols: False title: "My New Record" notes: "Created by Ansible" version: v3 fields: - type: login value: johndoe@localhost - type: url value: https://localhost custom_fields: - type: text label: "My Custom Label" value: "My custom value" register: my_new_record - name: "New Record UID" debug: msg: "New record uid is {{ my_new_record.record_uid }}" ``` 次のフィールドは必須です。 * `shared_folder_uid` - ボルトの共有フォルダUID。レコードはこのフォルダ内に作成されます。 * `record_type` - レコードのタイプです。既定のレコードタイプがすべて含まれます。`keeper_record_types` が設定されている場合は、そのレコードタイプも使用できます。 * `title` - レコードのタイトル。 次のフィールドは任意です。 * `version` - 使用するレコードスキーマのバージョン。既定は `v3`（推奨）。`v2` または `v3` を指定できます。v1.1.2以降で利用可能。 * `generate_password` - True にすると、パスワード未設定のパスワードフィールドにランダム生成パスワードが入ります。 * `password_complexity` - パスワードの複雑さ。`password_complexity` の各パラメータは任意です。 * `length` - パスワードの長さ。既定は**64**。 * `allow_lowercase` - 既定は**True**。**False**にすると小文字を使いません。 * `allow_uppercase` - 既定は**True**。**False**にすると大文字を使いません。 * `allow_digits` - 既定は**True**。**False**にすると数字を使いません。 * `allow_symbols` - 既定は True。**False**にすると記号を使いません。 * `filter_characters` - パスワードから除外する文字のリスト。サービスが拒否する文字を除きたい場合に使います (例: SQL の「%」)。未設定ならフィルタしません。 * `notes` - レコードにノートを添付します。 {% hint style="info" %} パスワード生成では、概ね次の記号が含まれます。`!@#$%()+;<>=?\[]{}^.,` などです。 {% endhint %} レコードタイプによっては追加の必須フィールドがあります。カスタムフィールドは任意です。`fields` と `custom_fields` はいずれも値の配列です。 * `fields` / `custom_fields` * `type` - フィールドタイプ * `label` - 値とともに表示するラベル * `value` - フィールドの値。フィールドタイプに応じて文字列またはディクショナリ #### カスタムレコードタイプを作成 特定のカスタムレコードタイプを使用してレコードを作成するには、まずKeeperコマンダーの `record-type-info` コマンドを使用して、カスタムレコードタイプをエクスポートします。KSMではカスタムタイプ定義が同期されないため、取得した定義を変数としてプレイブックに直接追加する必要があります。 KeeperコマンダーはJSON配列 ("content") を出力しますが、必要なのはその中のJSONオブジェクトのみです。 使用例は次のとおりです。 ``` My Vault> record-type-info --format json -lr "My Custom" [ { "recordTypeId": 18, "content": "{\"$id\":\"My Custom\",\"categories\":[\"login\"], \"description\":\"SSH key template\",\"fields\":[ {\"$ref\":\"login\"}, {\"$ref\":\"keyPair\"}, {\"$ref\":\"password\",\"label\":\"passphrase\"}, {\"$ref\":\"host\"}, {\"$ref\":\"fileRef\"}]}" } ] ``` AnsibleのYAMLファイルでは、「content」オブジェクトの値を `keeper_record_types` という変数キーに追加します。この変数は配列として定義し、JSONは文字列として扱います。配列の要素の後にパイプ(|)を付けることで、後続のJSON全体を文字列として扱えます。`keeper_record_types` には、複数のレコードタイプを指定できます。 使用例は次のとおりです。 ```yaml - name: My Playbook collections: - keepersecurity.keeper_secrets_manager hosts: "my_hosts" vars: keeper_record_types: - | { "recordTypeId": 35, "content": "{\"$id\":\"My Custom\",\"fields\":[{\"$ref\":\"fileRef\",\"label\":\"File or Photo\"},{\"$ref\":\"login\",\"label\":\"Login\"},{\"$ref\":\"password\",\"label\":\"Password\",\"required\":true,\"enforceGeneration\":false,\"privacyScreen\":false,\"complexity\":{\"length\":8,\"caps\":0,\"lowercase\":0,\"digits\":0,\"special\":0}},{\"$ref\":\"text\",\"label\":\"System Login\",\"required\":true},{\"$ref\":\"secret\",\"label\":\"System Password / Pin Code\"},{\"$ref\":\"url\",\"label\":\"Keeper VPN Wiki\",\"required\":true},{\"$ref\":\"url\",\"label\":\"Password Best Practices FAQ's and Tips\",\"required\":true}]}" } ``` 正しく設定できているかを確認するには、`keeper_info` プラグインを使用して、利用可能なレコードタイプを表示できます。 特定のカスタムタイプのレコードを作成する場合は、次の例のように、Ansible タスクの `record_type` パラメータでレコードタイプ名を指定します。 ```yaml - name: "Create A Custom Record" keeper_create: shared_folder_uid: XXXXXXXXXXXX record_type: "My Custom" title: "Example Custom Record" notes: "Created by Ansible" fields: - type: login label: Login value: johndoe@localhost - type: password label: Password value: "ABC123" register: my_new_record ``` ### プラグイン: `keeper_remove` v1.2.1\ リリース日: 2023年10月27日 Keeperボルト内のレコードを削除できます。 ```yaml --- - name: Keeper Remove hosts: my_hosts tasks: - name: Remove by UID keeper_remove: uid: RECORD UID - name: Remove by Title keeper_remove: title: RECORD TITLE ``` #### 必須属性 * `uid` - Keeperボルト内のレコードUID。 * `title` - Keeperボルト内のレコードタイトル。 `uid` と `title` は同時に指定できませんが、いずれか一方は必ず設定する必要があります。 #### 任意の属性 * `cache` - `keeper_cache_records` アクションで作成したレコードキャッシュを指定します。このキャッシュからレコードが削除されることはありません。レコードタイトルの参照にのみ使用されます。 ### プラグイン: `keeper_password` `keeper_password` プラグインはランダムなパスワードを生成します。アクションプラグインは `password` を返します。 例を次に示します。 ```yaml --- - name: Keeper Password hosts: my_hosts tasks: - name: Generate a long password keeper_password: length: 128 register: long_password - name: Show long password debug: msg: "Long password {{ long_password.password }}" - name: Generate an all digit password keeper_password: length: 32 allow_lowercase: False allow_uppercase: False allow_symbols: False register: digit_password - name: Show digit password debug: msg: "Digit password {{ digit_password.password }}" - name: Generate a PostgreSQL password (no % character) keeper_password: length: 64 filter_characters: - "%" register: pg_password - name: Show PostgreSQL password debug: msg: "PG password {{ pg_password.password }}" ``` パラメータはすべて任意です。いずれも未指定のときはデフォルト値が使われます。 * `length` - パスワードの長さ。デフォルトは**64**です。 * `allow_lowercase` - デフォルトは**True**です。**False**に設定すると、小文字は使用されません。 * `allow_uppercase` - デフォルトは**True**です。**False**に設定すると、大文字は使用されません。 * `allow_digits` - デフォルトは**True**です。**False**に設定すると、数字は使用されません。 * `allow_symbols` - デフォルトはTrueです。**False**に設定すると、記号は使用されません。 * `filter_characters` - パスワードから除外する文字のリスト。これにより、サービスが拒否する文字を削除できます。たとえば、SQLの「%」などです。設定しない場合、パスワードはフィルタリングされません。 {% hint style="info" %} パスワード生成では、概ね次の記号が含まれます。`!@#$%()+;<>=?\[]{}^.,` などです。 {% endhint %} レコードタイプに応じて、特定のフィールドが必須になる場合があります。カスタムフィールドは任意です。`fields` と `custom_fields` はいずれも値の配列です。 ### プラグイン: `keeper_lookup` `keeper_lookup` プラグインは、Keeperボルトのレコードからフィールドを取得し、その値をテキスト文字列に挿入します。 例を次に示します。 ```yaml --- - name: Keeper Lookup hosts: my_hosts tasks: - name: Write login to file. Get record from the Keeper Vault copy: content: "My login is {{ lookup('keeper', uid='RECORD UID', field='login') }}" dest: "/tmp/my_login.txt" no_log: True - name: Using the array_index and value_key on complex values debug: msg: >- Second phone number is {{ lookup('keeper', uid='RECORD UID', custom_field='My Phone', array_index=1, value_key='number') }} ``` 上の例では、最初のタスクでKeeperのレコードからユーザーのログイン名をテンプレート化することによってファイルの内容が作成されます。 2つ目のタスクでは、`array_index` および `value_key` のタスク属性で、複合値を持つフィールドの2番目の電話番号をデバッグ出力します。`array_index` は 0 から始まり、配列の次の要素は 1、その次は 2、という順になります。`value_key` は、キーと値のペアを持つオブジェクトにおけるキー名です。 #### 必須の属性 * `uid` - Keeperボルト内のレコードUID * `title` - Keeperボルト内のレコードのタイトル * `notation` - Keeper表記法を使ってレコードからフィールドを取得します `uids` と `titles` は同時に使用できます。少なくともどちらか一方が設定されている必要があります。 #### 任意の属性 * `cache` - レコードのキャッシュ。複数レコード取得に使用します。キャッシュは更新されません。 * `field` - Keeperボルトの標準レコードから値を取得します * `custom_field` - Keeperボルトのカスタムレコードから値を取得します * `file` - ファイルタイトルを指定して、Keeperボルトのレコードに添付されたファイルから値を取得します * `allow_array` - デフォルトは**False**。**True** のとき値の配列が返されます。電話番号のように複数値を持つフィールド向けです。**True** の場合、`array_index` と `value_key` は無視されます。 * `array_index` - デフォルトは 0。フィールドに複数の値がある場合に、返す要素を選びます。先頭は `array_index` **0**、次は **1**、という順です。 * `value_key` - フィールドの値が複合オブジェクトの場合、キーと値の対のキーを返すよう選択できます。 #### 重要な注意事項 * lookupプラグインを使用するときにシークレット値の漏洩を防ぐには、「no\_log:True」をタスクに追加します。値がTrueの場合、標準出力情報はログに記録されません。 * プラグインをAnsible Galaxyからインストールした場合は、lookupプラグインに長い名前（keepersecurity.keeper\_secrets\_manager.keeper）が必要です。コレクションの一覧表示は、lookupプラグインでは動作しないようです。 * 特定のボルトのシークレットで使用できるフィールドおよびカスタムフィールドを確認するには、KeeperシークレットマネージャーCLIの `ksm secret get -u XXXX` コマンドを使います。詳細は[こちら](/keeperpam/jp/secrets-manager/secrets-manager-command-line-interface/secret-command.md#secret-command)をご参照ください。 ### プラグイン: `keeper_init` `keeper_init` プラグインは、ワンタイムアクセストークンから構成を初期化します。`keeper_ansible --keeper_token` コマンドに相当します。次のオプションを指定できます。 * `token` - ワンタイムアクセストークン。この値はテンプレート化して、値で渡すことをお勧めします。 * `filename` - 設定値で生成する設定ファイルの名前。指定されていない場合、設定は作成されません。 * `show_config` - 設定値をタスクのログに返すべきか否かを示すフラグ。デフォルトは`False`です。他の方法で設定を生成できない場合、または生成された設定ファイルにアクセスできない場合にのみ、Trueに設定します。Trueの場合、設定がログに出力されます。コマンドラインからプレイブックを実行する分には問題になりにくいですが、Ansible Tower経由ではログに残る点に注意してください。 ```yaml --- - name: Keeper Lookup hosts: localhost connection: local tasks: - name: Init the one time access token keeper_init: token: "{{ keeper_token }}" filename: "{{ keeper_config_file }}" show_config: False ``` 有効なのは1回だけなので、トークンをプレイブックにハードコードしないことをお勧めします。トークンと設定ファイル名は、`extra vars`を使用してプレイブックに渡すことができます。 ```bash $ ansible-playbook my_init_playbook.yml \ -e "keeper_token=US:XXX" \ -e "keeper_config_file=my_keeper_config.yml" ``` 前のコマンドを実行すると、次のようなファイルが生成されます。内容は Ansible 用の設定ファイルに転記でき、必要に応じて `ansible-vault` で暗号化できます。 ``` keeper_app_key: +U5Ja ...5FmXymVI= keeper_client_id:Fokc ...WBdUPxPlBwzAKlMUgFZHqLg== keeper_hostname:US keeper_private_key:MIGHA ... yA7Oy keeper_server_public_key_id:'10' ``` #### Ansible Galaxyロール Keeperシークレットマネージャープラグインを Ansible Galaxy からインストールした場合、`keeper_init_token` ロールも入り、ワンタイムアクセストークンを初期化できます。プレイブックから利用します。 ```yaml --- - name: Initialize One Time Access Token hosts: localhost connection: local collections: keepersecurity.keeper_secrets_manager roles: - keeper_init_token ``` このロールは、追加変数で次のオプションを受け取ります。 * `keeper_token` - 必要なワンタイムアクセストークン。 * `keeper_config_file` - 設定を含むファイルを生成します。設定しない場合、ファイルは作成されません。 * `keeper_show_config` *= デフォルトはFalseです。Trueに設定すると、詳細出力が有効になっている場合、ログに設定が表示されます。* `keeper_config_file` または `keeper_show_config` のいずれかを指定してください。指定しないとトークンは消費されるだけで、生成された構成を確認できません。 ### プラグイン: `keeper_info` `keeper_info` アクションは、Keeper Ansible プラグインの情報を表示します。結果にはレコードタイプ、フィールドタイプ、Python モジュールのバージョン一覧が含まれます。表示するには詳細レベルを 1 以上にしてください。 ```yaml --- - name: Keeper Info hosts: localhost connection: local tasks: - name: Display Keeper Info keeper_info: ``` これで、カスタムレコードタイプがプラグインに認識されているかを確認できます。 ### プラグイン: `keeper_cleanup` `keeper_cleanup` プラグインは、Keeper 系プラグインが作成したファイル（主にキャッシュ）を削除します。ネットワーク障害時にレコード取得へフォールバックするキャッシュ向けです。シークレット運用で必ずしも削除する必要はありませんが、削除したい場合に使います。 ```yaml - name: Keeper Lookup hosts: localhost connection: local vars: keeper_use_cache: True tasks: ... bunch of tasks - name: Remove the cache file keeper_cleanup: ``` ### プラグイン: `keeper_redact` `keeper_redact` 標準出力コールバックプラグインは、標準出力ログ上のシークレットを編集してマスクします。`keeper_copy` および `keeper_get` の出力が対象です。`keeper_lookup` の値はマスクされないため、タスクに `no_log: True` を指定してください。 {% hint style="info" %} [プレイブックでシークレットデータを保存する方法](https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#keep-secret-data)をご参照ください。`no_log` を使うとタスク全体のログを抑止できます。本プラグインは、Keeperシークレットマネージャー系プラグインが返したシークレットだけを標準出力からマスクしたいときに使います。 {% endhint %} {% hint style="info" %} `keeper_redact` プラグインは Ansible Tower では利用できません。Tower がジョブのログ用に独自の標準出力コールバックを使うためです。ログへの露出を抑えたい場合は、Tower 上でも `no_log` の利用を強く推奨します。 {% endhint %} `keeper_redact` プラグインを使うには、*ansible.cfg* で有効にします。 ```ini [defaults] stdout_callback = keeper_redact # Use long name if install via Ansible Galaxy # stdout_callback = keepersecurity.keeper_secrets_manager.keeper_redact ``` たとえば、次のタスクはカスタムフィールド `MyPhoneNumbers` の電話番号をすべて返し、変数 `phone_numbers` に格納します。 ```yaml - name: "Get Phone Numbers" keeper_get: uid: OlLZ6JLjnyMOS3CiIPHBjw custom_field: MyPhoneNumbers allow_array: True register: phone_numbers ``` プレイブックを詳細付きで実行すると、変数に入れた値が表示され、シークレットがログに残るおそれがあります。`keeper_redact` 標準出力コールバックを有効にすると、ログ上の値がマスクされます。 ```bash TASK [Get Phone Numbers] ************************************************** ok: [my_server] => { "value": [ { "number": "****", "type": "****", "ext": "****" }, { "region": "****", "number": "****", "ext": "****", "type": "****" } ], "changed": false } ``` ## Ansibleボルトパスワードの取得 Keeper Secrets Manager CLI（「ksm」）を使用して、Ansibleボルトの復号化パスワードを設定できます。そのためには、ANSIBLE\_VAULT\_PASSWORD\_FILE環境変数またはansible.cfgフィールドのvault\_password\_fileを使用して、パスワードを返す実行可能ファイルを指定します。 「ksm」のシークレット表記法を使ってパスワードを返す実行可能シェルスクリプトを作成できます（ksm のシークレット表記法の[詳細](/keeperpam/jp/secrets-manager/secrets-manager-command-line-interface/secret-command.md#notation)）。たとえば、次のスクリプトは、指定したレコードUIDのシークレットパスワードを出力します。 ```bash #!/bin/sh ksm secret notation keeper://XXXX/field/password ``` XXXX をボルトのレコードUIDに置き換えます。このスクリプトを実行すると、シークレットのパスワードが出力されます。 環境変数 `ANSIBLE_VAULT_PASSWORD_FILE` を上書きするには、次を実行し、`/path/to/script` を上記スクリプトのパスに置き換えます。 ```bash $ ANSIBLE_VAULT_PASSWORD_FILE=/path/to/script.sh ansible-playbook playbook_with_vault.yml ``` これで、`playbook_with_vault.yml`で使用されているボルトを復号化する必要がある場合は、Ansibleはそのシェルスクリプトを実行します。このシェルスクリプトはKeeperボルトからパスワードを取得します。 ## ログ出力 デフォルトでは、Ansibleプラグインはエラーのみを表示します。Ansibleの詳細出力レベルを使用すると、SDKの様々なログが表示されます。Ansibleの詳細出力レベルを`-v`にすると、INFOレベル以上のSDKメッセージが表示されるのに対し、詳細出力レベルを`-vvv`にするとDEBUGレベル以上のSDKメッセージが表示されます。 ## トラブルシューティング ### fork()を呼び出したときに、\_\_NSPlaceholderDateが別のスレッドで実行中であるというエラー macOS 上の Ansible で起こり得ます。プレイブック実行中に、次のエラーが出ることがあります。 ``` objc[6763]: +[__NSPlaceholderDate initialize] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead. Set a breakpoint on objc_initializeAfterForkError to debug ``` Ansibleの既知の問題です。次の環境変数で回避できます。 ``` OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ansible-playbook ... ``` ### 構成ファイルの欠如 ``` TASK [Copy file from Keeper into the file] ******************************************************************************************** An exception occurred during task execution. To see the full traceback, use -vvv. The error was: Exception: Keeper Ansible error: There is no config file and the Ansible variable contain no config keys. Will not be able to connect to the Keeper server. fatal: [localhost]: FAILED! => {"msg": "Unexpected failure during module execution.", "stdout": ""} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/keeperpam/jp/secrets-manager/integrations/ansible/ansible-plugin.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.