Encore Cloud 外部密钥库External Vaults完全指南从 GCP Secret Manager 引用密钥让密钥值永不落入 Encore【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore导读Encore Cloud 默认会将应用的密钥存入 Encore 自带的密钥库并在部署时同步复制到云厂商的 Secret Manager 中供运行时读取。外部密钥库External Vaults则更进一步让密钥直接指向外部密钥存储中的某个密钥按名称与版本引用密钥值从头到尾都不需要输入或存储在 Encore Cloud 中。阅读完本文你将掌握外部密钥库的工作原理、GCP Secret Manager 的完整接入步骤、通过 IAM deny policies 构建Encore 能管理访问但永远读不到密钥值的强安全边界以及在应用代码中引用外部密钥的方法。注意外部密钥库是Enterprise企业版功能需要联系 Encore 官方为你的组织启用。一、背景Encore 默认的密钥存储与分发方式在理解外部密钥库之前先要明白 Encore 的默认密钥模型。根据官方文档 Storing Secrets and API keysEncore 内置的密钥管理器让应用可以用普通变量的方式安全使用密钥import { secret } from encore.dev/config; // 部署用的个人访问令牌 const githubToken secret(GitHubAPIToken); // 运行时通过调用 githubToken() 解析出密钥值密钥值本身由开发者通过 Encore Cloud DashboardSettings → Secrets或 CLI 设置。从 set.go 的源码可以看到 CLI 命令的完整定义encore secret set --type types secret-name--type支持逗号分隔的development、production、preview、local四种环境类型及其别名dev、prod、pr、ephemeral也可用--env env-name指定单个具体环境具体环境的取值优先于环境类型。存入 Encore 后密钥默认的存储路径是生产环境 / 自有云账户Encore 在你自己的 GCP/AWS 账户中按需创建密钥管理器GCP KMS 或 AWS Secrets Manager把密钥复制过去再以 secret 环境变量的形式注入容器开发 / Encore Cloud 环境Encore 的开发云底层运行在 GCP 上与自托管 GCP 环境一致使用 GCP Secrets Manager本地encore run时自动同步到开发者本机。外部密钥库正是对这一默认路径的替代与其让 Encore 托管密钥值不如让应用运行时直接从外部密钥存储读取适合密钥由其他团队或系统持有、已有既定轮换流程、或政策要求密钥必须留在指定存储中的场景。二、工作原理外部密钥库的模型非常清晰连接 vault把一个 vault密钥库连接到你的 Encore 应用指向一个外部密钥存储例如某个 GCP 项目的 Secret Manager。配置引用单个密钥可以配置为引用该 vault 中的某个密钥——通过外部存储中的密钥名称secret ID和版本version——而不是保存一个由 Encore 管理的值。运行时直读应用运行时直接从外部存储读取密钥值Encore 不再保存该值。在代码层面应用依然通过secret(Name)按名称读取密钥见 docs/ts/primitives/secrets.md只有值的来源发生了变化——这正是外部密钥库设计上对开发者透明的地方。支持的提供商Provider状态GCP Secret Manager可用。可引用存储在 Google Cloud Secret Manager 中的密钥。AWS Secrets Manager正在积极开发中——如有兴趣可联系 Encore 官方。三、添加一个 vaultVault 在应用级别配置。前提条件你拥有该应用的Admin或Memberowner/writer角色该功能已为你的组织启用Enterprise 功能。操作步骤打开你的应用进入Settings → Secrets。在External Vaults区域点击Add External Vault添加外部密钥库。选择提供商例如 GCP Secret Manager。为 vault 取一个用于识别的名称。填写提供商配置见下文。点击Save。四、GCP Secret Manager 接入详解4.1 配置项连接一个 GCP Secret Manager vault 需要提供两项配置GCP AccountGCP 账户——Encore Cloud 用来访问 Secret Manager 的已连接 GCP 服务账号。如果还没有请先连接你的云账户。根据 own-cloud.md 的说明连接 GCP 时可以选择Encore Service AccountEncore 用自己的 Google 托管服务账号不共享任何凭据或Service Account JSON Key上传自建服务账号的 JSON 密钥两种认证方式。Project ID项目 ID——承载 Secret Manager 密钥的 GCP 项目。配置表单填写过程中Dashboard 会显示确切的账号邮箱和所需权限并提供一键复制copy-to-clipboard辅助。4.2 在 GCP 侧授权在持有密钥的 GCP 项目中需要为已连接的服务账号授予访问密钥的权限创建一个自定义 IAM 角色包含以下两个权限secretmanager.secrets.getIamPolicysecretmanager.secrets.setIamPolicy在 Secret Manager 中将上述角色授予已连接的 GCP 服务账号授予在你想要引用的那些密钥上。关键点连接账号只需要getIamPolicy和setIamPolicy并不需要读取密钥值本身的权限。Encore Cloud 正是利用这两个权限为你的应用运行时服务账号授予对引用密钥的访问权Encore 自身始终不需要读取密钥值。这与默认方案形成鲜明对比在默认的Encore 托管密钥路径下根据 own-cloud.md 中Secrets始终必需一节的说明连接账户需要roles/secretmanager.admin创建/版本化/删除密钥并授予 accessor而在外部密钥库方案中连接的账户刻意被裁剪为只管理 IAM 策略、不触碰密钥内容体现了 Encore Cloud 默认的最小权限least privilege安全原则见 Application Security。五、防止 Encore 读取密钥值IAM deny policies 双保险上面的权限设计有一个理论上的漏洞连接账号既然持有setIamPolicy原则上它可以给自己或它控制的其它主体授予读取密钥值的权限。如果安全模型要求Encore Cloud 能够管理访问、但永远不能读取密钥可以通过两条 GCP IAM deny policies 来强制实现。deny policies 优先于 allow policies——即使之后添加了allow绑定deny 规则依然生效。应将它们挂载在包含密钥的项目、文件夹或组织层级。5.1 策略一拒绝在生产项目之外访问密钥该 deny 策略会阻止所有主体对 Secret Manager 的access权限唯一例外是你生产项目组中属于服务账号的那些主体。即使 Encore 的连接账号给自己授予了 allow 绑定这条 deny 规则也会覆盖它——只有你的运行时工作负载能读取密钥值。将示例中的123456789012替换为允许读取密钥的项目数字 ID每个生产项目添加一条exceptionPrincipals条目{ displayName: Strict App Project Boundary for Secrets, rules: [ { denyRule: { deniedPrincipals: [principalSet://goog/public:all], exceptionPrincipals: [ principalSet://cloudresourcemanager.googleapis.com/projects/123456789012/type/ServiceAccount ], deniedPermissions: [secretmanager.googleapis.com/*.access] } } ] }5.2 策略二阻止 Encore 模拟impersonate服务账号上面的边界依赖只有生产服务账号能读密钥这一前提。为了防止 Encore 的连接账号通过模拟某个生产服务账号来绕过边界需要拒绝它使用 Service Account Credentials 的模拟impersonation权限。将deniedPrincipals替换为你的 Encore 连接/编排orchestrator服务账号的主体标识符{ displayName: Block Encore Orchestrator Impersonation Loophole, rules: [ { denyRule: { deniedPrincipals: [principal://goog/subject/app-1esdad...], deniedPermissions: [ iam.googleapis.com/serviceAccounts.getAccessToken, iam.googleapis.com/serviceAccounts.getOpenIdToken, iam.googleapis.com/serviceAccounts.signBlob, iam.googleapis.com/serviceAccounts.signJwt, iam.googleapis.com/serviceAccounts.implicitDelegation ] } } ] }两条策略同时生效后Encore Cloud 仍然可以管理哪些运行时身份允许读取某个密钥但无论直接读取还是通过模拟间接读取都无法获取密钥值本身。警告务必确认第一条策略中的exceptionPrincipals覆盖了应用实际运行所使用的每一个服务账号否则你的工作负载同样会被拒绝读取密钥值。六、AWS当前状态外部密钥库对AWS包括 AWS Secrets Manager的支持正在积极开发中。如果你运行在 AWS 上且希望从外部存储引用密钥可联系 Encore 官方说明你的使用场景并了解 AWS 支持的可用时间。七、在应用中引用一个 vault 密钥vault 连接完成后就可以让某个密钥指向它而不是在 Encore 中保存值进入Settings → Secrets创建或编辑一个密钥。输入值时选择vault作为值的来源。提供要引用的secret ID外部存储中的密钥名称和version版本。应用代码依旧按名称读取密钥——只有值的来源发生变化。不同环境可以像普通密钥一样引用不同的 vault 或版本例如生产环境引用 vault A 的版本 3预览环境引用 vault B 的版本 1。八、管理 vault在External Vaults区域你可以对 vault 执行**重命名Rename**一个 vault。编辑配置Edit configuration——修改提供商配置例如 GCP 账户或项目 ID。**移除Remove**一个 vault。每个 vault 都会显示当前引用它的密钥列表used by 列表移除前可以清楚看到影响范围。九、小结与延伸阅读外部密钥库在不改变应用代码的前提下把谁持有密钥值这一职责从 Encore Cloud 移交给了你的外部密钥存储配合两条 IAM deny policies 即可构建Encore 只管授权、永不接触明文的强安全边界。对于需要满足合规审计、密钥由外部团队轮换管理的场景这是 Encore 密钥体系的关键扩展。继续深入阅读Secrets——密钥在 Encore 中的工作方式含encore secret setCLI 命令与本地覆盖文件.secrets.local.cue的用法Application Security——Encore Cloud 如何默认保障应用安全Connect your cloud account——连接用于访问 Secret Manager 的 GCP 账户CLI 层参考实现cli/cmd/encore/secrets/set.go环境类型与别名的解析逻辑【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
