SPIFFE 中文

主题

本文为 SPIRE 官方文档 plugin_server_upstreamauthority_vault 的中文译本,以英文原文为准。

🔗 穿越源码分析:Server 详解 · UpstreamAuthority · 上游 CA 与无缝轮换

Upstream Authority "vault" 插件 ​

vault 插件使用 Vault PKI 引擎(PKI Engine)为 SPIRE 签名中间 CA 证书(intermediate CA certificate)。该插件不支持 PublishJWTKey RPC,因此不适用于使用 JWT-SVID 的嵌套(nested)SPIRE 拓扑。

配置 ​

该插件接受以下配置项:

键名类型是否必填说明默认值
vault_addrstringVault 服务器的 URL。(例如 https://vault.example.com:8443/)${VAULT_ADDR}
namespacestringVault 命名空间(namespace)的名称。仅在 Vault Enterprise 中可用。${VAULT_NAMESPACE}
pki_mount_pointstringPKI secret 引擎(secret engine)挂载点(mount point)的名称pki
ca_cert_pathstring用于校验 Vault 服务器证书的 CA 证书文件路径。仅支持 PEM 格式。${VAULT_CACERT}
insecure_skip_verifybool若为 true,vault 客户端将接受任意服务器证书false
cert_authstruct客户端证书(Client Certificate)认证方式的配置
token_authstruct令牌(Token)认证方式的配置
approle_authstructAppRole 认证方式的配置
k8s_authstructKubernetes 认证方式的配置

环境变量 ​

插件会读取以下环境变量。标注为"标准"的变量会被 Vault CLI 与客户端库原生识别——完整参考见 Vault 文档。

变量标准说明
VAULT_ADDR是Vault 服务器的地址
VAULT_CACERT是CA 证书文件的路径
VAULT_CLIENT_CERT是客户端证书文件的路径(cert 认证)
VAULT_CLIENT_KEY是客户端私钥文件的路径(cert 认证)
VAULT_NAMESPACE是Vault 命名空间(仅 Enterprise)
VAULT_TOKEN是Vault 令牌(token 认证)
VAULT_APPROLE_ID否AppRole 的 role ID —— SPIRE 专用,并非 Vault SDK 变量
VAULT_APPROLE_SECRET_ID否AppRole 的 secret ID —— SPIRE 专用,并非 Vault SDK 变量

插件支持 客户端证书(Client Certificate)、令牌(Token)、AppRole 和 Kubernetes 四种认证方式。

  • 客户端证书(Client Certificate) 方式使用 TLS 客户端证书向 Vault 认证。
  • 令牌(Token) 方式使用 HTTP 请求头中的令牌向 Vault 认证。
  • AppRole 方式使用由 Vault 签发的 RoleID 与 SecretID 向 Vault 认证。
  • Kubernetes 方式使用 Kubernetes 服务账号令牌(Service Account Token)向 Vault 认证。

ca_ttl SPIRE Server 配置项应小于或等于 Vault PKI secret 引擎的 TTL。要配置该 TTL 值,请对引擎进行调优(tune)。

例如:

shell
$ vault secrets tune -max-lease-ttl=8760h pki

所配置的令牌需要绑定到一个至少具备以下能力(capabilities)的策略(policy)上:

hcl
path "pki/root/sign-intermediate" {
  capabilities = ["update"]
}

客户端证书认证(Client Certificate Authentication) ​

键名类型是否必填说明默认值
cert_auth_mount_pointstringTLS 证书认证方式挂载点(mount point)的名称cert
cert_auth_role_namestringVault 角色(role)的名称。若给定,插件仅针对该命名角色进行认证。默认尝试所有角色。
client_cert_pathstring客户端证书文件的路径。仅支持 PEM 格式。${VAULT_CLIENT_CERT}
client_key_pathstring客户端私钥文件的路径。仅支持 PEM 格式。${VAULT_CLIENT_KEY}
hcl
    UpstreamAuthority "vault" {
        plugin_data {
            vault_addr = "https://vault.example.org/"
            pki_mount_point = "test-pki"
            ca_cert_path = "/path/to/ca-cert.pem"
            cert_auth {
                cert_auth_mount_point = "test-tls-cert-auth"
                client_cert_path = "/path/to/client-cert.pem"
                client_key_path  = "/path/to/client-key.pem"
            }
            // 若要指定用于认证的角色
            // cert_auth {
            //     cert_auth_mount_point = "test-tls-cert-auth"
            //     cert_auth_role_name = "test"
            //     client_cert_path = "/path/to/client-cert.pem"
            //     client_key_path  = "/path/to/client-key.pem"
            // }
       
            // 若通过环境变量指定密钥对,并使用修改后的挂载点
            // cert_auth {
            //    cert_auth_mount_point = "test-tls-cert-auth"
            // }

            // 若通过环境变量指定密钥对,并使用默认挂载点,则设为空结构体。
            // cert_auth {}
        }
    }

令牌认证(Token Authentication) ​

键名类型是否必填说明默认值
tokenstring要设置到 "X-Vault-Token" 请求头中的令牌字符串${VAULT_TOKEN}
hcl
    UpstreamAuthority "vault" {
        plugin_data {
            vault_addr = "https://vault.example.org/"
            pki_mount_point = "test-pki"
            ca_cert_path = "/path/to/ca-cert.pem"
            token_auth {
               token = "<token>"
            }
            // 若通过环境变量指定令牌,则设为空结构体。
            // token_auth {}
        }
    }

AppRole 认证(AppRole Authentication) ​

键名类型是否必填说明默认值
approle_auth_mount_pointstringAppRole 认证方式挂载点(mount point)的名称approle
approle_idstringAppRole 的标识符${VAULT_APPROLE_ID}
approle_secret_idstringAppRole 的凭据${VAULT_APPROLE_SECRET_ID}
hcl
    UpstreamAuthority "vault" {
        plugin_data {
            vault_addr = "https://vault.example.org/"
            pki_mount_point = "test-pki"
            ca_cert_path = "/path/to/ca-cert.pem"
            approle_auth {
               approle_auth_mount_point = "my-approle-auth"
               approle_id = "<Role ID>" // 或通过环境变量指定
               approle_secret_id = "<Secret ID>" // 或通过环境变量指定
            }
            // 若通过环境变量指定 approle_id 和 approle_secret,并使用修改后的挂载点
            // approle_auth {
            //    approle_auth_mount_point = "my-approle-auth"
            // }

            // 若通过环境变量指定 approle_id 和 approle_secret,并使用默认挂载点,则设为空结构体。
            // approle_auth {}
        }
    }

Kubernetes 认证(Kubernetes Authentication) ​

键名类型是否必填说明默认值
k8s_auth_mount_pointstringKubernetes 认证方式挂载点(mount point)的名称kubernetes
k8s_auth_role_namestring✔Vault 角色(role)的名称。插件针对该命名角色进行认证
token_pathstring✔用于向 Vault 认证的 Kubernetes 服务账号令牌(Service Account Token)的路径
hcl
    UpstreamAuthority "vault" {
        plugin_data {
            vault_addr = "https://vault.example.org/"
            pki_mount_point = "test-pki"
            ca_cert_path = "/path/to/ca-cert.pem"
            k8s_auth {
               k8s_auth_mount_point = "my-k8s-auth"
               k8s_auth_role_name = "my-role"
               token_path = "/path/to/sa-token"
            }
            
            // 若指定角色名,并使用默认挂载点与 token_path
            // k8s_auth {
            //   k8s_auth_role_name = "my-role"
            // }            
        }
    }