对自承载网关使用 Microsoft Entra 身份验证

适用于：开发人员 | 高级

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

本文介绍如何使用 Microsoft Entra ID 应用（使用客户端机密或证书）使自承载网关能够向关联的云实例进行身份验证。通过使用 Microsoft Entra 身份验证，可以为机密配置更长的过期时间，并使用标准步骤来管理和轮换机密。有关其他身份验证选项，请参阅自承载网关身份验证选项。

场景概述

自承载网关配置 API 可以检查 Azure 基于角色的访问控制（RBAC），以确定谁有权读取网关配置。使用这些权限创建Microsoft Entra 应用后，自承载网关可以使用应用向 API 管理实例进行身份验证。

若要启用 Microsoft Entra 身份验证，请完成以下步骤：

创建两个自定义角色以：
- 让配置 API 访问客户的 RBAC 信息
- 授予读取自托管网关配置的权限
授予 RBAC 对 API 管理实例的托管标识的访问权限
创建Microsoft Entra 应用并授予它读取网关配置的权限
使用新的配置选项部署网关

先决条件

开发人员或高级服务层级中的 API 管理实例。如果需要，请完成以下快速入门：创建 Azure API 管理实例。
在实例上预配网关资源。
在实例上启用系统分配的托管标识。
自托管网关容器映像版本 2.2 或更高版本

局限性

仅支持系统分配的托管标识。

创建自定义角色

创建后续步骤中分配的以下两个自定义角色。可以使用以下 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、目录（租户）ID 和客户端密码。

注释

可以选择使用证书进行身份验证，而不是使用客户端密码。有关将证书上传到 Microsoft Entra 应用的步骤，请参阅使用证书进行 Azure AD 应用身份验证。

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

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

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

部署自托管网关

将自托管网关部署到如 Kubernetes 这样的容器化环境，并添加 Microsoft Entra 应用注册设置。

Helm
YAML

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

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

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

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='AzureAdApp' \
             --set gateway.auth.azureAd.tenant.id='<entra-id-tenant-id>' \
             --set gateway.auth.azureAd.app.id='<entra-id-app-id>'
             --set config.service.auth.azureAd.clientSecret='<entra-id-secret>'

有关先决条件和详细信息，请参阅使用 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 配置文件中，Microsoft Entra 应用注册配置被添加到网关的dataConfigMap 元素。网关名为 mygw。

重要

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

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

注释

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

<entra-id-app-id>：你的 Microsoft Entra 应用（客户端）ID
<entra-id-tenant-id>：Microsoft Entra租户 ID（目录 ID）
<entra-id-client-secret>：为Microsoft Entra应用生成的客户端密码
<gateway-id>：自建网关名称
<service-name>.configuration.azure-api.cn：API 管理配置终结点

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: mygw-env
  labels:
    app: apim-gateway
data:
  config.service.endpoint: "<service-name>.configuration.azure-api.cn"
  config.service.auth: azureAdApp 
  config.service.auth.azureAd.authority: "https://login.partner.microsoftonline.cn"  
  config.service.auth.azureAd.tenantId: "<entra-id-tenant-id>" 
  config.service.auth.azureAd.clientId: "<entra-id-app-id>" 
  config.service.auth.azureAd.clientSecret: "<entra-id-client-secret>"
  gateway.name: <gateway-id>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mygw
  labels:
    app: apim-gateway
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apim-gateway
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 25%
  template:
    metadata:
      labels:
        app: apim-gateway
    spec:
      terminationGracePeriodSeconds: 60
      containers:
      - name: mygw
        image: mcr.microsoft.com/azure-api-management/gateway:v2
        ports:
        - name: http
          containerPort: 8080
        - name: https
          containerPort: 8081
          # Container port used for rate limiting to discover instances
        - name: rate-limit-dc
          protocol: UDP
          containerPort: 4290
          # Container port used for instances to send heartbeats to each other
        - name: dc-heartbeat
          protocol: UDP
          containerPort: 4291
        readinessProbe:
          httpGet:
            path: /status-0123456789abcdef
            port: http
            scheme: HTTP
          initialDelaySeconds: 0
          periodSeconds: 5
          failureThreshold: 3
          successThreshold: 1
        envFrom:
        - configMapRef:
            name: mygw-env
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-live-traffic
  labels:
    app: apim-gateway
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  ports:
  - name: http
    port: 80
    targetPort: 8080
  - name: https
    port: 443
    targetPort: 8081
  selector:
    app: apim-gateway
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-instance-discovery
  labels:
    app: apim-gateway
  annotations:
    azure.apim.kubernetes.io/notes: "Headless service being used for instance discovery of self-hosted gateway"
spec:
  clusterIP: None
  type: ClusterIP
  ports:
  - name: rate-limit-discovery
    port: 4290
    targetPort: rate-limit-dc
    protocol: UDP
  - name: discovery-heartbeat
    port: 4291
    targetPort: dc-heartbeat
    protocol: UDP
  selector:
    app: apim-gateway

部署到 Kubernetes

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

kubectl apply -f apim-gateway-entra-id.yaml

确认网关正在运行

运行以下命令，检查部署是否成功。创建所有对象以及 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 或容器的日志。

详细了解 API 管理自托管网关。
详细了解有关在生产环境中在 Kubernetes 上运行自承载网关的指导。

Last updated on 2026-03-12

Compartilhar via

对自承载网关使用 Microsoft Entra 身份验证

场景概述

先决条件

局限性

创建自定义角色

添加角色分配

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

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

步骤 1：注册 Microsoft Entra 应用

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

部署自托管网关

确认网关正在运行

相关内容

Recursos adicionais