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

[アーティクル]
10/26/2023

適用対象: 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 ツールを使って、カスタムロールを作成できます。

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

API Management Configuration 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 Management Configuration API アクセス検証サービスロールを割り当てる

API Management Configuration API アクセス検証サービスロールを、API Management インスタンスのマネージド ID に割り当てます。ロールを割り当てる手順について詳しくは、ポータルを使用した Azure ロールの割り当てに関する記事をご覧ください。

スコープ: API Management インスタンスがデプロイされるリソースグループまたはサブスクリプション
ロール: API Management Configuration API アクセス検証サービスロール
アクセス権の割り当て先: API Management インスタンスのマネージド ID

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

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

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

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

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

API Management ゲートウェイ構成閲覧者サービスロールを割り当てるをアプリに割り当てます。

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

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

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

重要

既存の 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 セルフホステッドゲートウェイをデプロイする方法について学習します。

次の方法で共有

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

シナリオの概要

[前提条件]

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

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

ロールの割り当てを追加する

API Management Configuration API アクセス検証サービスロールを割り当てる

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

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

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

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

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

シナリオの概要

[前提条件]

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

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

ロールの割り当てを追加する

API Management Configuration API アクセス検証サービス ロールを割り当てる

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

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

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

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

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

次のステップ

フィードバック

その他のリソース

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

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

API Management Configuration API アクセス検証サービスロールを割り当てる

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

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