引用在 HashiCorp Vault 中的密钥
HashiCorp Vault 是一个集中式平台,用于管理不同环境和应用程序中的密钥和加密。它提供了一个统一的密钥管理平台,用于存储和访问 API 密钥、密码、证书等。
本教程演示了如何将 API7 企业版与 HashiCorp Vault 集成,使你能够安全地存储和引用 Vault 中的消费者凭据和插件配置。
前提条件
配置 Vault 服务器
在 Docker 中以开发模式启动一个名为 api7-quickstart-vault
的 Vault 实例,令牌为 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' \
--network=api7-quickstart-net \
--name api7-quickstart-vault \
-p 8200:8200 vault:1.13.0
API7 网关需要访问 Vault 和检索密钥的权限。你应该创建一个 HashiCorp 配置语言 (HCL) 策略文件来为 API7 网关生成 Vault 访问令牌。在 Vault 实例中创建一个名为 api7-policy.hcl
的 Vault 策略文件,以授予 API7 网关对路径 secret/
的读取权限。你可以将密钥放在路径 secret/
下以允许 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
接下来,生成附加到新定义的策略的访问令牌,以供 API7 网关访问 Vault:
docker exec api7-quickstart-vault vault token create -policy="api7-policy"
每次执行上述命令都会生成不同的令牌。如果成功,输出应类似于以下内容:
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
。 - 填写Secret 前缀字段。例如,
secret/api7
。 - 身份验证方法,选择
Token
。 - 填写令牌字段。
- 点击新增。
- Secret 提供商 ID,输入
暂不支持。
暂不支持。
引用密钥以创建消费者凭据
消费者凭据中的以下敏感字段可以存储在外部Secret 管理服务(HashiCorp Vault、AWS Secret Manager 等)中,并在 API7 网关中引用:
- Key Authentication 凭据中的
key
- Basic Authentication 凭据中的
password
- JWT 认证凭据中的
secret
、public key
- HMAC 认证凭据中的
secret key
新增消费者
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 点击新增消费者。
- 在对话框中,执行以下操作:
- 名称,输入
Alice
。 - 点击新增。
- 名称,输入
暂不支持。
暂不支持。
存储密钥
为 Key Authentication 凭据创建一个密钥 key=alice-primary-key
,并将其存储在 Vault 的路径 secret/api7/consumer/alice
中。确保路径与你配置的Secret 前缀一致:
docker exec api7-quickstart-vault vault kv put secret/api7/consumer/alice key=alice-primary-key
预期响应类似于以下内容:
=== Secret Path ===
secret/data/api7
======= Metadata =======
Key Value
--- -----
created_time 2023-03-15T11:42:17.123175125Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
重复创建其他消费者凭据的更多密钥,所有密钥都在同一路径下:
- 对于Basic Authentication 凭据:
docker exec api7-quickstart-vault vault kv put secret/api7/consumer/alice password=alice-password
- 对于 JWT 认证凭据:
docker exec api7-quickstart-vault vault kv put secret/api7/consumer/alice secret=alice-secret
- 对于 HMAC 认证凭据:
docker exec api7-quickstart-vault vault kv put secret/api7/consumer/alice secret-key=alice-secret-key
新增Key Authentication 凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice
。 - 凭据选项卡下,点击新增Key Authentication 凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-key
。 - Key,选择引用 Secret 提供商,然后输入
$secret://vault/my-vault/consumer/alice/key
。 - 点击新增。
- 名称,输入
所有密钥引用都以 $secret://
开头。vault
是 Secret 提供商的Secret 管理服务,my-vault
是Secret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault
将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/consumer/alice/key
。
暂不支持。
暂不支持。
新增Basic Authentication 凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice
。 - 凭据选项卡下,点击基本认证选项卡,然后点击新增Basic Authentication 凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-basic
。 - 用户名,输入
Alice
。 - 密码,选择引用 Secret 提供商,然后输入
$secret://vault/my-vault/consumer/alice/password
。 - 点击新增。
- 名称,输入
所有密钥引用都以 $secret://
开头。vault
是 Secret 提供商的Secret 管理服务,my-vault
是Secret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault
将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/consumer/alice/password
。
暂不支持。
暂不支持。
新增 JWT 认证凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice
。 - 凭据选项卡下,点击JWT选项卡,然后点击新增 JWT 凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-jwt
。 - Key,输入
alice-key
。 - 算法,选择
HS256
。 - 密钥,选择引用 Secret 提供商,然后输入
$secret://vault/my-vault/consumer/alice/secret
。 - 点击新增。
- 名称,输入
所有密钥引用都以 $secret://
开头。vault
是 Secret 提供商的Secret 管理服务,my-vault
是Secret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault
将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/consumer/alice/secret
。
暂不支持。
暂不支持。
新增 HMAC 认证凭据
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的消费者。
- 选择你的目标消费者,例如,
Alice
。 - 凭据选项卡下,点击HMAC 认证选项卡,然后点击新增 HMAC 认证凭据。
- 在对话框中,执行以下操作:
- 名称,输入
primary-hmac
。 - Key ID,输入
alice-keyid
。 - Secret Key,选择引用 Secret 提供商,然后输入
$secret://vault/my-vault/consumer/alice/secret-key
。 - 点击新增。
- 名称,输入
所有密钥引用都以 $secret://
开头。vault
是 Secret 提供商的Secret 管理服务,my-vault
是Secret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault
将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/consumer/alice/secret-key
。
暂不支持。
暂不支持。
引用密钥以启用插件
插件配置中的以下敏感字段可以存储在外部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 的路径 secret/api7/redis
中。确保路径与你配置的Secret 前缀一致:
docker exec api7-quickstart-vault vault kv put secret/api7/redis username=api7
预期响应类似于以下内容:
=== Secret Path ===
secret/data/api7
======= Metadata =======
Key Value
--- -----
created_time 2023-03-15T11:42:17.123175125Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
再次尝试存储 Redis 密码的密钥:
docker exec api7-quickstart-vault vault kv put secret/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
}
所有密钥引用都以 $secret://
开头。vault
是Secret 提供商的Secret 管理服务,my-vault
是Secret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault
将替换为Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/redis/username
和 secret/api7/redis/password
。
暂不支持。
暂不支持。