クレデンシャルヘルパー

モジュールレジストリなど、リモートネットワークサービスと連携するOpenTofu固有の機能の場合、OpenTofuはデフォルトで、これらの呼び出しで使用するAPIクレデンシャルをCLI設定で検索します。

クレデンシャルヘルパーは、外部プログラムを使用してOpenTofuがクレデンシャルを取得する方法をカスタマイズできる代替アプローチを提供し、これにより組織内の既存のシークレット管理システムに直接アクセスできます。

このページでは、クレデンシャルヘルパーの作成とインストール方法について説明します。インストール済みのクレデンシャルヘルパーを設定する方法については、CLI設定のクレデンシャルヘルパーセクションを参照してください。

OpenTofuがクレデンシャルヘルパーを検出する方法

クレデンシャルヘルパーは、特定の場所にインストールされ、その名前が特定の命名規則に従う通常の実行可能プログラムです。

たとえば、「credstore」という名前のクレデンシャルヘルパーは、terraform-credentials-credstore (Windowsでは.exe拡張子付き) という名前の実行可能プログラムとして実装され、デフォルトのプラグイン検索場所のいずれかにインストールされます。

OpenTofuがクレデンシャルヘルパーを実行する方法

OpenTofuは、設定済みのクレデンシャルヘルパーを見つけると、CLI設定のcredentialsブロックで満たせない各クレデンシャルリクエストに対して1回実行します。

次の例では、「credstore」クレデンシャルヘルパーが次のように設定されていると仮定します。

コードブロック
credentials_helper "credstore" {
  args = ["--host=credstore.example.com"]
}

OpenTofuは、argsで指定された各引数、続いて*動詞*、そして動詞が適用されるホスト名を付けてヘルパープログラムを実行します。現在の動詞のセットは次のとおりです。

get: 指定されたホスト名のクレデンシャルを取得します。
store: 指定されたホスト名の新しいクレデンシャルを保存します。
forget: 指定されたホスト名に保存されているクレデンシャルを削除します。

クレデンシャルを表すために、クレデンシャルヘルパープロトコルは、CLI設定のcredentialsブロックの内容に対応する内容を持つJSONオブジェクトを使用します。APIトークンを表すには、オブジェクトには「token」というプロパティが含まれ、その値はトークン文字列です。

コードブロック
{
  "token": "example-token-value"
}

次のセクションでは、3つの動詞それぞれの具体的な期待される動作について説明します。

`get`: 指定されたホスト名のクレデンシャルを取得します。

app.example.ioのクレデンシャルを取得するために、OpenTofuは「credstore」ヘルパーを次のように実行します。

terraform-credentials-credstore --host=credstore.example.com get app.example.io

クレデンシャルヘルパーが指定されたホストのクレデンシャルを提供できる場合、その標準出力ストリームにJSONクレデンシャルオブジェクトを出力し、成功を示すためにステータスコードゼロで終了する必要があります。

クレデンシャルヘルパーが、指定されたホストのクレデンシャルを明確に持っていない場合は、空のJSONオブジェクトを標準出力に出力し、ステータスゼロで終了する必要があります。

クレデンシャルヘルパーが他の理由で要求されたクレデンシャルを提供できない場合は、エンドユーザー向けのプレーンテキストのエラーメッセージをその標準エラー出力ストリームに出力し、*ゼロ以外の*ステータスコードで終了する必要があります。

`store`: 指定されたホスト名の新しいクレデンシャルを保存します。

app.example.ioの新しいクレデンシャルを保存するために、OpenTofuは「credstore」ヘルパーを次のように実行します。

terraform-credentials-credstore --host=credstore.example.com store app.example.io

OpenTofuは、JSONクレデンシャルオブジェクトをヘルパープログラムの標準入力ストリームに書き込みます。ヘルパーが指定されたクレデンシャルを保存できる場合、それを保存し、成功を示すために標準出力または標準エラー出力に何も出力せずにステータスコードゼロで終了する必要があります。

何らかの理由で指定されたクレデンシャルを保存できない場合は、EOFまで標準入力を完全に読み取り、ゼロ以外のステータスコードで終了する前に、エンドユーザー向けのプレーンテキストのエラーメッセージを標準エラー出力ストリームに出力する必要があります。

新しいクレデンシャルは、指定されたホスト名に保存されている既存のクレデンシャルを完全に置き換える必要があります。

`forget`: 指定されたホスト名に保存されているクレデンシャルを削除します。

app.example.ioの既存のクレデンシャルを削除するために、OpenTofuは「credstore」ヘルパーを次のように実行します。

terraform-credentials-credstore --host=credstore.example.com forget app.example.io

forget動詞では、JSONクレデンシャルオブジェクトは使用されません。

ヘルパープログラムが指定されたホスト名の保存済みクレデンシャルを削除できる場合、またはそのようなクレデンシャルがまだ保存されていない場合は、ステータスコードゼロで存在し、標準出力または標準エラー出力に何も出力しないでください。

保存されたクレデンシャルを削除できない場合、特にヘルパーがクレデンシャルが取得できなくなったことを確信できない場合、ヘルパープログラムは、エンドユーザー向けのプレーンテキストのエラーメッセージをその標準エラー出力ストリームに出力し、ゼロ以外のステータスコードで終了する必要があります。

その他のコマンドの処理

クレデンシャルヘルパープロトコルは将来、追加の動詞で拡張される可能性があるため、前方互換性のために、クレデンシャルヘルパーはサポートされていない動詞に対して、エンドユーザー向けのプレーンテキストのエラーメッセージをその標準エラー出力ストリームに出力し、ゼロ以外のステータスコードで終了することで対応する必要があります。

サポートされていないクレデンシャルオブジェクトプロパティの処理

OpenTofuは、JSONクレデンシャルオブジェクト内でtokenプロパティのみを定義します。

クレデンシャルヘルパーが、token以外のプロパティを持つオブジェクトを保存するように求められ、それらを忠実に保持できない場合は、オブジェクトが保存できないかのように動作し、エラーを返す必要があります。クレデンシャルオブジェクトの意味が変わる可能性があるため、token値のみを分離して保存し、他のプロパティを黙ってドロップしては*いけません*。

ターゲットシステムの制約内で技術的に可能であれば、クレデンシャルヘルパーは、後で取得するためにJSONオブジェクト全体をそのまま保存することを優先する必要があります。より制約の多いシステムでは、上記のように他のプロパティを含むオブジェクトをプログラムが拒否する限り、token文字列のみを保存することが許容されます。