跳至主要内容

凭据助手

对于与远程网络服务交互的 OpenTofu 特定功能，例如模块注册中心，OpenTofu 默认情况下会在 CLI 配置 中查找用于这些调用的 API 凭据。

凭据助手提供了一种替代方法，允许你使用外部程序自定义 OpenTofu 如何获取凭据，该程序可以随后直接访问你组织中现有的秘密管理系统。

本页介绍如何编写和安装凭据助手。要了解如何配置已安装的凭据助手，请参阅 CLI 配置凭据助手部分。

OpenTofu 如何查找凭据助手​

凭据助手是一个普通的可执行程序，它安装在特定位置，并且其名称遵循特定的命名约定。

例如，名为“credstore”的凭据助手将作为名为 terraform-credentials-credstore（仅在 Windows 上带有 .exe 扩展名）的可执行程序实现，并安装在 默认插件搜索位置 之一中。

OpenTofu 如何运行凭据助手​

一旦 OpenTofu 找到配置的凭据助手，它就会针对无法通过 CLI 配置中的 credentials 块满足的每个凭据请求执行它一次。

对于以下示例，我们假设一个名为“credstore”的凭据助手，其配置如下

代码块
credentials_helper "credstore" {
  args = ["--host=credstore.example.com"]
}

OpenTofu 使用 args 中给出的每个参数运行助手程序，然后是一个动词，最后是该动词将应用到的主机名。当前的动词集为

  • get：检索给定主机名的凭据
  • store：存储给定主机名的最新凭据
  • forget：删除给定主机名存储的任何凭据

为了表示凭据，凭据助手协议使用一个 JSON 对象，其内容对应于 CLI 配置中的 credentials 块 的内容。为了表示 API 令牌，该对象包含一个名为“token”的属性，其值为令牌字符串

代码块
{
  "token": "example-token-value"
}

以下部分描述了三种动词各自的预期行为。

get：检索给定主机名的凭据​

为了检索 app.example.io 的凭据，OpenTofu 将运行“credstore”助手，如下所示

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

如果凭据助手能够提供给定主机名的凭据，则它必须将 JSON 凭据对象打印到其 stdout 流，然后以状态码零退出以表示成功。

如果凭据助手明确地没有给定主机名的凭据，则它必须将一个空 JSON 对象打印到 stdout 并以状态码零退出。

如果凭据助手由于任何其他原因无法提供请求的凭据，则它必须将面向最终用户的纯文本错误消息打印到其 stderr 流，然后以非零状态码退出。

store：存储给定主机名的最新凭据​

为了存储 app.example.io 的最新凭据，OpenTofu 将运行“credstore”助手，如下所示

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

然后 OpenTofu 将 JSON 凭据对象写入助手程序的 stdin 流。如果助手能够存储给定的凭据，则它必须执行此操作，然后以状态码零退出，并且 stdout 或 stderr 上没有输出以表示成功。

如果由于任何原因无法存储给定的凭据，则它必须仍然完全读取其 stdin 直到 EOF，然后在以非零状态码退出之前将面向最终用户的纯文本错误消息打印到其 stderr 流。

新凭据必须完全替换为给定主机名存储的任何现有凭据。

forget：删除给定主机名存储的任何凭据​

为了忘记 app.example.io 的任何现有凭据，OpenTofu 将运行“credstore”助手，如下所示

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

forget 动词不使用任何 JSON 凭据对象。

如果助手程序能够删除其为给定主机名存储的凭据，或者如果尚未存储此类凭据，则它必须以状态码零退出，并且在 stdout 或 stderr 上不产生任何输出。

如果由于任何原因无法忘记存储的凭据，特别是如果助手无法确定凭据不再可用以检索，则助手程序必须将面向最终用户的纯文本错误消息打印到其 stderr 流，然后以非零状态码退出。

处理其他命令​

凭据助手协议将来可能会扩展为包含其他动词，因此为了向前兼容，凭据助手必须对任何不受支持的动词做出反应，方法是将面向最终用户的纯文本错误消息打印到其 stderr 流，然后以非零状态码退出。

处理不支持的凭据对象属性​

OpenTofu 在 JSON 凭据对象中仅定义 token 属性。

如果凭据助手被要求存储一个包含除 token 之外的任何属性的对象，并且无法忠实地保留它们，那么它必须表现得好像该对象不可存储一样，返回错误。它不能仅存储 token 值并默默地丢弃其他属性，因为这可能会改变凭据对象的含义。

如果在目标系统的约束条件下技术上可行，凭据助手应该优先考虑将整个 JSON 对象原样存储以供以后检索。对于更受约束的系统，仅存储 token 字符串是可以接受的，只要程序拒绝包含其他属性的对象，如上所述。

安装凭据助手​

OpenTofu 没有用于凭据助手的任何自动安装机制。相反，用户必须将助手程序可执行文件提取到 默认插件搜索位置 之一。

如果您正在打包一个用于分发的凭据助手，请将其放置在一个名为预期命名方案（terraform-credentials-example）的文件夹中，并且如果包含的存档格式支持它并且对目标操作系统有意义，请将文件标记为可执行文件，以提高它在提取后立即工作的机会。

OpenTofu 不会在搜索凭据助手时尊重 -plugin-dir 参数传递给 tofu init，因为凭据也由其他可以在 tofu init 之前运行的命令使用。仅支持默认搜索位置。