Ansibleプラグイン

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

機能

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

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

• Ansibleからレコードを作成

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

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

要件

• 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のライブラリ環境または仮想環境(virtualenv)に対して、pipを使用して手動でインストールする必要があります。

• importlib_metadata

• keeper-secrets-manager-core>=16.2.2

• keeper-secrets-manager-helper>=1.0.4

Pypiからのインストール

Keeper用のAnsibleモジュールは、以下のコマンドでインストールします。モジュールがインストールされる場所は、Ansible Playbookの設定で必要になるため、必ず控えておいてください。

$ pip3 install -U keeper_secrets_manager_ansible

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が自動で切り替えます。必須ではありませんが、Webサービス呼び出し回数の削減に役立ちます。
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には、3つのアクションプラグインと1つのルックアッププラグインがあります。

すべてのプラグインで、以下の引数が使用されます。uid または title のいずれかを指定する必要があります。

• uid – 対象となるレコードのUID

• title – 対象となるレコードのタイトル

• field – レコード内の指定したラベルの値を取得

• custom_field – 指定したカスタムフィールド名の値を取得

• file – レコード内の指定した名前のファイルを取得

uid の指定は必須であり、field または file のいずれかを指定する必要があります。

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

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

アクションでは、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
  # Ansible Galaxy経由でインストールした場合、または完全修飾プラグイン名を使用する場合は、以下の行を含めてください。
  # collections: 
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name: Generate a Keeper Record Cache secret
      keeper_password:
        length: 64
      register: keeper_record_cache_secret
      no_log: True

    - name: Store the Keeper Record Cache secret into variables.
      set_fact:
        keeper_record_cache_secret: "{{ keeper_record_cache_secret.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
  # Ansible Galaxy経由でインストールした場合、または完全修飾プラグイン名を使用する場合は、以下の行を追加してください。
  # 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

これらの例では、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ボルトのレコードに添付されたファイルのうち、ファイルタイトルを指定して内容を取得します

• array_index - 既定値は0です。フィールドの値に複数の要素が含まれている場合に、どの要素を返すかを指定します。最初の要素は0、次は1というように指定します。

• value_key - フィールドの値が複雑なオブジェクトの場合に、返却するキーと値のペアのうち、どのキーを取得するかを指定します。

このほか、任意属性として、Ansible組み込みのcopyプラグインで使用できる属性を指定できます。ただし、src、remote_src、content は使用できず、指定しても無視されます。

プラグイン: keeper_get

keeper_get プラグインは、Keeperボルトのレコードからフィールドまたはファイルを取得するために使用します。使用例は以下のとおりです。

---
- name:Keeper Get
  hosts: my_hosts
  # Ansible Galaxy経由でインストールした場合、または完全修飾プラグイン名を使用する場合は、以下の行を追加してください。
  # collections:
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name:Get login name
      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: |
          # Ansibleによって自動的に追加
          {{ my_login.value }} ALL=(ALL:ALL) ALL

keeper_get プラグインはディクショナリ形式の結果を返します。このディクショナリのvalueキーに、取得したフィールドまたはファイルの内容が格納されます。通常はAnsibleの register と組み合わせて使用し、返された値をメモリ上に保存することで、他のタスクから参照できるようにします。

上記の例では、ユーザーのログイン名を含むレコードを取得し、そのログイン名を my_login という名前で保存しています。次のタスクでは、デバッグ目的でログイン名をコンソールに出力します。さらに3つ目のタスクでは、そのログイン名を使用して、すべてのアプリケーションを実行できる権限を持つsudoersファイルを追加します。

必須属性

• uid - Keeperボルト内のレコードUID。

• title - Keeperボルト内のレコードタイトル。

• notation - Keeper表記法を使用して、レコード内のフィールドを取得します。

uids と titles は同時に指定できますが、いずれか一方は必ず設定する必要があります。

任意属性

• cache - keeper_cache_records アクションで作成したレコードキャッシュを指定します。

• field - Keeperボルトの標準レコードから値を取得します。

• custom_field - Keeperボルトのカスタムレコードから値を取得します。

• file - Keeperボルトのレコードに添付されたファイルのうち、ファイルタイトルを指定して値を取得します。

• allow_array - 既定値はFalseです。Trueに設定すると、値を配列として返します。電話番号など、フィールドに複数の値が含まれる場合に必要です。この属性をTrueにした場合、array_index および value_key は無視されます。

• array_index - 既定値は0です。フィールドの値に複数の要素が含まれている場合に、返す要素を指定します。最初の要素は0、次は1というように指定します。

• value_key - フィールドの値が複雑なオブジェクトの場合に、返却するキーと値のペアのうち、取得するキーを指定します。

プラグイン: keeper_get_record

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

---
- name: Keeper Get Record
  hosts: my_hosts
  # Ansible Galaxy経由でインストールした場合、または完全修飾プラグイン名を使用する場合は、以下の行を追加してください。
  # 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ボルトレコードに値を書き込む機能を備えています。使用例は以下のとおりです。

___
- name:Keeper Set
  hosts: my_hosts
  # Ansible Galaxy経由でインストールした場合、または完全修飾プラグイン名を使用する場合は、以下の行を追加してください。
  # collections:
  #   - keepersecurity.keeper_secrets_manager
  
  tasks:
    - name:Get login name
      keeper_get:
        uid:RECORD UID
        field: login
      register: my_login
      
    - name:Add new user
      user:
        name: "{{ my_login.value }}"
        comment:"User {{ my_login.value }}"
      register: new_user
        
    - name:Update record
      keeper_set:
        uid:RECORD UID
        custom_field: my_home_directory
        value: "{{ new_user.home }}"      

この例では、新しいユーザーのログイン名を取得し、そのレコードに含まれるログイン名を使用してリモートシステム上にユーザーを作成します。その後、リモートマシン上のホームディレクトリを、レコード内の情報として更新します。

keeper_set アクションでは、配列や複雑な値の一部だけを更新することはできません。常に既存の値を新しい値で置き換える動作になります。例えば、HostnameとPortを含むフィールドタイプでは、ポート番号だけを更新することはできず、hostNameを含めた値全体を指定する必要があります。

keeper_set はボルト内のレコードを更新しますが、使用しているキャッシュは更新されません。キャッシュの内容を反映させるには、更新したレコードのUIDまたはtitleを指定して、再度 keeper_cache_records アクションを実行する必要があります。

必須属性

• uid - Keeperボルト内のレコードUID。

• title - Keeperボルト内のレコードタイトル。

• notation - Keeper表記法を使用して、レコード内のフィールドを指定します。

uid と title は同時に指定できますが、いずれか一方は必ず設定する必要があります。

任意属性

• cache - レコードを取得するためのキャッシュを指定します。キャッシュの更新は行われません。

• field - 既存のKeeperボルトの標準フィールドを更新します。

• custom_field - 既存のKeeperボルトのカスタムフィールドを更新します。

プラグイン: keeper_create

keeper_create プラグインは、Keeperボルトに新しいレコードを作成します。作成可能なレコードタイプや、レコードを構成するフィールドタイプについては、フィールド/レコードタイプのページをご参照ください。作成に成功すると、アクションプラグインは record_uid を返します。

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

以下は使用例です。

---
- 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"
      note:"Created by Ansible"
      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が設定されている場合は、そこで定義されたレコードタイプも使用できます。keeper_record_types が設定されている場合は、それらのレコードタイプを使用できます。

• title - レコードのタイトルを指定します。

以下のフィールドは任意です。

• 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 Commanderは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"
        note:"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プラグインはランダムなパスワードを生成します。actionプラグインは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ボルトのレコードのタイトル

• 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プラグインによって作成されたファイルを消去するために使用されます。主として、キャッシュファイルを使用している場合に、キャッシュファイルを削除するために使用されます。キャッシュファイルは、ネットワークに問題がある場合、レコードを取得するために代わりに使用されます。Ansibleシークレット環境を実行している場合は、キャッシュを削除する必要はありません。ただし、このプラグインを使用すると、キャッシュを削除できます。

- 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_redact標準出力コールバックプラグインを使用して標準出力ログからシークレットを編集して難読化するのに有効です。これは、keeper_copyとkeeper_getに対応します。keeper_lookupのシークレット値は編集されません。keeper_lookupには、no_log:Trueディレクティブを使用します。

プレイブックでシークレットデータを保存する方法をご参照ください。no_logを使用すると、タスクのすべてのログを非表示にできます。このプラグインは、Keeperシークレットマネージャープラグインによって返されたシークレットを非表示または編集したい場合に使用します。

keeper_redactプラグインは、ジョブの実行時にログをストリーミングするための独自の標準出力コールバックプラグインを利用したため、Ansible Towerでは使用できません。ログに情報を表示したくない場合は、no_logオプションのご使用を強くお勧めします。

keeper_redactプラグインを使用するには、_ansible.cfg_で有効にします。

[defaults]
stdout_callback = keeper_redact
# 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": ""}