引用 HashiCorp Vault 中的密钥
HashiCorp Vault 是一个集中式平台,用于管理不同环境和应用程序中的密钥和加密。它提供了一个统一的密钥管理平台,用于存储和访问 API 密钥、密码、证书等。
本教程演示了如何将 API7 Enterprise 与 HashiCorp Vault 集成,使你能够安全地存储和引用 Vault 中的消费者凭据和插件配置。
以下互动演示介绍如何使用 API7 Enterprise 在 HashiCorp Vault 中存储和获取 key-auth 密钥。
前提条件
- 安装 API7 Enterprise。
- 在你的网关组中至少有一个网关实例。
- 安装 Docker。
- 安装 cURL 以向服务发送请求进行验证。
- 安装 ZIP 以解压缩 官方分发的压缩文件 中的 Vault 二进制文件。
配置 Vault 服务器
在 Docker 中以开发模式启动一个名为 api7-quickstart-vault 的 Vault 实例,Token 为 api7-quickstart-vault-token。暴露的端口映射到主机上的 8200:
docker run -d --cap-add=IPC_LOCK \
-e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200' \
-e 'VAULT_ADDR=http://127.0.0.1:8200' \
-e 'VAULT_DEV_ROOT_TOKEN_ID=api7-quickstart-vault-token' \
-e 'VAULT_TOKEN=api7-quickstart-vault-token' \
--name api7-quickstart-vault \
-p 8200:8200 vault:1.13.0
在 Vault 中启用 kv 密钥引擎,作为 API7 SSL 证书的存储路径。
docker exec api7-quickstart-vault vault secrets enable -path=kv -version=1 kv
API7 网关需要访问 Vault 和读取密钥的权限。请使用 HashiCorp 配置语言(HCL) 创建策略文件,为 API7 网关生成 Vault 访问 Token。
在 Vault 实例中创建名为 api7-policy.hcl 的策略文件,授予 API7 网关读取 kv/ 路径的权限。你可以将密钥存储在 kv/ 路径下,供 API7 网关读取:
docker exec api7-quickstart-vault /bin/sh -c "echo '
path \"secret/data/*\" {
capabilities = [\"read\"]
}
' > /etc/api7-policy.hcl"
将策略文件应用于 Vault 实例:
docker exec api7-quickstart-vault vault policy write api7-policy /etc/api7-policy.hcl
接下来,生成附加到新定义的策略的访问 Token,以供 API7 网关访问 Vault:
docker exec api7-quickstart-vault vault token create -policy="api7-policy"
每次执行上述命令都会生成不同的 Token。如果成功,输出应类似于以下内容:
Key Value
--- -----
token hvs.CAESIHUznrV4wgcifUia0FROd6iprK7NjipAiHBYwiZDQP9TGh4KHGh2cy5ndHc5dzBPbXd5Y1pzblZXd2ZuQXA3ZHI
token_accessor YY4iCj2lICDNd50ZJDsBjvZK
token_duration 768h
token_renewable true
token_policies ["api7-policy" "default"]
identity_policies []
policies ["api7-policy" "default"]
在网关组中新增 Secret 提供商
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的Secret 提供商,然后点击新增 Secret 提供商。
- 在对话框中,执行以下操作:
- Secret 提供商 ID,输入
my-vault。 - Secret 管理服务,选择
HashiCorp Vault。 - KV 版本,选择
KV version 1。 - 填写Vault 服务器 URL字段。例如,
127.0.0.1:8200。 - 填写Secret 前缀字段。例如,
kv/api7。 - 身份验证方法,选择
Token。 - 填写 Token 字段。
- 点击新增。
- 复制 Secret 变量以供后续引用。所有密钥引用均由该变量生成,例如
$secret://vault/my-vault/$secret_name/$key。
不适用。
API7 Ingress Controller 目前不支持 Secret 提供商。
引用密钥配置 SSL 证书
SSL 证书对象中的敏感字段 certificate 和 private key 可以安全地存储在外部 Secret 管理服务(例如 HashiCorp Vault 或 AWS Secret Manager)中,并在 API7 网关中引用。
存储密钥
为证书和私钥创建两个密钥,并将其存储在 Vault 的路径 kv/api7/ssl 中。确保路径与你配置的 Secret 前缀一致:
docker exec api7-quickstart-vault vault kv put kv/api7/ssl crt="MIIDHzCCAgegAwIBAgIUXO7pD7m/P9R9uMh8Y+Q4h1Q+E4YwDQYJKoZIhvcNAQEL\nBQAwRTELMAkGA1UEBhMCQ04xEjAQBgNVBAgMCVhpYW1lbmd4aWExDjAMBgNVBAoM\nBU15Q29tMQ0wCwYDVQQDDARUZXN0MB4XDTI0MDMxMzE1NDkyOFoXDTI1MDMxMzE1\nNDkyOFowRTELMAkGA1UEBhMCQ04xEjAQBgNVBAgMCVhpYW1lbmd4aWExDjAMBgNV\nBAoMBU15Q29tMQ0wCwYDVQQDDARUZXN0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\nMIIBCgKCAQEAyYt7Xm4w2T5L/pXJ39j9WzQ13w1/mUa4gC77V9p0+f9w8j+yK0Y\nb/q2/Vb+b/0/vj9s7d38/7Xq+Gq2q8rB+7j1y/6t/d/v/w/q9y+2b7Jv/J38/9r/\nn9u/b/7/x/3f+D9x/z/v/x/3P7D/r/7/8P6/8/+/0/v/7f7z+2/3P7P+7/6/7v+7\nf3/9/8P3P9v9z+7/7v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v\n8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v8v"
docker exec api7-quickstart-vault vault kv put kv/api7/ssl private-key="VGhpcyBpcyBhIHNpbXVsYXRlZCBwcml2YXRlIGtleSBmb3IgZGVtb25zdHJhdGlvbiBwdXJwb3NlcyBPTkxZLiBETyBOT1QgdXNlIHRoaXMgaW4gcHJvZHVjdGlvbiEK"
新增 SSL 证书
- 从侧边栏选择网关组的证书,进入 SSL 证书选项卡。
- 点击新增 SSL 证书。
- 在对话框中,执行以下操作:
- 在名称字段中输入
Test SSL Certificate。 - 在证书字段中输入
$secret://vault/my-vault/ssl/crt。 - 在私钥字段中输入
$secret://vault/my-vault/ssl/private-key。 - 点击新增。
连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际 Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 kv/api7/ssl/crt。
- 有关 SSL 证书的完整使用和验证步骤,请参阅在客户端与 API7 网关之间配置 mTLS。
引用密钥以创建消费者凭据
消费者凭据中的以下敏感字段可以存储在外部 Secret 管理服务(HashiCorp Vault、AWS Secret Manager 等)中,并在 API7 网关中引用:
- Key Authentication 凭据中的
key - Basic Authentication 凭据中的
password - JWT 认证凭据中的
secret、public key - HMAC 认证凭据中的
secret key
新增消费者
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 点击新增消费者。
- 在对话框中,执行以下操作:
- 名称,输入
Alice。 - 点击新增。
要使用 ADC 创建消费者,请添加以下配置:
consumers:
- username: Alice
将配置同步到 API7 Enterprise:
adc sync -f consumer.yaml
API7 Ingress Controller 目前不支持 Secret 提供商。
存储密钥
为 Key Authentication 凭据创建一个密钥 key=alice-primary-key,并将其存储在 Vault 的路径 kv/api7/consumer/alice 中。确保路径与你配置的 Secret 前缀一致:
docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice key=alice-primary-key
预期响应类似于以下内容:
=== Secret Path ===
kv/data/api7/consumer/alice
======= Metadata =======
Key Value
--- -----
created_time 2023-03-15T11:42:17.123175125Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
重复创建其他消费者凭据的更多密钥,存储在同一路径下(注意:KV v1 会覆盖已有密钥):
- 对于 Basic Authentication 凭据:
docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice password=alice-password
- 对于 JWT 认证凭据:
docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice secret=alice-secret
- 对于 HMAC 认证凭据:
docker exec api7-quickstart-vault vault kv put kv/api7/consumer/alice secret-key=alice-secret-key
新增 Key Authentication 凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice。 - 凭据选项卡下,点击新增 Key Authentication 凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-key。 - Key,输入
$secret://vault/my-vault/consumer/alice/key。 - 点击新增。
连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 kv/api7/consumer/alice/key。
要使用 ADC 创建具有 key-auth 凭据的消费者,请更新配置:
consumers:
- username: Alice
credentials:
- name: primary-key
type: key-auth
config:
key: $secret://vault/my-vault/consumer/alice/key
将配置同步到 API7 Enterprise:
adc sync -f consumer.yaml
API7 Ingress Controller 目前不支持 Secret 提供商。
新增 Basic Authentication 凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice。 - 凭据选项卡下,点击基本认证选项卡,然后点击新增 Basic Authentication 凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-basic。 - 用户名,输入
Alice。 - 密码,输入
$secret://vault/my-vault/consumer/alice/password。 - 点击新增。
连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 kv/api7/consumer/alice/password。
要使用 ADC 创建具有 basic-auth 凭据的消费者,请更新配置:
consumers:
- username: Alice
credentials:
- name: primary-basic
type: basic-auth
config:
password: $secret://vault/my-vault/consumer/alice/password
username: Alice
将配置同步到 API7 Enterprise:
adc sync -f consumer.yaml
API7 Ingress Controller 目前不支持 Secret 提供商。
新增 JWT 认证凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice。 - 凭据选项卡下,点击JWT选项卡,然后点击新增 JWT 凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-jwt。 - Key,输入
alice-key。 - 算法,选择
HS256。 - 密钥,输入
$secret://vault/my-vault/consumer/alice/secret。 - 点击新增。
连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 kv/api7/consumer/alice/secret。
要使用 ADC 创建具有 jwt-auth 凭据的消费者,请更新配置:
consumers:
- username: Alice
credentials:
- name: primary-jwt
type: jwt-auth
config:
algorithm: HS256
key: alice-key
secret: $secret://vault/my-vault/consumer/alice/secret
将配置同步到 API7 Enterprise:
adc sync -f consumer.yaml
API7 Ingress Controller 目前不支持 Secret 提供商。
新增 HMAC 认证凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice。 - 凭据选项卡下,点击HMAC 认证选项卡,然后点击新增 HMAC 认证凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-hmac。 - Key ID,输入
alice-keyid。 - Secret Key,输入
$secret://vault/my-vault/consumer/alice/secret-key。 - 点击新增。
连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 kv/api7/consumer/alice/secret-key。
要使用 ADC 创建具有 hmac-auth 凭据的消费者,请更新配置:
consumers:
- username: Alice
credentials:
- name: primary-hmac
type: hmac-auth
config:
key_id: alice-keyid
secret_key: $secret://vault/my-vault/consumer/alice/secret-key
将配置同步到 API7 Enterprise:
adc sync -f consumer.yaml
API7 Ingress Controller 目前不支持 Secret 提供商。
验证
验证 Key Authentication
参阅为 API 启用 Key Authentication,在服务级别启用 key-auth 插件,然后按照验证 Key Authentication进行验证。
验证 Basic Authentication
参阅为 API 启用 Basic Authentication,在服务级别启用 basic-auth 插件,然后按照验证 Basic Authentication进行验证。
验证 JWT Authentication
参阅为 API 启用 JWT Authentication,在服务级别启用 jwt-auth 插件,然后按照验证 JWT Authentication进行验证。
验证 HMAC Authentication
参阅为 API 启用 HMAC Authentication,在服务级别启用 hmac-auth 插件,然后按照验证 HMAC Authentication进行验证。
引用密钥以启用插件
插件配置中的以下敏感字段可以存储在外部 Secret 管理服务(HashiCorp Vault、AWS Secret Manager 等)中,并在 API7 网关中引用:
| 插件 | 字段 |
|---|---|
| Limit Count | redis_username、redis_password |
| Authz-Casdoor | client_id、client_secret |
| Wolf RBAC | appid |
| LDAP 认证 | user_dn |
本节以配置 Limit Count 插件为例。
创建密钥
创建一个密钥 username=api7,并将其存储在 Vault 的路径 kv/api7/redis 中。确保路径与你配置的 Secret 前缀一致:
docker exec api7-quickstart-vault vault kv put kv/api7/redis username=api7
预期响应类似于以下内容:
=== Secret Path ===
kv/data/api7/redis
======= Metadata =======
Key Value
--- -----
created_time 2023-03-15T11:42:17.123175125Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
存储 Redis 密码的密钥(注意:KV v1 会覆盖已有密钥):
docker exec api7-quickstart-vault vault kv put kv/api7/redis password=redis-api7
配置 Limit Count 插件
有关 Limit Count 插件的启用位置和方式,请参阅为 API 配置限流。
- 控制台
- ADC
- Ingress Controller
将以下配置添加到JSON 编辑器:
{
"count": 3,
"time_window": 60,
"key_type": "var",
"rejected_code": 429,
"rejected_msg": "Too many requests",
"key": "remote_addr",
"policy": "redis",
"redis_host": "127.0.0.1",
"redis_port": 6379,
"redis_username": "$secret://vault/my-vault/redis/username",
"redis_password": "$secret://vault/my-vault/redis/password",
"redis_database": 1,
"redis_timeout": 1001,
"allow_degradation": false,
"show_limit_quota_header": true
}
连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 kv/api7/redis/username 和 kv/api7/redis/password。
以下示例仅包含插件配置,无法作为完整配置文件进行同步。有关使用 ADC 启用 Limit Count 插件的位置和方式,请参阅为 API 配置限流。
limit-count:
count: 3
time_window: 60
key_type: var
rejected_code: 429
rejected_msg: Too many requests
key: remote_addr
policy: redis
redis_host: 127.0.0.1
redis_port: 6379
redis_username: $secret://vault/my-vault/redis/username
redis_password: $secret://vault/my-vault/redis/password
redis_database: 1
redis_timeout: 1001
allow_degradation: false
show_limit_quota_header: true
API7 Ingress Controller 目前不支持 Secret 提供商。