使用 Microsoft Entra 工作负荷标识身份验证来进行自托管网关认证

适用于：开发人员 | 高级

Azure API 管理自承载网关需要与其关联的基于云的 API 管理实例建立连接，以便报告状态、检查和应用配置更新以及发送指标和事件。

本文介绍如何使用 Microsoft Entra 工作负荷标识使自承载网关能够对其关联的云实例进行身份验证。通过使用工作负荷标识身份验证，无需管理机密或证书，因为身份验证是通过 Kubernetes 群集与 Microsoft Entra ID 之间的联合标识凭据进行处理的。有关其他身份验证选项，请参阅自承载网关身份验证选项。

场景概述

自承载网关配置 API 可以检查 Azure 基于角色的访问控制（RBAC），以确定谁有权读取网关配置。通过使用工作负荷标识，可以创建一个通过联合标识凭据与 Kubernetes 服务帐户关联的Microsoft Entra 应用。然后，自承载网关可以使用此工作负荷标识向 API 管理实例进行身份验证，而无需机密。

工作负荷标识使用 OpenID Connect （OIDC）使 Kubernetes 应用程序能够安全地访问 Azure 资源。

若要启用工作负荷标识身份验证，请完成以下步骤：

创建两个自定义角色以：
- 让配置 API 访问客户的 RBAC 信息
- 授予读取自托管网关配置的权限
授予 RBAC 对 API 管理实例的托管标识的访问权限
创建Microsoft Entra 应用并配置联合标识凭据
授予 Microsoft Entra 应用读取网关配置的权限
部署网关并进行工作负荷标识配置

先决条件

开发人员或高级服务层级中的 API 管理实例。如果需要，请完成以下快速入门：创建 Azure API 管理实例。
启用了"工作负载标识"和"OIDC 发行者"的 Azure Kubernetes 服务 (AKS) 集群。
实例上的网关资源。
在实例上启用系统分配的托管标识。
自行托管网关容器镜像版本 2.11.0 或更高版本。

备注

本文重点介绍如何部署到 Azure Kubernetes 服务（AKS）。
该模式适用于具有所需 OIDC 支持的其他 Kubernetes 分发。有关详细信息，请参阅 Azure 工作负荷标识存储库。

创建自定义角色

创建后续步骤中分配的以下两个自定义角色。可以使用以下 JSON 模板中列出的权限通过 Azure 门户、 Azure CLI、 Azure PowerShell 或其他 Azure 工具创建自定义角色。

配置自定义角色时，请更新 AssignableScopes 属性，使用您的目录中适当的作用域值，例如部署 API 管理实例的订阅。

API 管理配置 API 访问验证程序服务角色

{
  "Description": "Can access RBAC permissions on the API Management resource to authorize requests in Configuration API.",
  "IsCustom": true,
  "Name": "API Management Configuration API Access Validator Service Role",
  "Permissions": [
    {
      "Actions": [
        "Microsoft.Authorization/*/read"
      ],
      "NotActions": [],
      "DataActions": [],
      "NotDataActions": []
    }
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionID}"
  ]
}

API 管理网关配置读取者角色

{
  "Description": "Can read self-hosted gateway configuration from Configuration API",
  "IsCustom": true,
  "Name": "API Management Gateway Configuration Reader Role",
  "Permissions": [
    {
      "Actions": [],
      "NotActions": [],
      "DataActions": [
        "Microsoft.ApiManagement/service/gateways/getConfiguration/action"
      ],
      "NotDataActions": []
    }
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionID}"
  ]
}

增加角色分配

分配 API 管理配置 API 访问验证器服务角色

将 API Management 配置 API 访问验证器服务角色分配给 API Management 实例的托管标识。有关分配角色的详细步骤，请参阅通过门户分配 Azure 角色。

范围：在其中部署 API 管理实例的资源组或订阅
角色：API 管理配置 API 访问验证程序服务角色
分配对：API 管理实例的托管标识的访问权限

分配 API 管理网关配置查看者角色

步骤 1：注册 Microsoft Entra 应用并配置工作负荷标识

创建新的Microsoft Entra 应用。有关步骤，请参阅创建可访问资源的 Microsoft Entra 应用程序和服务主体。 Microsoft Entra 应用由自托管网关用于对 API 管理实例进行身份验证。

重要

工作负荷标识不需要创建客户端密码。身份验证通过联合标识凭据进行处理。

请记下应用程序（客户端）ID，以便在下一部分部署自托管网关时使用。

接下来，配置联合标识凭据，以在 Microsoft Entra 应用与 Kubernetes 服务帐户之间建立信任：

在 Azure 门户中，导航到 Microsoft Entra 应用注册。
选择 “证书和机密>联合凭据>+ 添加凭据”。
选择 Kubernetes 访问 Azure 资源 场景。
配置联合凭据：
- 集群颁发者 URL：从你的 AKS 集群中获取的 OIDC 颁发者 URL（请使用 az aks show --resource-group <resource-group> --name <cluster-name> --query "oidcIssuerProfile.issuerUrl" 获取）
- 命名空间：部署网关的 Kubernetes 命名空间（例如 apim-gateway-wi）
- 服务帐户：Kubernetes 服务帐户的名称（例如 apim-gateway-workload-identity）
- 名称：凭据的描述性名称（例如 apim-gateway-federated-credential）
选择 “添加” 以创建联合凭据。

有关详细信息，请参阅在应用上配置联合标识凭据。

步骤 2：分配 API 管理网关配置读取服务角色

将 API 管理网关配置读取者服务角色分配给应用。

范围：API 管理实例（或部署应用的资源组或订阅）
角色：API 管理网关配置读取者角色
将访问权限分配给：Microsoft Entra 应用

部署自托管网关

使用工作负荷标识将自承载网关部署到 Kubernetes。

Helm
YAML

可以使用 Helm 图表部署具有 Microsoft Entra 身份验证的自托管网关。

将 helm install 命令中的以下值替换为实际值：

<gateway-name>：Azure API 管理实例名称
<gateway-url>：网关的 URL，格式 https://<gateway-name>.configuration.azure-api.cn
<entra-id-app-id>：已注册Microsoft Entra应用的应用程序（客户端）ID

helm install --name azure-api-management-gateway azure-apim-gateway/azure-api-management-gateway \
             --set gateway.name=='<gateway-name>' \
             --set gateway.configuration.uri='<gateway-url>' \
             --set gateway.auth.type='WorkloadIdentity' \
             --set gateway.auth.azureAd.app.id='<entra-id-app-id>'

有关先决条件和详细信息，请参阅使用 Helm 部署 API 管理自承载网关。

确认网关正在运行

运行以下命令来检查网关 Pod 是否正在运行。 Pod 名称将有所不同。

kubectl get pods
NAME                                           READY     STATUS    RESTARTS   AGE
azure-api-management-gateway-59f5fb94c-s9stz   1/1       Running   0          1m

运行以下命令来检查网关服务是否正在运行。你的服务名称和 IP 地址与此不同。

kubectl get services
NAME                           TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)               AGE
azure-api-management-gateway   ClusterIP   10.0.229.55     <none>        8080/TCP,8081/TCP     1m

返回到Azure门户，确认部署的网关节点报告正常状态。

小窍门

使用 kubectl logs <gateway-pod-name> 命令查看自承载网关日志的快照。

以下 YAML 配置显示了所需的组件和设置。

重要

如果遵循现有的 Kubernetes 部署指南：

省略使用 kubectl create secret generic 命令存储默认身份验证密钥的步骤。
将以下基本配置文件替换为 Azure 门户为你生成的默认 YAML 文件。以下文件添加Microsoft Entra 工作区标识来代替配置以使用身份验证密钥。

注释

请确保将占位符值替换为实际配置：

<namespace-name>：Kubernetes 命名空间
<client-id>：你的 Microsoft Entra 应用（客户端）ID
<gateway-name>：API 管理网关名称
<service-name>.configuration.azure-api.cn：API 管理配置终结点

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: apim-gateway-workload-identity
  namespace: <namespace-name>
  labels:
    azure.workload.identity/use: "true"
  annotations:
    azure.workload.identity/client-id: "<client-id>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: apim-gateway
  namespace: <namespace-name>
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apim-gateway
  template:
    metadata:
      labels:
        app: apim-gateway
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: apim-gateway-workload-identity
      containers:
      - name: apim-gateway
        image: mcr.microsoft.com/azure-api-management/gateway:v2
        ports:
        - name: http
          containerPort: 8080
          protocol: TCP
        - name: https
          containerPort: 8081
          protocol: TCP
        readinessProbe:
          failureThreshold: 3
          httpGet:
            path: /internal-status-0123456789abcdef
            port: http
            scheme: HTTP
          periodSeconds: 5
          successThreshold: 1
          timeoutSeconds: 1
        resources:
          limits:
            cpu: "2"
            memory: 2Gi
          requests:
            cpu: "2"
            memory: 2Gi
        envFrom:
        - configMapRef:
            name: apim-gateway-env
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: apim-gateway-env
  namespace: <namespace-name>
data:
  gateway.name: <gateway-name>
  config.service.auth: workloadIdentity
  config.service.endpoint: https://<service-name>.configuration.azure-api.cn
  telemetry.logs.std.level: info
---
apiVersion: v1
kind: Service
metadata:
  name: apim-gateway-loadbalancer
  namespace: <namespace-name>
spec:
  type: LoadBalancer
  selector:
    app: apim-gateway
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 8080
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8081

部署到 Kubernetes

将 YAML 配置保存到文件（例如 apim-gateway-workload-identity.yaml），并将其部署到 AKS 群集：

kubectl apply -f apim-gateway-workload-identity.yaml

验证部署：

kubectl get pods -n <namespace-name>
kubectl logs -n <namespace-name> <pod-name>

确认网关正在运行

运行以下命令，检查部署是否成功。创建所有对象以及 Pod 初始化可能需要一点时间。

kubectl get deployments

它应返回

NAME             READY   UP-TO-DATE   AVAILABLE   AGE
<gateway-name>   1/1     1            1           18s

运行以下命令，检查是否已成功创建服务。服务 IP 和端口将有所不同。

kubectl get services

它应返回

NAME                                TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
<gateway-name>-live-traffic         ClusterIP      None            <none>        4290/UDP,4291/UDP   9m1s
<gateway-name>-instance-discovery   LoadBalancer   10.99.236.168   <pending>     80:31620/TCP,443:30456/TCP   9m1s

返回到 Azure 门户，然后选择网关的 “概述 ”选项卡。
确认状态显示为绿色勾号，并且节点计数与 YAML 文件中指定的副本数量一致。此状态意味着部署的自托管网关 Pod 已成功与 API 管理服务进行通信，并定期发送“心跳信号”。

小窍门

kubectl logs deployment/<gateway-name>运行命令，查看随机选择的 Pod 中的日志（如果有多个）。
运行 kubectl logs -h 以获取完整的命令选项集，例如如何查看特定 Pod 或容器的日志。

Last updated on 2026-03-12

Compartilhar via

使用 Microsoft Entra 工作负荷标识身份验证来进行自托管网关认证

场景概述

先决条件

备注

创建自定义角色

增加角色分配

分配 API 管理配置 API 访问验证器服务角色

分配 API 管理网关配置查看者角色

步骤 1：注册 Microsoft Entra 应用并配置工作负荷标识

步骤 2：分配 API 管理网关配置读取服务角色

部署自托管网关

确认网关正在运行

相关内容

Recursos adicionais