跳到主要内容
版本:3.9.x

安全凭证管理

保护 SSL 证书、API Key(API 密钥)和密码等敏感信息,是重要的安全与合规要求。API7 网关提供可靠的工具,既可以在网关内部安全管理这些凭证,也可以与外部密钥管理系统集成。

前置条件​

能力​

  • 安全 SSL 管理:集中存储并自动续订 SSL 证书。
  • 静态凭证加密:敏感值在存入网关配置数据库前会进行加密。
  • 密钥管理器集成:与 HashiCorp Vault、AWS Secrets Manager 和 Kubernetes Secrets 集成,集中控制密钥。
  • 环境变量支持:部署期间以环境变量形式注入密钥。

SSL 证书管理​

API7 网关允许通过控制面存储和管理 SSL 证书。可以将证书与特定域名(SNI)关联,为路由启用 HTTPS。

准备 PEM 证书和私钥​

使用 PEM 编码的服务器证书,以及与其匹配且不带口令的私钥。PEM 文件包含 -----BEGIN CERTIFICATE----- 和 -----BEGIN PRIVATE KEY----- 等块。标注用于 NGINX 或 Apache 的证书下载通常包含 PEM 文件;请检查文件内容,不要仅依赖文件名。PFX/PKCS#12 和 JKS 文件必须在上传前转换。重命名扩展名不会转换文件格式。

证书值必须以服务器证书开头,随后按顺序附上签发它的中间证书。不要包含无关证书或根 CA。私钥必须与第一个证书对应。

转换 PFX 或 PKCS#12​

使用 OpenSSL 3 或更高版本提取服务器证书、CA 证书和私钥。请在私有工作目录中运行以下命令;命令会提示输入 PFX 密码和临时私钥口令:

umask 077
openssl pkcs12 -in certificate.pfx -clcerts -nokeys -out leaf.pem
openssl pkcs12 -in certificate.pfx -cacerts -nokeys -out ca-chain.pem
openssl pkcs12 -in certificate.pfx -nocerts -out encrypted-key.pem
openssl x509 -in leaf.pem -out certificate.pem
openssl pkey -in encrypted-key.pem -out private-key.pem

仅保留 ca-chain.pem 中签发服务器证书的中间证书块,按从服务器证书签发者到根的顺序排列,并保存到 intermediate-ca.pem。将它们与服务器证书合并:

cat certificate.pem intermediate-ca.pem > certificate-chain.pem

如果服务器证书由受信任的根 CA 直接签发,请仅使用 certificate.pem 作为 certificate-chain.pem。如果 PFX 不包含中间证书,请向证书签发者获取。对于 OpenSSL 无法读取的旧式 PFX 加密,请参阅 openssl pkcs12 的 legacy 选项。

private-key.pem 不带口令,使网关可以在不提示输入密码的情况下加载它。请限制对该文件的访问,并在导入和验证证书后移除临时私钥文件。

转换 JKS 密钥库​

使用 Java Development Kit 中的 keytool 查找服务器 PrivateKeyEntry 的别名,然后仅将该条目导出为 PKCS#12:

keytool -list -keystore certificate.jks
keytool -importkeystore \
-srckeystore certificate.jks \
-srcstoretype JKS \
-srcalias YOUR_SERVER_KEY_ALIAS \
-destkeystore certificate.pfx \
-deststoretype PKCS12

根据提示输入源密钥库、私钥和目标密钥库的密码。然后按照上述 PFX 转换步骤操作。受信任证书条目不包含私钥,无法用作服务器的密钥对。有关密钥库和别名选项,请参阅 keytool 参考。

上传前验证​

检查服务器证书的名称和有效期,然后将其公钥与私钥的公钥比较:

openssl x509 -in certificate-chain.pem -noout -subject -issuer -dates -ext subjectAltName
openssl x509 -in certificate-chain.pem -pubkey -noout | openssl pkey -pubin -outform DER | openssl dgst -sha256
openssl pkey -in private-key.pem -pubout -outform DER | openssl dgst -sha256

两个 SHA-256 值必须一致。配置证书覆盖的 SNI,然后在下方的导入示例中使用证书链和私钥。导入后,请使用该主机名发送 HTTPS 请求,验证证书链和路由。

导入证书​

使用 jq 将 PEM 文件编码为 JSON 字符串,并保留其换行符。请将 SNI 和网关组 ID 替换为部署中的实际值:

jq -n \
--arg sni 'api.example.com' \
--rawfile cert certificate-chain.pem \
--rawfile key private-key.pem \
'{snis: [$sni], cert: $cert, key: $key}' > ssl.json

curl -k "https://localhost:7443/apisix/admin/ssls/example-com-ssl?gateway_group_id={gateway_group_id}" -X PUT \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
--data-binary @ssl.json

生成的 ssl.json 包含私钥。请将其保存在上述私有工作目录中,并在导入后移除。在生产环境中,请验证控制面的证书,不要使用 -k。

将 {gateway_group_id} 替换为控制台 网关组 页面中的网关组 ID。快速入门创建的网关组使用 default。将 $CERTIFICATE_CONTENT 和 $PRIVATE_KEY_CONTENT 替换为 PEM 编码的证书和私钥,并将换行符转义为 \n。

外部密钥管理器​

要实现企业级密钥管理,请使用外部密钥管理器。API7 网关可以在运行时直接从这些系统获取敏感值。

集成 HashiCorp Vault​

API7 网关可以在运行时从 HashiCorp Vault 获取敏感值。端到端流程如下:

  1. 通过 Admin API 在网关组中创建 Vault 密钥提供方。有关请求结构、必填字段(uri、prefix、token)、可选字段(kv_version、authentication_method),以及部署 Vault 实例和限制 Token 权限范围的步骤,请参阅配置 HashiCorp Vault 密钥提供方。
  2. 使用 $secret://{provider_type}/{provider_id}/{secret_key} URI 格式,在资源或插件配置中引用密钥。
# 在你的插件配置中
plugins:
key-auth:
key: "$secret://vault/my-vault/api-key-path/my-key"

静态凭证加密​

API7 控制面会在部分敏感字段(例如插件密码和密钥)存入配置数据库前进行加密。这可以减少日常查看数据库时的明文暴露,但如果数据库或备份遭到入侵,加密并不能保护这些凭证。请对数据库备份加密并严格控制访问。如果敏感值及其加密密钥必须保留在控制面之外,请将这些值存入外部密钥管理器,并在 API7 网关中引用。

后续步骤​