Ansibleプラグイン

Keeperアカウントを操作し、自動化で使用できるAnsibleプラグインのコレクション。

機能

• Ansibleプレイブックで使用するシークレットをKeeperボルトから取得します

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

• Ansibleからレコードを作成します

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

Keeperシークレットマネージャー機能の完全なリストについては、概要をご参照ください。

前提条件

このページでは、シークレットマネージャーとAnsibleとの連携について説明します。 この連携を利用するための必要条件は以下のとおりです。

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

  • Keeperアカウントのシークレットマネージャーアドオンの有効化

  • シークレットマネージャー強制ポリシーが有効化されたロールを割り当てられたメンバーシップ

• シークレットを共有するKeeperシークレットマネージャー

  • アプリケーションの作成手順については、クイックスタートガイドをご参照ください
• Keeperシークレットマネージャー設定の初期化

  • Ansible連携では、JSON形式の設定を利用できます。

インストール

Ansibleの柔軟性により、プラグインをインストールする場所は、Ansibleのインストールプログラムとプレイブックの場所によって異なります。

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

Ansible Galaxyからのインストール

このコレクションはAnsible Galaxyのサイトで入手できます。次のコマンドラインを使用してこのコレクションをインストールできます。

$ ansible-galaxy collection install keepersecurity.keeper_secrets_manager

Ansible Galaxyのコレクションでは、長いプラグイン名が使用されています。名前は、コレクション名とプラグイン名の組み合わせです。たとえば、Ansible Galaxyを使用する場合のkeeper_copyプラグイン名は、keeper_security.keeper_secrets_manager.keeper_copy_です。_短いプラグイン名を使用したい場合は、プレイブックのコレクションブロックに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プレイブックの設定で必要になるため、モジュールのインストール場所をメモしておきます。

$ pip3 install -U keeper_secrets_manager_ansible

GitHubリポジトリでKeeperシークレットマネージャーのAnsibleプラグインのソースコードを検索します。

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プレイブックで認証を行い、ボルトから指定したシークレットを取得できます。

Ansible変数

Keeperシークレットマネージャープラグインは、複数の設定形式を使用できます。たとえば、Base64でエンコードされた設定を使用できます。

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

Ansibleは、client-config.json設定ファイルをそのまま使用できます。keeper_config_file変数キーを使用して、Ansible変数で指定できます。

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

もう1つの解決策は、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	ワンタイムアクセストークンが使用された後に、Secrets Managerが発行するクライアント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_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つのactionプラグインと1つのlookupプラグインがあります。

すべてのプラグインで、以下の引数が使用されます。

• uid - 目的の記録のUIDレコード（必須）。

• field - 指定したラベルの値をレコードから取得します。

• custom_field - 特定のカスタムフィールド名の値を取得します。

• file - 指定した名前のファイルをレコードから取得します。

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

特定のボルトのシークレットで使用できるフィールドおよびカスタムフィールドを確認するには、KeeperシークレットマネージャーCLIの「ksm secret get -u XXXX」コマンドを使用します。 詳細についてはこちらをご覧ください。

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

アクションでは、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: 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またはレコードタイトルによって取得できます。アクションの結果、レコードが暗号化されてシリアライズされます。結果はregister変数を使用してAnsibleに保存し、他のアクションで使用できるようする必要があります。レコードの暗号化を伴うシリアルライズは非常に長くなる場合があります。 セキュリティとログノイズを軽減するために、no_logをTrueに設定することを推奨します。

keeper_cache_recordsはレコードのみをキャッシュし、添付ファイルはキャッシュされません。アクションでキャッシュに含まれているレコードから添付ファイルを取得しようとすると、ファイルをダウンロードするためのAPI呼び出しが行われます。

「cache: "{{ my_records.cache }}」のように、テンプレートを使用して他のアクションで属性を設定します。

keeper_cache_recordsでは、keeper_record_cache_secretが設定されている必要があります。これは、ホスト、グループ、タスク変数で行うことも、タスク内で生成してファクト (変数) として設定することもできます。上の例では、keeper_passwordアクションを使用してパスワードを生成し、それがkeeper_record_cache_secretとして保存されます。no_log属性はTrueに設定され、シークレットがログされないようにします。

キャッシュは更新されません。キャッシュには、生成後に作成または更新されたレコードは含まれません。キャッシュ内の新しいレコードまたは変更を取得するには、keeper_cache_recordsを再度呼び出す必要があります。

必須の属性

• uids - KeeperボルトのレコードのUIDのリスト

• titles - Keeperボルトのレコードのタイトルのリスト

uidsとtitlesは同時に使用できます。少なくともどちらか一方が設定されている必要があります。

プラグイン: keeper_copy

keeper_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」に保存されます。組み込みのコピープラグインのmodeキー/値を使用して、ファイルのアクセス権限を変更します。

上の2番目のタスクの例では、ファイル「my_cert_file.crt」がKeeperボルトのレコードからコピーされ、「/tmp/special.crt」に保存されます。組み込みのコピープラグイン関数のいくつかが、このファイルに適用されます。

必須の属性

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

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

• notation - Keeper表記法を使用してレコードからフィールドを取得

uidsとtitlesは同時に使用できます。少なくともどちらか一方が設定されている必要があります。

任意の属性

• cache - keeper_cache_records操作からのレコードキャッシュ

• field - 標準Keeperボルトレコードから内容を取得

• custom_field - カスタムKeeperボルトレコードから内容を取得

• file - ファイルタイトルを使用してKeeperボルトレコードの添付ファイルの内容を取得

• array_index - デフォルトは0。フィールドの値に複数の値が含まれている場合、どの項目を返すか選択できます。最初の項目はarray_indexが0であり、次の項目は1となります。

• value_key - フィールドの値が複合オブジェクトの場合、キーと値の対のキーを返すよう選択できます。

その他の任意の属性は、内蔵のコピー プラグイン属性と同じとなります。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プラグインは連想配列を返します。連想配列内のキーの「値」には、目的のフィールドまたはファイルの内容が含まれます。このプラグインは通常、Ansible命令レジスタとペアになっており、戻り値は他のタスクからアクセスできるようにメモリに格納されます。

上記の例では、最初のタスクは、指定したボルトのUIDレコードからログインフィールドを取得します。続いて、my_loginという名前で格納されます。2番目のタスクでは、デバッグのためにログイン名をコンソールに出力します。3番目のタスクでは、すべてのアプリケーションを実行できるログイン名のsudoerファイルが追加されます。

必須の属性

• 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。フィールドの値に複数の値が含まれている場合、どの項目を返すか選択できます。最初の項目はarray_indexが0であり、次の項目は1のようになります。

• value_key - フィールドの値が複合オブジェクトの場合、キーと値の対のキーを返すよう選択できます。

プラグイン: 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属性が使用されているため、ディクショナリにはログインとパスワードのみが含まれます。フィールド値には、Ansibleの通常のテンプレートを使用してアクセスできます。 値は配列として保存されますが、これは電話などの値の配列を返す一部フィールドに起因します。

必須の属性

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

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

uidsかtitlesのどちらかが必要となります。

任意の属性

• 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 and Portのフィールドタイプの場合、Portのみを更新する方法はありません。HostNameを含む値全体がオブジェクト値に含まれる必要があります。

keeper_setは、ボルト内のレコードの更新を設定します。使用してもキャッシュは更新されません。キャッシュを更新するには、更新されたレコードのUIDまたはタイトルを使用して、keeper_cache_recordsを再度実行する必要があります。

必須の属性

• uid - Keeperボルトのレコードのタイトル

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

• notation - Keeper表記法を使用してレコードからフィールドを取得

uidsとtitlesは同時に使用できます。少なくともどちらか一方が設定されている必要があります。

Optional Attributes

• cache - レコードのキャッシュ。レコードの取得に使用し、キャッシュは更新されません。

• field - 既存の標準Keeperボルトレコードフィールドを更新

• custom_field - 既存のカスタムKeeperボルトレコードフィールドを更新

プラグイン: keeper_create

keeper_createプラグインは、Keeperボルトにレコードを作成します。使用可能なレコードタイプ、およびレコードの作成に使用されるフィールドタイプについては、フィールド/レコードタイプのドキュメントをご参照ください。actionプラグインは、作成に成功すると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"
      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が設定されている場合は、それらのレコードタイプを使用できます。

• 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コマンダーは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ファイルで、keeper_record_typesという変数キーに"content"オブジェクトの値を追加します。変数は配列で、JSONは文字列値として扱う必要があります。配列項目の後のパイプは、以降のJSONを文字列として扱います。この変数は複数のレコードタイプを指定できます。

例:

- 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_removeで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ボルトのレコードのタイトル

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

uidsとtitlesは同時に使用できます。少なくともどちらか一方が設定されている必要があります。

任意の属性

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