本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

认证方法

DeepSeek V3 中英对照 Authentication methods

不同的组织对安全性和身份验证有不同的要求。Vault 通过提供多种身份验证方法来满足这一需求。Spring Cloud Vault 支持令牌和 AppId 身份验证。

Token 身份验证

令牌是 Vault 中身份验证的核心方法。令牌身份验证需要通过配置提供一个静态令牌。作为备用方案，令牌也可以从 ~/.vault-token 中获取，这是 Vault CLI 用于缓存令牌的默认位置。

备注

令牌认证是默认的认证方式。如果令牌被泄露，非预期方将获得访问 Vault 的权限，并能够访问预期客户端的密钥。

spring.cloud.vault:
    authentication: TOKEN
    token: 00000000-0000-0000-0000-000000000000

authentication 将此值设置为 TOKEN 以选择令牌认证方法
token 设置要使用的静态令牌。如果缺失或为空，则将尝试从 ~/.vault-token 检索令牌。

另请参阅：

Vault Agent 身份验证

自 0.11.0 版本起，Vault 随 Vault Agent 附带了一个 sidecar 工具。Vault Agent 通过其自动认证功能实现了 Spring Vault 的 SessionManager 功能。应用程序可以依赖运行在 localhost 上的 Vault Agent 来重用缓存的会话凭据。Spring Vault 可以在不发送 X-Vault-Token 请求头的情况下发送请求。禁用 Spring Vault 的认证基础设施以禁用客户端认证和会话管理。

spring.cloud.vault:
    authentication: NONE

authentication 将此值设置为 NONE 将禁用 ClientAuthentication 和 SessionManager。

另请参阅：Vault 文档：代理

AppId 认证

Vault 支持 AppId 认证，该认证由两个难以猜测的令牌组成。AppId 默认为静态配置的 spring.application.name。第二个令牌是 UserId，这是由应用程序确定的一部分，通常与运行时环境相关。IP 地址、Mac 地址或 Docker 容器名称都是很好的例子。Spring Cloud Vault Config 支持 IP 地址、Mac 地址和静态 UserId（例如通过系统属性提供）。IP 和 Mac 地址以十六进制编码的 SHA256 哈希表示。

基于IP地址的用户ID使用本地主机的IP地址。

spring.cloud.vault:
    authentication: APPID
    app-id:
        user-id: IP_ADDRESS

authentication 将此值设置为 APPID 将选择 AppId 认证方法
app-id-path 设置要使用的 AppId 挂载路径
user-id 设置 UserId 方法。可能的值为 IP_ADDRESS、MAC_ADDRESS 或实现自定义 AppIdUserIdMechanism 的类名

从命令行生成 IP 地址用户 ID 的对应命令是：

$ echo -n 192.168.99.1 | sha256sum

备注

包含 echo 的换行符会导致不同的哈希值，因此请确保包含 -n 标志。

基于MAC地址的用户ID从绑定到本地主机的网络设备获取其网络设备。配置还允许指定一个 network-interface 提示来选择正确的设备。network-interface 的值是可选的，可以是接口名称或接口索引（从0开始）。

spring.cloud.vault:
    authentication: APPID
    app-id:
        user-id: MAC_ADDRESS
        network-interface: eth0

network-interface 设置用于获取物理地址的网络接口

从命令行生成 IP 地址用户 ID 的对应命令是：

$ echo -n 0AFEDE1234AC | sha256sum

备注

Mac 地址需指定为大写且不带冒号。包含 echo 的换行符会导致哈希值不同，因此请确保包含 -n 标志。

自定义用户ID

UserId 的生成是一个开放的机制。你可以将 spring.cloud.vault.app-id.user-id 设置为任意字符串，配置的值将作为静态 UserId 使用。

一种更高级的方法允许你将 spring.cloud.vault.app-id.user-id 设置为一个类名。该类必须位于你的类路径中，并且必须实现 org.springframework.cloud.vault.AppIdUserIdMechanism 接口及其 createUserId 方法。Spring Cloud Vault 每次使用 AppId 进行身份验证以获取令牌时，都会通过调用 createUserId 方法来获取 UserId。

spring.cloud.vault:
    authentication: APPID
    app-id:
        user-id: com.examlple.MyUserIdMechanism

public class MyUserIdMechanism implements AppIdUserIdMechanism {

  @Override
  public String createUserId() {
    String userId = ...
    return userId;
  }
}

另请参阅：Vault 文档：使用 App ID 认证后端

AppRole 认证

AppRole 旨在用于机器身份验证，类似于已弃用（自 Vault 0.6.1 起）的 AppId 身份验证。AppRole 身份验证包含两个难以猜测的（秘密）令牌：RoleId 和 SecretId。

Spring Vault 支持多种 AppRole 场景（推送/拉取模式和包装模式）。

必须通过配置提供 RoleId 和可选的 SecretId，Spring Vault 不会查找这些信息或创建自定义的 SecretId。

spring.cloud.vault:
    authentication: APPROLE
    app-role:
        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52

支持以下场景及所需的配置详情：

表 1. 配置

方法	角色ID	密钥ID	角色名称	令牌
提供角色ID/密钥ID	提供	提供
提供角色ID（无密钥ID）	提供
提供角色ID，拉取密钥ID	提供		提供	提供
拉取角色ID，提供密钥ID		提供	提供	提供
完全拉取模式			提供	提供
封装模式				提供
封装角色ID，提供密钥ID		提供		提供
提供角色ID，封装密钥ID	提供			提供

表 2. 拉取/推送/包装矩阵

RoleId	SecretId	Supported
Provided	Provided	✅
Provided	Pull	✅
Provided	Wrapped	✅
Provided	Absent	✅
Pull	Provided	✅
Pull	Pull	✅
Pull	Wrapped	❌
Pull	Absent	❌
Wrapped	Provided	✅
Wrapped	Pull	❌
Wrapped	Wrapped	✅
Wrapped	Absent	❌

备注

你仍然可以通过在上下文中提供一个配置好的 AppRoleAuthentication bean 来使用所有 push/pull/wrapped 模式的组合。Spring Cloud Vault 无法从配置属性中推导出所有可能的 AppRole 组合。

important

AppRole 认证仅限于使用响应式基础设施的简单拉取模式。目前尚不支持完全拉取模式。将 Spring Cloud Vault 与 Spring WebFlux 栈结合使用，会启用 Vault 的响应式自动配置，该功能可以通过设置 spring.cloud.vault.reactive.enabled=false 来禁用。

spring.cloud.vault:
    authentication: APPROLE
    app-role:
        role-id: bde2076b-cccb-3cf0-d57e-bca7b1e83a52
        secret-id: 1696536f-1976-73b1-b241-0b4213908d39
        role: my-role
        app-role-path: approle

role-id 设置 RoleId。
secret-id 设置 SecretId。如果 AppRole 配置为不需要 SecretId（参见 bind_secret_id），则可以省略 SecretId。
role：为拉取模式设置 AppRole 名称。
app-role-path 设置要使用的 AppRole 认证挂载路径。

另请参阅：Vault 文档：使用 AppRole 认证后端

AWS-EC2 认证

aws-ec2 认证后端为 AWS EC2 实例提供了一种安全的引入机制，允许自动获取 Vault 令牌。与大多数 Vault 认证后端不同，该后端不需要首次部署或配置安全敏感凭据（令牌、用户名/密码、客户端证书等）。相反，它将 AWS 视为可信第三方，并使用唯一代表每个 EC2 实例的加密签名动态元数据信息。

spring.cloud.vault:
    authentication: AWS_EC2

AWS-EC2 认证默认启用一次性随机数（nonce），以遵循首次使用信任（TOFU）原则。任何意外获得 PKCS#7 身份元数据访问权限的第三方都可以对 Vault 进行身份验证。

首次登录时，Spring Cloud Vault 会生成一个随机数，该随机数与实例 ID 一同存储在认证后端。重新认证时需要发送相同的随机数。任何其他方都无法获取该随机数，从而可以在 Vault 中触发警报以便进一步调查。

nonce 保存在内存中，在应用程序重启时会丢失。您可以使用 spring.cloud.vault.aws-ec2.nonce 配置静态 nonce。

AWS-EC2 认证角色是可选的，默认使用 AMI 中的设置。您可以通过设置 spring.cloud.vault.aws-ec2.role 属性来配置认证角色。

spring.cloud.vault:
    authentication: AWS_EC2
    aws-ec2:
        role: application-server

spring.cloud.vault:
    authentication: AWS_EC2
    aws-ec2:
        role: application-server
        aws-ec2-path: aws-ec2
        identity-document: http://...
        nonce: my-static-nonce

authentication 将此值设置为 AWS_EC2 以选择 AWS EC2 身份验证方法
role 设置尝试登录时所针对的角色名称
aws-ec2-path 设置要使用的 AWS EC2 挂载路径
identity-document 设置 PKCS#7 AWS EC2 身份文档的 URL
nonce 用于 AWS-EC2 身份验证。空 nonce 值默认为生成 nonce

另请参阅：Vault 文档：使用 aws 认证后端

AWS-IAM 身份验证

aws 后端为 AWS IAM 角色提供了一种安全的身份验证机制，允许基于运行中应用程序的当前 IAM 角色自动进行 Vault 身份验证。与大多数 Vault 身份验证后端不同，此后端不需要首次部署或配置安全敏感的凭据（令牌、用户名/密码、客户端证书等）。相反，它将 AWS 视为可信第三方，并使用调用方使用其 IAM 凭据签名的 4 条信息来验证调用方确实在使用该 IAM 角色。

应用程序当前运行的IAM角色是自动计算的。如果您在AWS ECS上运行应用程序，那么应用程序将使用分配给运行容器的ECS任务的IAM角色。如果您在EC2实例上直接运行应用程序，那么使用的IAM角色将是分配给EC2实例的角色。

在使用AWS-IAM认证时，您必须在Vault中创建一个角色，并将其分配给您的IAM角色。如果role为空，则默认为当前IAM角色的友好名称。

spring.cloud.vault:
    authentication: AWS_IAM

spring.cloud.vault:
    authentication: AWS_IAM
    aws-iam:
        region: aws-global
        role: my-dev-role
        aws-path: aws
        server-name: some.server.name
        endpoint-uri: https://sts.eu-central-1.amazonaws.com

region 设置 AWS 区域的名称。如果未提供，区域将由 AWS 默认值确定。
role 设置尝试登录时所针对的角色的名称。这应绑定到您的 IAM 角色。如果未提供，则将使用当前 IAM 用户的友好名称作为 Vault 角色。
aws-path 设置要使用的 AWS 挂载路径
server-name 设置用于 X-Vault-AWS-IAM-Server-ID 标头的值，以防止某些类型的重放攻击。
endpoint-uri 设置用于 iam_request_url 参数的 AWS STS API 的值。

AWS-IAM 需要 AWS Java SDK v2 依赖项 (software.amazon.awssdk:auth)，因为其认证实现使用了 AWS SDK 类型来处理凭证和请求签名。

另请参阅：Vault 文档：使用 aws 认证后端

Azure MSI 身份验证

azure 认证后端为 Azure VM 实例提供了一种安全的引入机制，允许自动获取 Vault 令牌。与大多数 Vault 认证后端不同，此后端不需要首次部署或配置安全敏感的凭据（令牌、用户名/密码、客户端证书等）。相反，它将 Azure 视为可信第三方，并使用可绑定到 VM 实例的托管服务标识和实例元数据信息。

spring.cloud.vault:
    authentication: AZURE_MSI
    azure-msi:
        role: my-dev-role

spring.cloud.vault:
    authentication: AZURE_MSI
    azure-msi:
        role: my-dev-role
        azure-path: azure
        metadata-service: http://169.254.169.254/metadata/instance…
        identity-token-service: http://169.254.169.254/metadata/identity…

role 设置尝试登录时所针对的角色名称。
azure-path 设置要使用的 Azure 挂载路径
metadata-service 设置访问实例元数据服务的 URI
identity-token-service 设置访问身份令牌服务的 URI

Azure MSI 身份认证从实例元数据服务获取虚拟机的环境详情（订阅 ID、资源组、VM 名称）。Vault 服务器的资源 ID 默认为 [vault.hashicorp.com](https://vault.hashicorp.com)。如需更改，请相应设置 spring.cloud.vault.azure-msi.identity-token-service。

另请参阅：

TLS 证书认证

cert 认证后端允许使用 SSL/TLS 客户端证书进行身份验证，这些证书可以由 CA 签发或为自签名证书。

要启用 cert 认证，你需要：

使用 SSL，请参阅 Vault 客户端 SSL 配置
配置一个包含客户端证书和私钥的 Java Keystore
将 spring.cloud.vault.authentication 设置为 CERT

spring.cloud.vault:
    authentication: CERT
    ssl:
        key-store: classpath:keystore.jks
        key-store-password: changeit
        key-store-type: JKS
        cert-auth-path: cert
        role: my-dev-role

另请参阅：Vault 文档：使用 Cert 认证后端

Cubbyhole 认证

Cubbyhole 认证利用 Vault 的原语来提供安全的认证工作流。Cubbyhole 认证使用令牌作为主要的登录方法。一个临时令牌用于从 Vault 的 Cubbyhole 秘密后端获取第二个登录 VaultToken。登录令牌通常具有更长的有效期，用于与 Vault 进行交互。登录令牌将从存储在 /cubbyhole/response 的包装响应中检索。

创建包装代币

备注

创建令牌的响应封装功能需要 Vault 0.6.0 或更高版本。

$ vault token-create -wrap-ttl="10m"
Key                            Value
---                            -----
wrapping_token:                397ccb93-ff6c-b17b-9389-380b01ca2645
wrapping_token_ttl:            0h10m0s
wrapping_token_creation_time:  2016-09-18 20:29:48.652957077 +0200 CEST
wrapped_accessor:              46b6aebb-187f-932a-26d7-4f3d86a68319

spring.cloud.vault:
    authentication: CUBBYHOLE
    token: 397ccb93-ff6c-b17b-9389-380b01ca2645

另请参阅：

GCP-GCE 认证

gcp 认证后端允许使用现有的 GCP（Google Cloud Platform）IAM 和 GCE 凭证登录 Vault。

GCP GCE（Google Compute Engine）身份验证会为服务账户创建一个JSON Web Token（JWT）形式的签名。Compute Engine实例的JWT可通过实例身份验证从GCE元数据服务获取。此API会创建一个可用于确认实例身份的JSON Web Token。

与大多数 Vault 认证后端不同，此后端不需要首次部署或配置安全敏感凭据（令牌、用户名/密码、客户端证书等）。相反，它将 GCP 视为可信第三方，并使用加密签名的动态元数据信息，该信息唯一地代表每个 GCP 服务账户。

spring.cloud.vault:
    authentication: GCP_GCE
    gcp-gce:
        role: my-dev-role

spring.cloud.vault:
    authentication: GCP_GCE
    gcp-gce:
        gcp-path: gcp
        role: my-dev-role
        service-account: my-service@projectid.iam.gserviceaccount.com

role 设置登录尝试所针对的角色名称。
gcp-path 设置要使用的 GCP 挂载路径
service-account 允许将服务账户 ID 覆盖为特定值。默认为 default 服务账户。

另请参阅：

GCP-IAM 身份验证

gcp 认证后端允许使用现有的 GCP（Google Cloud Platform）IAM 和 GCE 凭证登录 Vault。

GCP IAM 认证为服务账户创建 JSON Web Token (JWT) 形式的签名。服务账户的 JWT 通过调用 GCP IAM 的 projects.serviceAccounts.signJwt API 获得。调用方通过 GCP IAM 进行身份验证，从而证明其身份。此 Vault 后端将 GCP 视为可信第三方。

IAM 凭证可以从运行时环境中获取，具体通过 GOOGLE_APPLICATION_CREDENTIALS 环境变量、Google Compute 元数据服务，或者以外部方式提供，例如 JSON 或 base64 编码。JSON 是首选形式，因为它包含调用 projects.serviceAccounts.signJwt 所需的项目 ID 和服务账号标识符。

spring.cloud.vault:
    authentication: GCP_IAM
    gcp-iam:
        role: my-dev-role

spring.cloud.vault:
    authentication: GCP_IAM
    gcp-iam:
        credentials:
            location: classpath:credentials.json
            encoded-key: e+KApn0=
        gcp-path: gcp
        jwt-validity: 15m
        project-id: my-project-id
        role: my-dev-role
        service-account-id: my-service@projectid.iam.gserviceaccount.com

role 设置尝试登录时所针对的角色名称。
credentials.location 包含 JSON 格式 Google 凭据的凭据资源路径。
credentials.encoded-key JSON 格式的 OAuth2 账户私钥的 base64 编码内容。
gcp-path 设置要使用的 GCP 挂载路径
jwt-validity 配置 JWT 令牌的有效期。默认为 15 分钟。
project-id 允许将项目 ID 覆盖为特定值。默认为从获取的凭据中得到的项目 ID。
service-account 允许将服务账户 ID 覆盖为特定值。默认为从获取的凭据中得到的服务账户。

GCP IAM 身份验证需要 Google Cloud Java SDK 依赖项（com.google.apis:google-api-services-iam 和 com.google.auth:google-auth-library-oauth2-http），因为身份验证实现使用 Google API 进行凭据和 JWT 签名。

备注

Google 凭据需要维护令牌生命周期的 OAuth 2 令牌。所有 API 都是同步的，因此 GcpIamAuthentication 不支持响应式使用所需的 AuthenticationSteps。

另请参阅：

GitHub 身份验证

您可以通过提供个人访问令牌，使用 GitHub 身份验证来验证 Vault。作为备用方案，如果已安装并验证了 GitHub CLI，也可以从中检索令牌。

spring.cloud.vault:
    authentication: GITHUB
    github:
        token: gho_…

authentication 将此值设置为 GITHUB 以选择 GitHub 身份验证方法
token 设置要使用的静态令牌。如果缺失或为空，则如果已安装并认证了 GitHub CLI 且通过 spring.cloud.vault.github.allow-cli-token=true 允许访问，则可以尝试从 gh auth token 检索令牌。
allow-cli-token 启用回退到 GitHub CLI 以检索令牌。默认禁用，以避免意外调用 GitHub CLI。

另请参阅：

Kubernetes 身份验证

Kubernetes 认证机制（自 Vault 0.8.3 起）允许使用 Kubernetes 服务账户令牌向 Vault 进行身份验证。该认证基于角色，且角色绑定至特定的服务账户名称和命名空间。

一个包含 Pod 服务账户 JWT 令牌的文件会自动挂载在 /var/run/secrets/kubernetes.io/serviceaccount/token 路径下。

spring.cloud.vault:
    authentication: KUBERNETES
    kubernetes:
        role: my-dev-role
        kubernetes-path: kubernetes
        service-account-token-file: /var/run/secrets/kubernetes.io/serviceaccount/token

role 设置角色。
kubernetes-path 设置要使用的 Kubernetes 挂载路径。
service-account-token-file 设置包含 Kubernetes 服务账户令牌的文件位置。默认为 /var/run/secrets/kubernetes.io/serviceaccount/token。

另请参阅：

Pivotal CloudFoundry 认证

pcf 认证后端为在 Pivotal 的 CloudFoundry 实例中运行的应用程序提供了一种安全的引入机制，允许自动获取 Vault 令牌。与大多数 Vault 认证后端不同，该后端不需要首次部署或配置安全敏感的凭据（令牌、用户名/密码、客户端证书等），因为身份配置由 PCF 本身处理。相反，它将 PCF 视为可信第三方，并使用托管实例身份。

spring.cloud.vault:
    authentication: PCF
    pcf:
        role: my-dev-role

spring.cloud.vault:
    authentication: PCF
    pcf:
        role: my-dev-role
        pcf-path: path
        instance-certificate: /etc/cf-instance-credentials/instance.crt
        instance-key: /etc/cf-instance-credentials/instance.key

role 设置登录尝试所针对的角色名称。
pcf-path 设置要使用的 PCF 挂载路径。
instance-certificate 设置 PCF 实例身份证书的路径。默认为 ${CF_INSTANCE_CERT} 环境变量。
instance-key 设置 PCF 实例身份密钥的路径。默认为 ${CF_INSTANCE_KEY} 环境变量。

备注

PCF 认证要求在类路径中包含 BouncyCastle (bcpkix-jdk15on) 以支持 RSA PSS 签名。

另请参阅：Vault 文档：使用 pcf 认证后端

ACL 要求

本节将介绍 Spring Vault 访问的路径，以便您根据所需功能推导出策略声明。

能力	关联的 HTTP 动词
创建	`POST`/`PUT`
读取	`GET`
更新	`POST`/`PUT`
删除	`DELETE`
列表	`LIST` (`GET`)

另请参阅 www.vaultproject.io/guides/identity/policies。

身份验证

KeyValue 挂载发现

GET sys/internal/ui/mounts/$mountPath

SecretLeaseContainer

SecretLeaseContainer 根据配置的租约端点使用不同的路径。

LeaseEndpoints.Legacy

吊销：PUT sys/revoke
续期：PUT sys/renew

LeaseEndpoints.Leases (SysLeases)

撤销：PUT sys/leases/revoke
续租：PUT sys/leases/renew

会话管理

令牌查询：GET auth/token/lookup-self
续期：POST auth/token/renew-self
撤销：POST auth/token/revoke-self

Token 身份验证​

Vault Agent 身份验证​

AppId 认证​

自定义用户ID​

AppRole 认证​

AWS-EC2 认证​

AWS-IAM 身份验证​

Azure MSI 身份验证​

TLS 证书认证​

Cubbyhole 认证​

GCP-GCE 认证​

GCP-IAM 身份验证​

GitHub 身份验证​

Kubernetes 身份验证​

Pivotal CloudFoundry 认证​

ACL 要求​

身份验证​

KeyValue 挂载发现​

SecretLeaseContainer​

会话管理​

Token 身份验证

Vault Agent 身份验证

AppId 认证

自定义用户ID

AppRole 认证

AWS-EC2 认证

AWS-IAM 身份验证

Azure MSI 身份验证

TLS 证书认证

Cubbyhole 认证

GCP-GCE 认证

GCP-IAM 身份验证

GitHub 身份验证

Kubernetes 身份验证

Pivotal CloudFoundry 认证

ACL 要求

身份验证

KeyValue 挂载发现

SecretLeaseContainer

会话管理