Ansibleプラグイン

Keeperアカウントと連携し、自動化処理の中で利用できるAnsibleプラグインのコレクション

機能

• Keeperボルトからシークレットを取得し、Ansible Playbookで利用

• AnsibleからKeeperボルト内のシークレットの値を更新

• Ansibleからレコードを作成

• Keeperボルトからファイルをコピー

Keeperシークレットマネージャーの機能一覧については、概要ページをご参照ください。

要件

このページでは、KeeperシークレットマネージャーのAnsible連携について説明します。この連携を利用するには、次のものが必要です。

• Keeperシークレットマネージャーへのアクセス (詳細はクイックスタートガイドをご参照ください)

  • Keeperアカウントでシークレットマネージャーアドオンが有効になっていること

  • シークレットマネージャーの適用ポリシーが有効なロールのメンバーであること

• シークレットが共有されているKeeperのシークレットマネージャーアプリケーション

  • アプリケーションの作成手順は、クイックスタートガイドをご参照ください

• 初期化済みのKeeperのシークレットマネージャー構成

  • Ansible連携では、Base64形式およびJSON形式のいずれの構成も利用できます。

インストール

Ansibleは柔軟性が高いため、プラグインのインストール先は、使用しているAnsibleの構成やPlaybookの配置場所によって異なります。

Keeper Ansibleモジュールのインストール

Ansible Galaxyを使用したインストール

このコレクションは、Ansible Galaxyのサイトで公開されています。次のコマンドでコレクションをインストールできます。

$ 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 を追加します。

- name: Keeper Copy
  hosts: my_hosts
  collections: 
    - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Copy a password
      keeper_copy:
        uid: RECORD UID
        ...

Ansible Galaxyを使用したインストールでは、あらかじめAnsibleがインストールされていることを前提とします。Ansible Galaxyでは依存関係をインストールできません。次の依存関係は、Ansibleが使用するPythonのライブラリまたは仮想環境に対して、pipなどで手動でインストールする必要があります。

• keeper-secrets-manager-core>=17.2.0

• keeper-secrets-manager-helper>=1.1.0

PyPIからのインストール

Keeper用のAnsibleモジュールは、次のコマンドでインストールします。モジュールのインストール先のパスを控えておいてください。Ansible Playbookの設定で必要になります。

$ pip3 install -U keeper_secrets_manager_ansible

Python 3.9以降が必要です。

詳細は、PyPIのページをご参照ください。

KeeperシークレットマネージャーのAnsibleプラグインのソースコードは、GitHubリポジトリで確認できます。

KeeperのAnsibleプラグインは、使用中のPythonのバージョンまたは現在の仮想環境の site-packages ディレクトリにインストールされます。次のコマンドでプラグインの場所を確認できます。

$ 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 で使用できます。

[defaults]
action_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/action_plugins
lookup_plugins = ...site-packages/keeper_secrets_manager_ansible/plugins/lookup_plugins

構成ファイルの生成

このガイドに進む前に、要件をすべて満たし、次のものを用意してください。

• KSMアプリケーションおよび対応するワンタイムアクセストークン

• Keeper Ansibleモジュールがインストールされていること

Keeperシークレットマネージャー用のAnsibleプラグインを使用するには、Keeperの構成ファイルが必要です。構成ファイルを取得したら、その値をAnsibleの変数ファイルに記述できます。これらの変数ファイルはAnsible Vaultで暗号化できます。

Keeper Ansibleモジュールと生成済みのワンタイムアクセストークンを使って、次のコマンドで構成ファイルを生成します。

$ keeper_ansible --token XX:XXXXXX
Config file create at location client-config.json

現在のディレクトリにKeeperのJSON構成ファイルが生成されます。

PythonモジュールのbinディレクトリがPATH環境変数に含まれていない場合は、次のコマンドでも構成ファイルを作成できます。

$ python3 -m keeper_secrets_manager_ansible --token XX:XXXXXX
Config file create at location client-config.json

JSON構成ファイルのデフォルト名は client-config.json です。内容の例は次のとおりです。

{
    "appKey" : "XXXXXXXX",
    "appOwnerPublicKey": "XXXXXXX",
    "clientId": "XXXXXXXX",
    "hostname": "XXXXX",
    "privateKey": "XXXXXXXX",
    "serverPublicKeyId": "XX"
}

この構成ファイルにより、Ansible Playbookが認証し、ボルトから指定したシークレットを取得できます。

Ansible変数

Keeperシークレットマネージャーのプラグインでは、複数の構成方法を使用できます。たとえば、Base64でエンコードされた構成を利用することも可能です。

---
keeper_config: U09NRVRFc2R ... GFzZGFzZGFzZHNhWFQK==

Ansibleでは、client-config.json を構成ファイルとして直接使用できます。Ansibleの変数で keeper_config_file という変数キーを指定します。

---
keeper_config_file: /path/to/client-config.json

別の方法として、client-config.json に含まれる値をAnsibleの変数ファイルに置けます。たとえば、_group_vars、host_vars、またはタスクファイル_内に記述できます。

---
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キー	説明
keeper_config	--	Base64エンコードされた構成文字列です。
keeper_config_file	--	JSON構成ファイルのパスとファイル名を指定します。現在のディレクトリ以外にある場合や、ファイル名がclient-config.json以外の場合に使用します。
keeper_token	clientKey	ワンタイムアクセストークン(クライアントキーとも呼ばれます)です。構成の初期化時にのみ使用されます。
keeper_client_id	clientId	ワンタイムアクセストークン使用後にシークレットマネージャーが返すクライアントIDです。必須です。
keeper_app_key	appKey	ワンタイムアクセストークン使用後にシークレットマネージャーが返すアプリケーションキーです。必須です。
keeper_private_key	privateKey	ワンタイムアクセストークン使用後にシークレットマネージャーが返す秘密鍵です。必須です。
keeper_app_owner_public_key	appOwnerPublicKey	レコード作成時に使用される公開鍵です。keeper_createプラグインを使用する場合に必須です。
keeper_server_public_key_id	serverPublicKeyId	サーバー接続時に使用する公開鍵を指定します。サーバー側で異なる公開鍵が必要な場合はSDKが自動で切り替えます。必須ではありませんが、ウェブサービス呼び出し回数の削減に役立ちます。
keeper_hostname	hostname	シークレットマネージャーのバックエンドホスト名です。デフォルトは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コマンダーのレコードタイプ定義の一覧です。

プラグインには2種類のキャッシュ方法があります。同じものではありません。 keeper_record_cache_secret は、Playbookの実行中にレコードをキャッシュするために使用します。Playbookの実行が終わるとキャッシュは削除されます。キャッシュは暗号化された状態でメモリに保持されます。このキャッシュにより、KeeperシークレットマネージャーサービスへのAPI呼び出し回数を減らせます。メモリに保持されるため、取得するレコードが増えるほど、消費するメモリ量も増えます。 keeper_use_cache と keeper_cache_dir は、Keeperボルトの障害時バックアップ用キャッシュに使います。Keeperシークレットマネージャーに接続できないときの取得先として使われます。キャッシュは暗号化されたままディスクに保存されます。

コマンドライン変数

任意の方法として、ansible-playbook の実行時に値を渡せます。例を次に示します。

$ 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 の指定も必要です。

特定のボルトシークレットで利用可能なフィールドやカスタムフィールドを確認するには、KeeperシークレットマネージャーCLIの ksm secret get -u XXXX コマンドを使います。詳細はこちらをご参照ください。

プラグインの例では短いプラグイン名を使用しています。Ansible Galaxy経由でコレクションをインストールした場合は、長いプラグイン名を使うか、Playbookで使用するコレクションの一覧にコレクション名を追加する必要があります。

アクションでは、Keeper表記法を使うか、レコードのUIDまたはタイトルと、タスク属性の array_index および value_key を組み合わせて、特定の値を取得できます。

たとえば、電話番号のように複雑な値は、オブジェクトの配列として表現されます。

[
    {
        'number': '[phone]', 
        'type': 'Work', 
        'ext': '11'
    }, 
    {
        'region': 'AD', 
        'number': '111-2223333', 
        'ext': '5555', 
        'type': 'Mobile'
    }
]

次の例では、Keeper表記法と array_index および value_key を使って、同じ結果を得る方法を示します。

---
- 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呼び出しの回数を抑えることが目的です。

---
- 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プラグインを拡張したものです。以下はその例です。

---
- 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プラグインと同じものを指定できます。src、remote_src、content は使用できず、指定しても無視されます。

プラグイン: keeper_get

v1.3.0の新機能: notes パラメータでレコードのノートを取得できるようになりました。

keeper_get プラグインは、Keeperボルトのレコードからフィールドまたはファイルを取得します。以下はその例です。

---
- 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 - フィールドの値が複雑なオブジェクトの場合に、返すキーと値のペアのうちどのキーを選ぶかを指定します。

レコードのノートを更新するには、keeper_set プラグインで notes: yes と value: を指定します。

プラグイン: keeper_get_record

keeper_get_record プラグインは、レコードに含まれるすべてのフィールドを取得し、ディクショナリ形式で返します。使用例は次のとおりです。

---
- 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ボルトのレコードに値を書き込めます。

v1.3.0の新機能: keeper_set で notes: yes と value: を指定すると、レコードのノート欄を更新できます。

レコードのノートを取得するには、keeper_get プラグインで notes: yes を指定します。

例を次に示します。

---
- 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ボルトにレコードを作成します。利用可能なレコードタイプとレコードを構成するフィールドタイプは、フィールド/レコードタイプをご参照ください。作成に成功すると、アクションプラグインは record_uid を返します。

レコードを作成するには、Ansible変数 keeper_app_owner_public_key が必要です。client-config.json では JSON キー appOwnerPublicKey に対応します。このキーが構成に含まれていない場合は、新しいワンタイムアクセストークンを作成して初期化してください。

例を次に示します。

---
- 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 - レコードにノートを添付します。

パスワード生成では、概ね次の記号が含まれます。!@#$%()+;<>=?\[]{}^., などです。

レコードタイプによっては追加の必須フィールドがあります。カスタムフィールドは任意です。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 には、複数のレコードタイプを指定できます。

使用例は次のとおりです。

- 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 パラメータでレコードタイプ名を指定します。

- 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ボルト内のレコードを削除できます。

---
- 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 を返します。

例を次に示します。

---
- 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の「%」などです。設定しない場合、パスワードはフィルタリングされません。

パスワード生成では、概ね次の記号が含まれます。!@#$%()+;<>=?\[]{}^., などです。

レコードタイプに応じて、特定のフィールドが必須になる場合があります。カスタムフィールドは任意です。fields と custom_fields はいずれも値の配列です。

プラグイン: keeper_lookup

keeper_lookup プラグインは、Keeperボルトのレコードからフィールドを取得し、その値をテキスト文字列に挿入します。

例を次に示します。

---
- 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 コマンドを使います。詳細はこちらをご参照ください。

プラグイン: keeper_init

keeper_init プラグインは、ワンタイムアクセストークンから構成を初期化します。keeper_ansible --keeper_token コマンドに相当します。次のオプションを指定できます。

• token - ワンタイムアクセストークン。この値はテンプレート化して、値で渡すことをお勧めします。

• filename - 設定値で生成する設定ファイルの名前。指定されていない場合、設定は作成されません。

• show_config - 設定値をタスクのログに返すべきか否かを示すフラグ。デフォルトはFalseです。他の方法で設定を生成できない場合、または生成された設定ファイルにアクセスできない場合にのみ、Trueに設定します。Trueの場合、設定がログに出力されます。コマンドラインからプレイブックを実行する分には問題になりにくいですが、Ansible Tower経由ではログに残る点に注意してください。

---
- 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を使用してプレイブックに渡すことができます。

$ 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 ロールも入り、ワンタイムアクセストークンを初期化できます。プレイブックから利用します。

---
- 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 以上にしてください。

---
- name: Keeper Info
  hosts: localhost
  connection: local
  
  tasks:
    - name: Display Keeper Info
      keeper_info:

これで、カスタムレコードタイプがプラグインに認識されているかを確認できます。

プラグイン: keeper_cleanup

keeper_cleanup プラグインは、Keeper 系プラグインが作成したファイル（主にキャッシュ）を削除します。ネットワーク障害時にレコード取得へフォールバックするキャッシュ向けです。シークレット運用で必ずしも削除する必要はありませんが、削除したい場合に使います。

- 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 を指定してください。

プレイブックでシークレットデータを保存する方法をご参照ください。no_log を使うとタスク全体のログを抑止できます。本プラグインは、Keeperシークレットマネージャー系プラグインが返したシークレットだけを標準出力からマスクしたいときに使います。

keeper_redact プラグインは Ansible Tower では利用できません。Tower がジョブのログ用に独自の標準出力コールバックを使うためです。ログへの露出を抑えたい場合は、Tower 上でも no_log の利用を強く推奨します。

keeper_redact プラグインを使うには、ansible.cfg で有効にします。

[defaults]
stdout_callback = keeper_redact
# Use long name if install via Ansible Galaxy
# stdout_callback = keepersecurity.keeper_secrets_manager.keeper_redact

たとえば、次のタスクはカスタムフィールド MyPhoneNumbers の電話番号をすべて返し、変数 phone_numbers に格納します。

    - name: "Get Phone Numbers"
      keeper_get:
        uid: OlLZ6JLjnyMOS3CiIPHBjw
        custom_field: MyPhoneNumbers
        allow_array: True
      register: phone_numbers

プレイブックを詳細付きで実行すると、変数に入れた値が表示され、シークレットがログに残るおそれがあります。keeper_redact 標準出力コールバックを有効にすると、ログ上の値がマスクされます。

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 のシークレット表記法の詳細）。たとえば、次のスクリプトは、指定したレコードUIDのシークレットパスワードを出力します。

#!/bin/sh
ksm secret notation keeper://XXXX/field/password

XXXX をボルトのレコードUIDに置き換えます。このスクリプトを実行すると、シークレットのパスワードが出力されます。

環境変数 ANSIBLE_VAULT_PASSWORD_FILE を上書きするには、次を実行し、/path/to/script を上記スクリプトのパスに置き換えます。

$ 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": ""}