Azure CLI を使って Microsoft Entra ID を Azure Kubernetes Service (AKS) と統合する (レガシ)

[アーティクル]
08/02/2024

警告

このドキュメントで説明されている機能 Microsoft Entra 統合 (レガシ) は 2023 年 6 月 1 日に非推奨になりました。現時点で、Microsoft Entra 統合 (レガシ) を使って新しいクラスターを作成することはできません。

AKS には、サーバーまたはクライアントのアプリケーションの管理を必要としない、改善された新しい AKS マネージド Microsoft Entra ID エクスペリエンスが備わっています。移行する場合は、こちらの手順に従ってください。

Azure Kubernetes Service (AKS) は、ユーザー認証に Microsoft Entra ID を使うように構成することができます。この構成では、Microsoft Entra 認証トークンを使って AKS クラスターにログインできます。また、クラスターオペレーターが、ユーザーの ID またはディレクトリグループメンバーシップに基づいて、Kubernetes のロールベースのアクセス制御 (Kubernetes RBAC) を構成することもできます。

この記事では、必要な Microsoft Entra コンポーネントを作成してから、Microsoft Entra ID 対応クラスターをデプロイして、AKS クラスターで基本的な Kubernetes ロールを作成する方法について説明します。

制限事項

Microsoft Entra ID は、Kubernetes RBAC が有効なクラスターでのみ有効にすることができます。
Microsoft Entra のレガシ統合は、クラスター作成時にのみ有効にすることができます。

開始する前に

Azure CLI バージョン 2.0.61 以降がインストールされて構成されている必要があります。バージョンを確認するには、az --version を実行します。インストールまたはアップグレードする必要がある場合は、Azure CLI のインストールに関するページを参照してください。

https://shell.azure.com にアクセスし、ブラウザーで Cloud Shell を開きます。

一貫性を保ち、この記事のコマンドを実行するのに役立てるため、目的の AKS クラスター名に変数を作成します。次の例では、myakscluster という名前を使用しています。

aksname="myakscluster"

Microsoft Entra 認証の概要

Microsoft Entra 認証は、OpenID Connect によって AKS クラスターに提供されます。 OpenID Connect は、OAuth 2.0 プロトコル上に構築された ID レイヤーです。 OpenID Connect の詳細については、OpenID Connect のドキュメントを参照してください。

Kubernetes クラスターの内部からは、Webhook トークン認証を使用して認証トークンが確認されます。 webhook トークン認証は、AKS クラスターの一部として構成および管理されます。 Webhook トークン認証の詳細については、Webhook 認証のドキュメントを参照してください。

Note

Microsoft Entra ID を AKS 認証用に構成する場合、2 つの Microsoft Entra アプリケーションが構成されます。この操作は、Azure テナント管理者が行う必要があります。

Microsoft Entra サーバーコンポーネントを作成する

AKS と統合するには、ID 要求のエンドポイントとして機能する Microsoft Entra アプリケーションを作成して使います。必要な最初の Microsoft Entra アプリケーションは、ユーザーの Microsoft Entra グループメンバーシップを取得します。

az ad app create コマンドを使用してサーバーアプリケーションコンポーネントを作成してから、az ad app update コマンドを使用してそのグループメンバーシップの要求を更新します。次の例では、「開始する前に」セクションで定義した aksname 変数を使用して変数を作成します。

# Create the Azure AD application
serverApplicationId=$(az ad app create \
    --display-name "${aksname}Server" \
    --identifier-uris "https://${aksname}Server" \
    --query appId -o tsv)

# Update the application group membership claims
az ad app update --id $serverApplicationId --set groupMembershipClaims=All

ここで、az ad sp create コマンドを使用して、サーバーアプリのサービスプリンシパルを作成します。このサービスプリンシパルは、Azure プラットフォーム内で自身を認証するために使用されます。次に、az ad sp credential reset コマンドを使用してサービスプリンシパルのシークレットを取得し、次のいずれかのステップで使用するために serverApplicationSecret という名前の変数に割り当てます。

# Create a service principal for the Azure AD application
az ad sp create --id $serverApplicationId

# Get the service principal secret
serverApplicationSecret=$(az ad sp credential reset \
    --name $serverApplicationId \
    --credential-description "AKSPassword" \
    --query password -o tsv)

Microsoft Entra サービスプリンシパルには、次のアクションを実行するためのアクセス許可が必要です。

ディレクトリデータの読み取り
サインインとユーザープロファイルの読み取り

az ad app permission add コマンドを使用して、これらのアクセス許可を割り当てます。

az ad app permission add \
    --id $serverApplicationId \
    --api 00000003-0000-0000-c000-000000000000 \
    --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope 06da0dbc-49e2-44d2-8312-53f166ab848a=Scope 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role

最後に、az ad app permission grant コマンドを使用して、前の手順で割り当てたアクセス許可をサーバーアプリケーションに付与します。現在のアカウントがテナント管理者ではない場合、このステップは失敗します。また、az ad app permission admin-consent を使って、管理者の同意を別途必要とする可能性のある情報を Microsoft Entra アプリケーションが要求するためのアクセス許可を追加する必要もあります。

az ad app permission grant --id $serverApplicationId --api 00000003-0000-0000-c000-000000000000
az ad app permission admin-consent --id  $serverApplicationId

Microsoft Entra クライアントコンポーネントを作成する

2 つ目の Microsoft Entra アプリケーションは、Kubernetes CLI (kubectl) を使ってユーザーが AKS クラスターにログインするときに使われます。このクライアントアプリケーションでは、認証要求をユーザーから取得して、その資格情報とアクセス許可を確認します。 az ad app create コマンドを使って、クライアントコンポーネント用に Microsoft Entra アプリを作成します。

clientApplicationId=$(az ad app create \
    --display-name "${aksname}Client" \
    --native-app \
    --reply-urls "https://${aksname}Client" \
    --query appId -o tsv)

az ad sp create コマンドを使用して、クライアントアプリケーション用にサービスプリンシパルを作成します。

az ad sp create --id $clientApplicationId

az ad app show コマンドを使用して、サーバーアプリの oAuth2 ID を取得して、2 つのアプリコンポーネント間の認証フローを許可します。この oAuth2 ID は、次のステップで使用されます。

oAuthPermissionId=$(az ad app show --id $serverApplicationId --query "oauth2Permissions[0].id" -o tsv)

az ad app permission add コマンドを使用して、クライアントアプリケーションおよびサーバーアプリケーションコンポーネントが oAuth2 通信フローを使用するためのアクセス許可を追加します。次に、az ad app permission grant コマンドを使用して、サーバーアプリケーションと通信するためのアクセス許可をクライアントアプリケーションに付与します。

az ad app permission add --id $clientApplicationId --api $serverApplicationId --api-permissions ${oAuthPermissionId}=Scope
az ad app permission grant --id $clientApplicationId --api $serverApplicationId

クラスターをデプロイする

2 つの Microsoft Entra アプリケーションが作成されたので、今度は AKS クラスターそのものを作成します。最初に、az group create コマンドを使用して、リソースグループを作成します。次の例では、米国東部リージョンにリソースグループを作成します。

クラスター用にリソースグループを作成します。

az group create --name myResourceGroup --location EastUS

az account show コマンドを使用して Azure サブスクリプションのテナント ID を取得します。次に、az aks create コマンドを使用して AKS クラスターを作成します。 AKS クラスターを作成するコマンドは、サーバーとクライアントアプリケーションの ID、サーバーアプリケーションサービスプリンシパルのシークレット、およびテナント ID を提供します。

tenantId=$(az account show --query tenantId -o tsv)

az aks create \
    --resource-group myResourceGroup \
    --name $aksname \
    --node-count 1 \
    --generate-ssh-keys \
    --aad-server-app-id $serverApplicationId \
    --aad-server-app-secret $serverApplicationSecret \
    --aad-client-app-id $clientApplicationId \
    --aad-tenant-id $tenantId

最後に、az aks get-credentials コマンドを使用して、クラスター管理者資格情報を取得します。次の手順のいずれかで、通常の user クラスターの資格情報を取得して、Microsoft Entra 認証のフローの動作を確認します。

az aks get-credentials --resource-group myResourceGroup --name $aksname --admin

Kubernetes RBAC バインドの作成

Microsoft Entra アカウントを AKS クラスターで使用できるようにするには、その前にまず、ロールのバインドまたはクラスターロールのバインドを作成する必要があります。付与するアクセス許可を "ロール" によって定義し、それらを "バインド" によって目的のユーザーに適用します。これらの割り当ては、特定の名前空間に適用することも、クラスター全体に適用することもできます。詳細については、Kubernetes RBAC 認可の使用に関するページを参照してください。

az ad signed-in-user show コマンドを使用して、現在ログインしているユーザーのユーザープリンシパル名 (UPN) を取得します。このユーザーアカウントは、次のステップで Microsoft Entra 統合に対して有効化されます。

az ad signed-in-user show --query userPrincipalName -o tsv

重要

Kubernetes RBAC のバインドの付与先となるユーザーが同じ Microsoft Entra テナントに存在する場合は、userPrincipalName に基づいてアクセス許可を割り当てます。ユーザーが別の Microsoft Entra テナント内にいる場合、代わりに objectId プロパティに対してクエリを実行して使います。

basic-azure-ad-binding.yaml という名前の YAML マニフェストを作成し、次の内容を貼り付けます。最後の行で、userPrincipalName_or_objectId を前のコマンドで出力された UPN またはオブジェクト ID に置き換えます。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: contoso-cluster-admins
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: userPrincipalName_or_objectId

kubectl apply コマンドを使用して ClusterRoleBinding を作成し、YAML マニフェストのファイル名を指定します。

kubectl apply -f basic-azure-ad-binding.yaml

Microsoft Entra ID を使ってクラスターにアクセスする

ここで、AKS クラスターの Microsoft Entra 認証の統合をテストしてみましょう。通常のユーザーの資格情報を使用するように kubectl 構成のコンテキストを設定します。このコンテキストは、Microsoft Entra ID 経由ですべての認証要求を返します。

az aks get-credentials --resource-group myResourceGroup --name $aksname --overwrite-existing

今度は、kubectl get pods コマンドを使用して、すべての名前空間にわたってポッドを表示します。

kubectl get pods --all-namespaces

Web ブラウザーを使って、Microsoft Entra の資格情報を使って認証するためのサインインプロンプトが表示されます。正常に認証を行うと、次の出力例に示されているように、kubectl コマンドによって AKS クラスター内のポッドが表示されます。

kubectl get pods --all-namespaces

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BYMK7UXVD to authenticate.

NAMESPACE     NAME                                    READY   STATUS    RESTARTS   AGE
kube-system   coredns-754f947b4-2v75r                 1/1     Running   0          23h
kube-system   coredns-754f947b4-tghwh                 1/1     Running   0          23h
kube-system   coredns-autoscaler-6fcdb7d64-4wkvp      1/1     Running   0          23h
kube-system   heapster-5fb7488d97-t5wzk               2/2     Running   0          23h
kube-system   kube-proxy-2nd5m                        1/1     Running   0          23h
kube-system   kube-svc-redirect-swp9r                 2/2     Running   0          23h
kube-system   kubernetes-dashboard-847bb4ddc6-trt7m   1/1     Running   0          23h
kube-system   metrics-server-7b97f9cd9-btxzz          1/1     Running   0          23h
kube-system   tunnelfront-6ff887cffb-xkfmq            1/1     Running   0          23h

kubectl 用に受信した認証トークンがキャッシュされます。トークンの有効期限が切れたとき、または Kubernetes の構成ファイルが再作成されたときにのみ、サインインを再び求められます。

Web ブラウザーを使用して正常にサインインした後に、次の出力例のような承認エラーメッセージが表示される場合は、次の考えられる問題を確認してくださいます。

error: You must be logged in to the server (Unauthorized)

ユーザーアカウントが同じ Microsoft Entra テナント内にあるかどうかに応じて、適切なオブジェクト ID または UPN を定義した。
ユーザーが 200 を超えるグループのメンバーにはなっていない。
サーバーのアプリケーション登録に定義されているシークレットが、--aad-server-app-secret を使用して構成された値と一致する
コンピューターにインストールする kubectl のバージョンは必ず、一度に 1 つにしてください。バージョンが競合すると、承認中に問題が発生する可能性があります。最新バージョンをインストールするには、az aks install-cli を使用します。

Microsoft Entra 統合から AKS マネージド Microsoft Entra ID への移行についてよく寄せられる質問

1. 移籍の計画はどうなっていますか?

Microsoft Entra Integration (レガシ) は 2023 年 6 月 1 日に廃止されます。この日以降、Microsoft Entra ID (レガシ) を使って新しいクラスターを作成できなくなります。すべての Microsoft Entra Integration (レガシ) AKS クラスターは、2023 年 8 月 1 日から、AKS マネージド Microsoft Entra ID に自動的に移行されます。影響を受けたサブスクリプション管理者に、移行をリマインドする通知メールを隔週で送信します。

2. 何もアクションを実行しないとどうなりますか?

Microsoft Entra 統合 (レガシ) AKS クラスターは、2023 年 6 月 1 日以降も引き続き機能します。 2023 年 8 月 1 日から、クラスターは AKS マネージド Microsoft Entra ID に自動的に移行されます。移行中に API サーバーのダウンタイムが発生する可能性があります。

移行後に kubeconfig コンテンツは変更されます。 az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> を使用して、新しい資格情報を kubeconfig ファイルにマージする必要があります。

8 月 1 日までに、AKS クラスターを AKS マネージド Microsoft Entra ID に手動で更新することを推奨します。これにより、営業時間外の都合の良い時間にダウンタイムを管理できます。

3. 手動による移行後も通知メールが届くのはなぜですか?

メールが送信されるまでに数日かかります。メール送信プロセスを開始する前にクラスターが移行されなかった場合でも、通知が届く場合があります。

4.クラスターが AKS マネージド Microsoft Entra ID に移行済みかどうかを確認するにはどうすればよいですか?

az aks show コマンドを使って、AKS クラスターが AKS マネージド Microsoft Entra ID に移行されたことを確認します。

az aks show -g <RGName> -n <ClusterName>  --query "aadProfile"

クラスターが AKS マネージド Microsoft Entra ID を使っている場合、出力に managed が true であることが示されます。次に例を示します。

    {
      "adminGroupObjectIDs": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ],
      "adminUsers": null,
      "clientAppId": null,
      "enableAzureRbac": null,
      "managed": true,
      "serverAppId": null,
      "serverAppSecret": null,
      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }

次のステップ

この記事で示されているコマンドを含む完全なスクリプトについては、[AKS サンプルリポジトリの Microsoft Entra 統合スクリプト][complete-script]のページを参照してください。

Microsoft Entra ユーザーとグループを使ってクラスターリソースへのアクセスを制御するには、AKS で Kubernetes のロールベースのアクセス制御と Microsoft Entra の ID を使ってクラスターリソースへのアクセスを制限する方法に関するページを参照してください。

Kubernetes クラスターをセキュリティで保護する方法の詳細については、AKS でのアクセスと ID オプションに関するページを参照してください。

ID とリソース管理に関するベストプラクティスについては、AKS での認証と承認のベストプラクティスに関するページを参照してください。

次の方法で共有

Azure CLI を使って Microsoft Entra ID を Azure Kubernetes Service (AKS) と統合する (レガシ)

制限事項

開始する前に

Microsoft Entra 認証の概要

Microsoft Entra サーバーコンポーネントを作成する

Microsoft Entra クライアントコンポーネントを作成する

クラスターをデプロイする

Kubernetes RBAC バインドの作成

Microsoft Entra ID を使ってクラスターにアクセスする

Microsoft Entra 統合から AKS マネージド Microsoft Entra ID への移行についてよく寄せられる質問

次のステップ

その他のリソース

次の方法で共有

Azure CLI を使って Microsoft Entra ID を Azure Kubernetes Service (AKS) と統合する (レガシ)

制限事項

開始する前に

Microsoft Entra 認証の概要

Microsoft Entra サーバー コンポーネントを作成する

Microsoft Entra クライアント コンポーネントを作成する

クラスターをデプロイする

Kubernetes RBAC バインドの作成

Microsoft Entra ID を使ってクラスターにアクセスする

Microsoft Entra 統合から AKS マネージド Microsoft Entra ID への移行についてよく寄せられる質問

次のステップ

その他のリソース

Microsoft Entra サーバーコンポーネントを作成する

Microsoft Entra クライアントコンポーネントを作成する