針對自我裝載閘道使用 Microsoft Entra 驗證

適用於：開發人員 | 進階

Azure API 管理自我裝載閘道需要與其相關聯的雲端式 API 管理執行個體連線，才能報告狀態、檢查和套用設定更新，以及傳送計量和事件。

除了使用閘道存取權杖（驗證金鑰）來連線到其雲端式 API 管理執行個體之外，您還可以啟用自我裝載閘道，以使用 Microsoft Entra 應用程式向其相關聯的雲端執行個體進行驗證。透過 Microsoft Entra 驗證，您可以設定較長的祕密到期時間，並使用標準步驟來管理和輪替 Active Directory 中的祕密。

案例概觀

自我裝載閘道設定 API 可以檢查 Azure 角色型存取控制（RBAC），以判斷誰有權讀取閘道設定。建立具有這些許可權的 Microsoft Entra 應用程式之後，自我托管閘道可以使用應用程式對 API 管理實例進行身份驗證。

若要啟用 Microsoft Entra 驗證，請完成下列步驟：

建立兩個自訂角色以：
- 讓組態 API 存取客戶的 RBAC 資訊
- 授與讀取自我裝載閘道設定的權限
將 RBAC 存取權授與 APIM 執行個體的受控識別
建立 Microsoft Entra 應用程式，並授與其讀取閘道設定的存取權
使用新的組態選項部署閘道

先決條件

開發人員或進階服務層級中的 API 管理執行個體。如有需要，請完成下列快速入門：建立 Azure API 管理執行個體。
在執行個體上佈建閘道資源。
在執行個體上啟用系統指派的受控識別。
自行托管閘道容器映像檔 2.2 版或更新版本

限制說明

僅支援系統指派的受控識別。

建立自訂角色

建立下列兩個在後續步驟中指派的自訂角色。您可以使用下列 JSON 範本中列出的許可權，透過 Azure 入口網站、 Azure CLI、 Azure PowerShell 或其他 Azure 工具來建立自訂角色。

設定自訂角色時，請使用目錄的適當範圍值更新 AssignableScopes 屬性，例如部署 APIM 執行個體所在的訂用帳戶。

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 存取驗證器服務角色

將 APIM 設定 API 存取驗證程式服務角色指派給 APIM 執行個體的受控識別。如需指派角色的詳細步驟，請參閱使用入口網站指派 Azure 角色。

範圍：API 管理實例部署所在的資源群組或訂用帳戶
角色：API 管理設定 API 存取驗證器服務角色
將存取權指派給：APIM 執行個體的受控識別

指派 API 管理閘道設定讀取者角色

步驟 1：註冊 Microsoft Entra 應用程式

建立新的 Microsoft Entra 應用程式。如需步驟，請參閱建立可存取資源的 Microsoft Entra 應用程式和服務主體。自我裝載閘道會使用 Microsoft Entra 應用程式，向 APIM 執行個體進行驗證。

產生用戶端密碼
在部署自我裝載閘道時，請記下下一節中使用的應用程式值：應用程式（用戶端）識別碼、目錄（租用戶）識別碼和用戶端密碼

步驟 2：指派 API 管理閘道設定讀取者服務角色

將 API 管理閘道設定讀取者服務角色指派給應用程式。

範圍：API 管理執行個體（或部署應用程式的資源群組或訂用帳戶）
角色：API 管理閘道設定讀取者角色
指派存取權限：Microsoft Entra 應用程式

部署自行裝載閘道器

將自託管閘道部署至 Kubernetes，將 Microsoft Entra 應用程式註冊設定新增至閘道的 data 元素 ConfigMap。在下列範例 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

它應該會返回

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 已成功與 APIM 服務進行通訊，並且有一般「活動訊號」。

小提示

執行命令 kubectl logs deployment/<gateway-name> 以檢視隨機選取的 Pod 中的記錄（如果有多個 Pod）。
執行 kubectl logs -h，以取得完整的指令選項，例如如何檢視特定 Pod 或容器的日誌。

深入瞭解 API 管理自我裝載閘道。
深入瞭解在生產環境中對於 Kubernetes 執行自我裝載閘道的指引。
了解如何將 API 管理自我裝載閘道部署至已啟用 Azure Arc 的 Kubernetes 叢集 (部分內容可能是機器或 AI 翻譯)。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-10