跳到主要内容
版本:3.2.16.3

引用在 HashiCorp Vault 中的密钥

HashiCorp Vault 是一个集中式平台,用于管理不同环境和应用程序中的密钥和加密。它提供了一个统一的密钥管理平台,用于存储和访问 API 密钥、密码、证书等。

本教程演示了如何将 API7 企业版与 HashiCorp Vault 集成,使你能够安全地存储和引用 Vault 中的消费者凭据和插件配置。

前提条件

  1. 安装 API7 企业版
  2. 在你的网关组中至少有一个网关实例
  3. 安装 Docker
  4. 安装 cURL 以向服务发送请求进行验证。
  5. 安装 ZIP 以解压缩 官方分发的压缩文件 中的 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 提供商

  1. 从侧边栏选择网关组的Secret 提供商,然后点击新增 Secret 提供商
  2. 在对话框中,执行以下操作:
    • Secret 提供商 ID,输入 my-vault
    • Secret 管理服务,选择 HashiCorp Vault
    • KV 版本,选择 KV version 1
    • 填写Vault 服务器 URL字段。例如,127.0.0.1
    • 填写Secret 前缀字段。例如,secret/api7
    • 身份验证方法,选择 Token
    • 填写令牌字段。
    • 点击新增

引用密钥以创建消费者凭据

消费者凭据中的以下敏感字段可以存储在外部Secret 管理服务(HashiCorp Vault、AWS Secret Manager 等)中,并在 API7 网关中引用:

  • Key Authentication 凭据中的 key
  • Basic Authentication 凭据中的 password
  • JWT 认证凭据中的 secretpublic key
  • HMAC 认证凭据中的 secret key

新增消费者

  1. 从侧边栏选择网关组的消费者
  2. 点击新增消费者
  3. 在对话框中,执行以下操作:
    • 名称,输入 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 凭据

  1. 从侧边栏选择网关组的消费者
  2. 选择你的目标消费者,例如,Alice
  3. 凭据选项卡下,点击新增Key Authentication 凭据
  4. 在对话框中,执行以下操作:
    • 名称,输入 primary-key
    • Key,选择引用 Secret 提供商,然后输入 $secret://vault/my-vault/consumer/alice/key
    • 点击新增
备注

所有密钥引用都以 $secret:// 开头。vault 是 Secret 提供商的Secret 管理服务my-vaultSecret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/consumer/alice/key

新增Basic Authentication 凭据

  1. 从侧边栏选择网关组的消费者
  2. 选择你的目标消费者,例如,Alice
  3. 凭据选项卡下,点击基本认证选项卡,然后点击新增Basic Authentication 凭据
  4. 在对话框中,执行以下操作:
    • 名称,输入 primary-basic
    • 用户名,输入 Alice
    • 密码,选择引用 Secret 提供商,然后输入 $secret://vault/my-vault/consumer/alice/password
    • 点击新增
备注

所有密钥引用都以 $secret:// 开头。vault 是 Secret 提供商的Secret 管理服务my-vaultSecret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/consumer/alice/password

新增 JWT 认证凭据

  1. 从侧边栏选择网关组的消费者
  2. 选择你的目标消费者,例如,Alice
  3. 凭据选项卡下,点击JWT选项卡,然后点击新增 JWT 凭据
  4. 在对话框中,执行以下操作:
    • 名称,输入 primary-jwt
    • Key,输入 alice-key
    • 算法,选择 HS256
    • 密钥,选择引用 Secret 提供商,然后输入 $secret://vault/my-vault/consumer/alice/secret
    • 点击新增
备注

所有密钥引用都以 $secret:// 开头。vault 是 Secret 提供商的Secret 管理服务my-vaultSecret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为 Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/consumer/alice/secret

新增 HMAC 认证凭据

  1. 从侧边栏选择网关组的消费者
  2. 选择你的目标消费者,例如,Alice
  3. 凭据选项卡下,点击HMAC 认证选项卡,然后点击新增 HMAC 认证凭据
  4. 在对话框中,执行以下操作:
    • 名称,输入 primary-hmac
    • Key ID,输入 alice-keyid
    • Secret Key,选择引用 Secret 提供商,然后输入 $secret://vault/my-vault/consumer/alice/secret-key
    • 点击新增
备注

所有密钥引用都以 $secret:// 开头。vault 是 Secret 提供商的Secret 管理服务my-vaultSecret 提供商 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 Countredis_usernameredis_password
Authz-Casdoorclient_idclient_secret
Wolf RBACappid
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 限流限速

将以下配置添加到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-vaultSecret 提供商 ID。连接到 HashiCorp Vault 时,$secret://vault/my-vault 将替换为Secret 提供商的实际Secret 前缀。最后,发送到 HashiCorp Vault 的路径将是 secret/api7/redis/usernamesecret/api7/redis/password

相关阅读