セルフホステッドゲートウェイに Microsoft Entra 認証を使用する

適用対象: Developer | Premium

Azure API Management のセルフホステッドゲートウェイでは、状態の報告、構成の更新の確認と適用、メトリックとイベントの送信のために、関連付けられているクラウドベースの API Management インスタンスとの接続が必要です。

ゲートウェイアクセストークン (認証キー) を使用してクラウドベースの API Management インスタンスに接続するだけでなく、 Microsoft Entra アプリを使用して、関連付けられているクラウドインスタンスに対する認証をセルフホステッドゲートウェイで有効にできます。 Microsoft Entra 認証を使用すると、シークレットの有効期限を長く構成し、標準の手順を使用して Active Directory でシークレットを管理およびローテーションできます。

シナリオの概要

セルフホステッドゲートウェイ構成 API では、Azure ロールベースのアクセス制御 (RBAC) を確認して、ゲートウェイ構成を読み取るアクセス許可を持つユーザーを特定できます。これらのアクセス許可を持つ Microsoft Entra アプリを作成した後、セルフホステッドゲートウェイはアプリを使用して API Management インスタンスに対して認証を行うことができます。

Microsoft Entra 認証を有効にするには、次の手順を実行します。

次の 2 つのカスタムロールを作成します。
- 構成 API が顧客の RBAC 情報にアクセスできるようにする
- セルフホステッドゲートウェイ構成を読み取るアクセス許可を付与する
API Management インスタンスのマネージド ID への RBAC アクセス権を付与する
Microsoft Entra アプリを作成し、ゲートウェイ構成を読み取るアクセス権を付与する
新しい構成オプションを使用してゲートウェイをデプロイする

[前提条件]

Developer または Premium サービスレベルの API Management インスタンス。必要に応じて、次のクイックスタートを完了します。 Azure API Management インスタンスを作成します。
インスタンスにゲートウェイリソースをプロビジョニングします。
インスタンスでシステム割り当てマネージド ID を有効にします。
セルフホステッドゲートウェイコンテナーイメージバージョン 2.2 以降

制限事項に関する注意事項

システム割り当てマネージド ID のみがサポートされています。

カスタムロールを作成する

後の手順で割り当てられる次の 2 つのカスタムロールを作成します。次の JSON テンプレートに記載されているアクセス許可を使用して、 Azure portal、 Azure CLI、 Azure PowerShell、またはその他の Azure ツールを使用してカスタムロールを作成できます。

カスタムロールを構成するときは、 AssignableScopes プロパティを、API Management インスタンスがデプロイされているサブスクリプションなど、ディレクトリの適切なスコープ値で更新します。

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 Management ゲートウェイ構成閲覧者ロール

{
  "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 Configuration API Access Validator Service ロールを API Management インスタンスのマネージド ID に割り当てます。ロールを割り当てる詳細な手順については、ポータルを使用した Azure ロールの割り当てに関するページを参照してください。

スコープ: API Management インスタンスがデプロイされているリソースグループまたはサブスクリプション
ロール: API管理構成APIアクセスバリデーターサービスの役割
アクセスの割り当て: API Management インスタンスのマネージド ID

API Management ゲートウェイ構成閲覧者ロールの割り当て

手順 1: Microsoft Entra アプリを登録する

新しい Microsoft Entra アプリを作成します。手順については、「リソースにアクセスできる Microsoft Entra アプリケーションとサービスプリンシパルを作成する」を参照してください。 Microsoft Entra アプリは、API Management インスタンスに対する認証にセルフホステッドゲートウェイによって使用されます。

クライアントシークレットを生成する
セルフホステッドゲートウェイをデプロイするときに、次のセクションで使用するアプリケーション値 (アプリケーション (クライアント) ID、ディレクトリ (テナント) ID、クライアントシークレット) を書き留めておきます。

手順 2: API Management ゲートウェイ構成リーダーサービスロールを割り当てる

API Management Gateway 構成閲覧者サービスロールをアプリに割り当てます。

スコープ: API Management インスタンス (またはアプリがデプロイされているリソースグループまたはサブスクリプション)
ロール: API Management ゲートウェイ構成閲覧者ロール
アクセスの割り当て先: Microsoft Entra アプリ

セルフホステッドゲートウェイをデプロイする

セルフホステッドゲートウェイを Kubernetes にデプロイし、Microsoft Entra アプリ登録設定をゲートウェイ dataのConfigMap要素に追加します。次の YAML 構成ファイルの例では、ゲートウェイの名前は mygw で、ファイルの名前は mygw.yaml です。

Important

既存の Kubernetes デプロイガイダンスに従っている場合:

kubectl create secret generic コマンドを使用して既定の認証キーを格納する手順は必ず省略してください。
Azure portal で生成される既定の 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

ゲートウェイが実行されていることを確認する

次のコマンドを実行して、デプロイが成功したかどうかを確認します。すべてのオブジェクトが作成され、ポッドが初期化されるまでに少し時間がかかる場合があります。
```
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 portal に戻り、[ 概要] を選択します。
状態に緑色のチェックマークが表示され、その後に YAML ファイルで指定されたレプリカの数と一致するノード数が表示されることを確認します。この状態は、デプロイされたセルフホステッドゲートウェイポッドが API Management サービスと正常に通信し、通常の "ハートビート" があることを意味します。

ヒント

kubectl logs deployment/<gateway-name> コマンドを実行して、複数のポッドがある場合は、ランダムに選択されたポッドのログを表示します。
特定のポッドまたはコンテナーのログを表示する方法など、コマンドオプションの完全なセットに対して kubectl logs -h を実行します。

API Management のセルフホステッドゲートウェイの詳細を確認します。
運用環境の Kubernetes でセルフホステッドゲートウェイを実行するためのガイダンスについて説明します。
Azure Arc 対応 Kubernetes クラスターに API Management セルフホステッドゲートウェイをデプロイする方法について学習します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-10