你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

2025-10-13

适用于：开发人员 | 高级

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

除了使用网关访问令牌（身份验证密钥）与其基于云的 API 管理实例连接外，还可以使用 Microsoft Entra 应用使自承载网关能够向关联的云实例进行身份验证。使用 Microsoft Entra 身份验证，可以为机密配置更长的过期时间，并使用标准步骤来管理和轮换 Active Directory 中的机密。

场景概述

自承载网关配置 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 管理配置 API 访问验证程序服务角色分配给 API 管理实例的托管标识。有关分配角色的详细步骤，请参阅使用门户分配 Azure 角色。

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

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

步骤 1：注册 Microsoft Entra 应用

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

生成客户端密码
记下在部署自托管网关时要使用的以下应用程序值：应用程序（客户端）ID、目录（租户）ID 和客户端秘钥

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

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

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

部署自托管网关

将自承载网关部署到 Kubernetes，并将 Microsoft Entra 应用注册设置添加到网关 ConfigMap 的 data 元素。在以下示例 YAML 配置文件中，网关名为 mygw ，该文件命名 mygw.yaml。

重要

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

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

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: mygw-env
  labels:
    app: mygw
data:
  config.service.endpoint: "<service-name>.configuration.azure-api.net"
  config.service.auth: azureAdApp 
  config.service.auth.azureAd.authority: "https://login.microsoftonline.com"  
  config.service.auth.azureAd.tenantId: "<Azure AD tenant ID>" 
  config.service.auth.azureAd.clientId: "<Azure AD client ID>" 
  config.service.auth.azureAd.clientSecret: "<Azure AD client secret>"
  gateway.name: <gateway-id>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mygw
  labels:
    app: mygw
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mygw
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 25%
  template:
    metadata:
      labels:
        app: mygw
    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: mygw
spec:
  type: LoadBalancer
  externalTrafficPolicy: Local
  ports:
  - name: http
    port: 80
    targetPort: 8080
  - name: https
    port: 443
    targetPort: 8081
  selector:
    app: mygw
---
apiVersion: v1
kind: Service
metadata:
  name: mygw-instance-discovery
  labels:
    app: mygw
  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: mygw

使用以下命令将网关部署到 Kubernetes：

kubectl apply -f mygw.yaml

确认网关正在运行

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

kubectl get deployments

它应返回

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

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

kubectl get services