管理消费者凭证

消费者（Consumer） 是消费你 API 的应用程序。在服务（Service）上启用身份验证可以控制访问权限，要求消费者在访问 API 之前获取凭证。

服务上启用的身份验证插件充当 API 的锁，而消费者凭证则是解锁它们的钥匙。在 API7 企业版中，你需要一个唯一的用户名和至少一个凭证来设置消费者。

消费者可以使用多种不同类型的凭证，所有这些凭证在身份验证时均被同等对待。

备注

在实现基于消费者的凭证管理之前，请考虑开发者（Developers）是否是一个更好的解决方案。

本教程将指导你创建消费者并配置身份验证凭证。

前置条件

1. 安装 API7 企业版。
2. 在网关组上已运行一个 API。

配置 Key 认证凭证

Dashboard

1. 从侧边导航栏选择你网关组的 Consumers（消费者）。
2. 点击 + Add Consumer。
3. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 Alice。
• 点击 Add。

4. 在 Credentials 选项卡下，点击 + Add Key Authentication Credential。
5. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 primary-key。
• 在 Key 字段中，输入 alice-primary-key。
  • 如果你想从密钥提供商（Secret Provider）中引用，请参考在 HashiCorp Vault 中引用密钥、在 AWS Secrets Manager 中引用密钥或在 Kubernetes Secret 中引用密钥。
• 点击 Add。

6. 再次尝试添加另一个名为 backup-key 的 Key 认证凭证，其 Key 为 alice-backup-key。所有凭证均有效，并且可以互换使用以进行 API 身份验证。

以下是一个交互式演示，为你提供了使用 API7 企业版配置 Key 认证凭证的实践介绍。

ADC

更新 ADC 配置，添加一个具有 Key 认证凭证的消费者 Alice：

adc.yaml

consumers:
  - username: Alice
    credentials:
      - config:
          key: alice-backup-key
        name: backup-key
        type: key-auth
      - config:
          key: alice-primary-key
        name: primary-key
        type: key-auth

将配置同步到 API7 企业版：

adc sync -f adc.yaml

Ingress Controller

Gateway API

创建一个 Kubernetes 清单文件，为消费者 alice 配置一个主 Key（primary key）和一个备用 Key（backup key）以进行 Key 认证：

consumer-cred.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: primary-key
      config:
        key: alice-primary-key
    - type: key-auth
      name: backup-key
      config:
        key: alice-backup-key

或者，你在配置凭证时可以使用 Kubernetes Secret：

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: key-auth-primary
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk=
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: key-auth-backup
data:
  key: YWxpY2UtYmFja3VwLWtleQ==
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth-primary
      secretRef:
        name: key-auth-primary
    - type: key-auth
      name: key-auth-backup
      secretRef:
        name: key-auth-backup

❶ 对主 Key alice-primary-key 进行 Base64 编码。

❷ 对备用 Key alice-backup-key 进行 Base64 编码。

将配置应用到你的集群：

kubectl apply -f consumer-cred.yaml

APISIX CRD

备注

ApisixConsumer CRD 目前不支持将相同类型的多个凭证关联到单个消费者。

创建一个 Kubernetes 清单文件，为消费者 alice 配置一个用于 Key 认证的 Key：

consumer-cred.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: alice-primary-key

或者，你在配置凭证时可以使用 Kubernetes Secret：

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: key-auth-primary
data:
  key: YWxpY2UtcHJpbWFyeS1rZXk=
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      secretRef:
        name: key-auth-primary

❶ 对主 Key alice-primary-key 进行 Base64 编码。

将配置应用到你的集群：

kubectl apply -f consumer-cred.yaml

验证

有关说明，请参阅为 API 启用 Key 认证，并在服务级别启用 Key Auth 插件。

然后按照验证 Key 认证的说明进行操作。

配置 Basic 认证凭证

Dashboard

1. 从侧边导航栏选择你网关组的 Consumers（消费者）。
2. 点击 + Add Consumer。
3. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 Alice。
• 点击 Add。

4. 在 Credentials 选项卡下，点击 Basic Authentication 选项卡，然后点击 Add Basic Authentication Credential。
5. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 primary-basic。
• 在 Username 字段中，输入 alice。
• 在 Password 字段中，输入 alice-password。
  • 如果你想从密钥提供商（Secret Provider）中引用，请参考在 HashiCorp Vault 中引用密钥、在 AWS Secrets Manager 中引用密钥或在 Kubernetes Secret 中引用密钥。
• 点击 Add。

6. 再次尝试添加另一个名为 backup-basic 的 Basic 认证凭证，其 Username 为 alice-backup，Password 为 alice-backup-password。所有凭证均有效，并且可以互换使用以进行 API 身份验证。

ADC

更新 ADC 配置，添加一个具有 Basic 认证凭证的消费者 Alice：

adc.yaml

consumers:
  - username: Alice
    credentials:
      - config:
          password: alice-backup-password
          username: alice-backup
        name: backup-basic
        type: basic-auth
      - config:
          password: alice-password
          username: alice
        name: primary-basic
        type: basic-auth

将配置同步到 API7 企业版：

adc sync -f adc.yaml

Ingress Controller

Gateway API

创建一个 Kubernetes 清单文件，为消费者 alice 配置一个主凭证和一个备用凭证以进行 Basic 认证：

consumer-cred.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: basic-auth
      name: primary-basic
      config:
        username: alice
        password: alice-password
    - type: basic-auth
      name: backup-basic
      config:
        username: alice-backup
        password: alice-backup-password

或者，你在配置凭证时可以使用 Kubernetes Secret：

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: basic-auth-primary
data:
  username: YWxpY2U=
  password: YWxpY2UtcGFzc3dvcmQ=
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: basic-auth-backup
data:
  username: YWxpY2UtYmFja3Vw
  password: YWxpY2UtYmFja3VwLXBhc3N3b3Jk
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: alice
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: basic-auth
      name: basic-auth-primary
      secretRef:
        name: basic-auth-primary
    - type: basic-auth
      name: basic-auth-backup
      secretRef:
        name: basic-auth-backup

❶ 对用户名 alice 进行 Base64 编码。

❷ 对密码 alice-password 进行 Base64 编码。

❸ 对用户名 alice-backup 进行 Base64 编码。

❹ 对密码 alice-backup-password 进行 Base64 编码。

将配置应用到你的集群：

kubectl apply -f consumer-cred.yaml

APISIX CRD

备注

ApisixConsumer CRD 目前不支持将相同类型的多个凭证关联到单个消费者。

创建一个 Kubernetes 清单文件，为消费者 alice 配置一个主凭证以进行 Basic 认证：

consumer-cred.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    basicAuth:
      value:
        username: alice
        password: alice-password

或者，你在配置凭证时可以使用 Kubernetes Secret：

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: basic-auth-primary
data:
  username: YWxpY2U=
  password: YWxpY2UtcGFzc3dvcmQ=
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: alice
spec:
  ingressClassName: apisix
  authParameter:
    basicAuth:
      secretRef:
        name: basic-auth-primary

❶ 对用户名 alice 进行 Base64 编码。

❷ 对密码 alice-password 进行 Base64 编码。

将配置应用到你的集群：

kubectl apply -f consumer-cred.yaml

验证

有关说明，请参阅为 API 启用 Basic 认证，并在服务级别启用 Basic Auth 插件。

然后按照验证 Basic 认证的说明进行操作。

配置多种类型的认证凭证

虽然消费者可以拥有不同类型的多个凭证，但已发布服务中的每条路由应仅配置一种身份验证插件。这样可以让消费者使用他们首选的身份验证方法访问多条路由。

以下是一个交互式演示，为你提供了使用 API7 企业版配置各种认证凭证的实践介绍。

Dashboard

1. 从侧边导航栏选择你网关组的 Consumers（消费者）。
2. 点击 + Add Consumer。
3. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 John。
• 点击 Add。

4. 在 Credentials 选项卡下，点击 Add Key Authentication Credential。
5. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 key-auth。
• 在 Key 字段中，输入 john-key-auth。
• 点击 Add。

6. 在 Credentials 选项卡下，选择 Basic Authentication 并点击 Add Basic Authentication Credential。
7. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 basic-auth。
• 在 Username 字段中，输入 john。
• 在 Password 字段中，输入 john-password。
• 点击 Add。

8. 在 Credentials 选项卡下，选择 JWT 并点击 Add JWT Credential。
9. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 jwt-auth。
• 在 Key 字段中，输入 john-jwt-key。
• 在 Algorithm 字段中，选择 RS256。
• 在 Public Key 字段中，输入你的公钥。
• 点击 Add。

10. 在 Credentials 选项卡下，选择 HMAC Authentication 并点击 Add HMAC Authentication Credential。
11. 在对话框中，执行以下操作：

• 在 Name 字段中，输入 hmac-auth。
• 在 Key ID 字段中，输入 john-key。
• 在 Secret Key 字段中，输入 john-hmac-key。
• 点击 Add。

ADC

更新 ADC 配置，添加一个具有多种认证凭证的消费者 John：

adc.yaml

consumers:
  - username: John
    credentials:
      - config:
          key: john-key-auth
        name: key-auth
        type: key-auth
      - config:
          password: john-password
          username: john
        name: basic-auth
        type: basic-auth
      - config:
          algorithm: RS256
          key: john-jwt-key
          public_key: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
        name: jwt-auth
        type: jwt-auth
      - config:
          key_id: john-key
          secret_key: john-hmac-key
        name: hmac-auth
        type: hmac-auth

将配置同步到 API7 企业版：

adc sync -f adc.yaml

Ingress Controller

Gateway API

创建一个 Kubernetes 清单文件，为消费者 john 配置用于多种身份验证方法的凭证：

consumer-cred.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: john
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth
      config:
        key: john-key-auth
    - type: basic-auth
      name: basic-auth
      config:
        username: john
        password: john-password
    - type: jwt-auth
      name: jwt-auth
      config:
        key: john-jwt-key
        algorithm: RS256
        public_key: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
    - type: hmac-auth
      name: hmac-auth
      config:
        key_id: john-key
        secret_key: john-hmac-key

或者，你在配置凭证时可以使用 Kubernetes Secret：

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: key-auth-john
data:
  key: am9obi1rZXktYXV0aA==
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: basic-auth-john
data:
  username: am9obg==
  password: am9obi1wYXNzd29yZA==
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: jwt-auth-john
data:
  key: am9obi1qd3Qta2V5
  algorithm: UlMyNTY=
  public_key: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbi4uLlxuLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: hmac-auth-john
data:
  key_id: am9obi1rZXk=
  secret_key: am9obi1obWFjLWtleQ==
---
apiVersion: apisix.apache.org/v1alpha1
kind: Consumer
metadata:
  namespace: api7
  name: john
spec:
  gatewayRef:
    name: apisix
  credentials:
    - type: key-auth
      name: key-auth-john
      secretRef:
        name: key-auth-john
    - type: basic-auth
      name: basic-auth-john
      secretRef:
        name: basic-auth-john
    - type: jwt-auth
      name: jwt-auth-john
      secretRef:
        name: jwt-auth-john
    - type: hmac-auth
      name: hmac-auth-john
      secretRef:
        name: hmac-auth-john

APISIX CRD

创建一个 Kubernetes 清单文件，为消费者 john 配置用于多种身份验证方法的凭证：

consumer-cred.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: john
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      value:
        key: john-key-auth
    basicAuth:
      value:
        username: john
        password: john-password
    jwtAuth:
      value:
        key: john-jwt-key
        algorithm: RS256
        public_key: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----

或者，你在配置凭证时可以使用 Kubernetes Secret：

consumer-cred.yaml

apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: key-auth-john
data:
  key: am9obi1rZXktYXV0aA==
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: basic-auth-john
data:
  username: am9obg==
  password: am9obi1wYXNzd29yZA==
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: jwt-auth-john
data:
  key: am9obi1qd3Qta2V5
  algorithm: UlMyNTY=
  public_key: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS1cbi4uLlxuLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t
---
apiVersion: v1
kind: Secret
metadata:
  namespace: api7
  name: hmac-auth-john
data:
  key_id: am9obi1rZXk=
  secret_key: am9obi1obWFjLWtleQ==
---
apiVersion: apisix.apache.org/v2
kind: ApisixConsumer
metadata:
  namespace: api7
  name: john
spec:
  ingressClassName: apisix
  authParameter:
    keyAuth:
      secretRef:
        name: key-auth-john
    basicAuth:
      secretRef:
        name: basic-auth-john
    jwtAuth:
      secretRef:
        name: jwt-auth-john
    hmacAuth:
      secretRef:
        name: hmac-auth-john

在这些配置中，编码内容如下：

• key-auth：
  • key john-key-auth
• basic-auth：
  • username john
  • password john-password
• jwt-auth：
  • key john-jwt-key
  • algorithm RS256
  • public key -----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY----- —— 你应该将其替换为实际公钥并重新编码。
• hmac-auth
  • key ID john-key
  • secret key john-hmac-key

将配置应用到你的集群：

kubectl apply -f consumer-cred.yaml

附加资源

• 核心概念
  • 服务（Services）
  • 路由（Routes）
  • 插件（Plugins）
  • 消费者（Consumers）
  • 密钥（Secrets）
• API 安全
  • 设置 API 身份验证
  • 在 HashiCorp Vault 中引用密钥
  • 在 AWS Secrets Manager 中引用密钥
  • 在 Kubernetes Secret 中引用密钥
• API 消费
  • 应用基于列表的访问控制
• 插件中心
  • Key Authentication
  • Basic Authentication
  • JWT Auth Plugin
  • HMAC Auth Plugin