Azure Kubernetes Service (AKS) で Microsoft Entra ワークロード ID を使う

Azure Kubernetes Services (AKS) クラスターにデプロイされたワークロードでは、Azure Key Vault や Microsoft Graph などの Microsoft Entra で保護されたリソースにアクセスするには、Microsoft Entra アプリケーションの資格情報またはマネージド ID が必要です。 Microsoft Entra ワークロード ID は、Kubernetes にネイティブな機能と統合され、外部 ID プロバイダーとフェデレーションされます。

Microsoft Entra ワークロード ID では、サービス アカウント トークン ボリューム プロジェクション (つまりサービス アカウント) を使って、ポッドで Kubernetes ID を使用できるようにします。 Kubernetes トークンが発行され、OIDC フェデレーションにより、Kubernetes アプリケーションは注釈付きのサービス アカウントに基づいて Microsoft Entra ID を使って Azure リソースに安全にアクセスできるようになります。

Microsoft Entra ワークロード ID は、アプリケーションの登録を一緒に使用している場合は、Azure ID クライアント ライブラリと Microsoft Authentication Library (MSAL) コレクションで特に適切に機能します。 ワークロードでは、これらのライブラリのいずれかを使用して、Azure クラウド リソースのシームレスな認証とアクセスを行うことができます。

この記事は、Microsoft Entra Workload ID を理解し、プロジェクト戦略や Microsoft Entra ポッドマネージド ID からの移行の可能性を計画するために使用できるオプションを確認するのに役立ちます。

Note

一部の手順を自動的に構成するのに役立てるために、Service Connector を使用できます。 関連項目: Service Connector とは

依存関係

• AKS は、バージョン 1.22 以降で Microsoft Entra ワークロード ID をサポートしています。
• Azure CLI バージョン 2.47.0 以降。 az --version を実行してバージョンを見つけ、az upgrade を実行してバージョンをアップグレードします。 インストールまたはアップグレードする必要がある場合は、Azure CLI のインストールに関するページを参照してください。

Azure ID クライアント ライブラリ

Azure ID クライアント ライブラリで、次のいずれかの方法を選択します。

• WorkloadIdentityCredential を使用しようとしている DefaultAzureCredential を使用します。
• WorkloadIdentityCredential を含む ChainedTokenCredential インスタンスを作成します。
• WorkloadIdentityCredential を直接使用します。

次の表は、各言語のクライアント ライブラリに必要な最小 のパッケージ バージョンを示しています。

エコシステム	ライブラリ	最小バージョン
.NET	Azure.Identity	1.9.0
C++	azure-identity-cpp	1.6.0
Go	azidentity	1.3.0
Java	azure-identity	1.9.0
Node.js	@azure/identity	3.2.0
Python	azure-identity	1.13.0

次のコード サンプルでは、DefaultAzureCredential が使用されています。 この資格情報の種類では、Azure Workload Identity によって挿入された環境変数を使用して、Webhook を変更して Azure Key Vault で認証します。

.NET

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

string keyVaultUrl = Environment.GetEnvironmentVariable("KEYVAULT_URL");
string secretName = Environment.GetEnvironmentVariable("SECRET_NAME");

var client = new SecretClient(
    new Uri(keyVaultUrl),
    new DefaultAzureCredential());

KeyVaultSecret secret = await client.GetSecretAsync(secretName);

C++

#include <cstdlib>
#include <azure/identity.hpp>
#include <azure/keyvault/secrets/secret_client.hpp>

using namespace Azure::Identity;
using namespace Azure::Security::KeyVault::Secrets;

int main()
{
  const char* keyVaultUrl = std::getenv("KEYVAULT_URL");
  const char* secretName = std::getenv("SECRET_NAME");
  auto credential = std::make_shared<DefaultAzureCredential>();

  SecretClient client(keyVaultUrl, credential);
  Secret secret = client.GetSecret(secretName).Value;

  return 0;
}

Go

package main

import (
	"context"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets"
    "k8s.io/klog/v2"
)

func main() {
	keyVaultUrl := os.Getenv("KEYVAULT_URL")
	secretName := os.Getenv("SECRET_NAME")

	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		klog.Fatal(err)
	}

	client, err := azsecrets.NewClient(keyVaultUrl, credential, nil)
	if err != nil {
		klog.Fatal(err)
	}

	secret, err := client.GetSecret(context.Background(), secretName, "", nil)
	if err != nil {
		klog.ErrorS(err, "failed to get secret", "keyvault", keyVaultUrl, "secretName", secretName)
		os.Exit(1)
	}
}

Java

import java.util.Map;

import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.DefaultAzureCredential;

public class App {
    public static void main(String[] args) {
        Map<String, String> env = System.getenv();
        String keyVaultUrl = env.get("KEYVAULT_URL");
        String secretName = env.get("SECRET_NAME");

        SecretClient client = new SecretClientBuilder()
                .vaultUrl(keyVaultUrl)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();
        KeyVaultSecret secret = client.getSecret(secretName);
    }
}

Node.js

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const main = async () => {
    const keyVaultUrl = process.env["KEYVAULT_URL"];
    const secretName = process.env["SECRET_NAME"];

    const credential = new DefaultAzureCredential();
    const client = new SecretClient(keyVaultUrl, credential);

    const secret = await client.getSecret(secretName);
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Python

import os

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

def main():
    keyvault_url = os.getenv('KEYVAULT_URL', '')
    secret_name = os.getenv('SECRET_NAME', '')

    client = SecretClient(vault_url=keyvault_url, credential=DefaultAzureCredential())
    secret = client.get_secret(secret_name)

if __name__ == '__main__':
    main()

Microsoft Authentication Library (MSAL)

次のクライアント ライブラリは、必要な最小バージョンです。

エコシステム	ライブラリ	Image	例	Windows が含まれます
.NET	Microsoft Authentication Library-for-dotnet	ghcr.io/azure/azure-workload-identity/msal-net:latest	リンク	はい
Go	Microsoft Authentication Library-for-go	ghcr.io/azure/azure-workload-identity/msal-go:latest	リンク	はい
Java	Microsoft Authentication Library-for-java	ghcr.io/azure/azure-workload-identity/msal-java:latest	リンク	いいえ
JavaScript	Microsoft Authentication Library-for-js	ghcr.io/azure/azure-workload-identity/msal-node:latest	リンク	いいえ
Python	Microsoft Authentication Library-for-python	ghcr.io/azure/azure-workload-identity/msal-python:latest	リンク	いいえ

制限事項

• フェデレーション ID 資格情報は、マネージド ID ごとに最大 20 個持つことができます。
• フェデレーション ID 資格情報が最初に追加された後に反映されるまでに数秒かかります。
• オープン ソース プロジェクト Virtual Kubelet に基づき、仮想ノード アドオンはサポートされていません。
• これらのリージョンのユーザー割り当て済みマネージド ID では、フェデレーション ID 資格情報の作成がサポートされていません。

しくみ

このセキュリティ モデルでは、AKS クラスターはトークン発行者として機能します。 Microsoft Entra ID により OpenID Connect を使って公開署名キーが検出され、サービス アカウント トークンの信頼性が検証されてから、それと Microsoft Entra トークンが交換されます。 ワークロードでは、Azure ID クライアント ライブラリまたは Microsoft Authentication Library (MSAL) を使って、Microsoft Entra トークンのボリュームに投影されたサービス アカウント トークンを交換できます。

次の表では、Microsoft Entra ワークロード ID に必要な OIDC 発行者のエンドポイントについて説明します。

エンドポイント	説明
{IssuerURL}/.well-known/openid-configuration	OIDC 探索ドキュメントとも呼ばれます。 これには、発行者の構成に関するメタデータが含まれています。
{IssuerURL}/openid/v1/jwks	これには、サービス アカウント トークンの信頼性を検証するために Microsoft Entra ID で使う公開署名キーが含まれています。

次の図は、OpenID Connect を使用した認証シーケンスをまとめたものです。

Webhook 証明書の自動ローテーション

他の Webhook アドオンと同様に、証明書はクラスター証明書の自動ローテーション処理によってローテーションされます。

サービス アカウントのラベルと注釈

Microsoft Entra ワークロード ID では、サービス アカウントに関連する次のマッピングがサポートされています。

• 1 つのサービス アカウントから 1 つの Microsoft Entra オブジェクトを参照する一対一。
• 複数のサービス アカウントから同一の Microsoft Entra オブジェクトを参照する多対一。
• クライアント ID 注釈を変更することで、1 つのサービス アカウントから複数の Microsoft Entra オブジェクトを参照する一対多。 詳しくは、「Kubernetes サービス アカウントを使用して複数の ID をフェデレートする方法」をご覧ください。

Note

サービス アカウントの注釈が更新された場合は、変更を有効にするためにポッドを再起動する必要があります。

Microsoft Entra ポッドマネージド ID を使っている場合、サービス アカウントはコア Kubernetes API の一部であることを除き、サービス アカウントをカスタム リソース定義 (CRD) ではなく Azure セキュリティ プリンシパルと考えてください。 次のセクションでは、Microsoft Entra アクセス トークンのサービス アカウント トークンを交換するときに動作を構成するために使用できる、使用可能なラベルと注釈の一覧について説明します。

サービス アカウントの注釈

すべての注釈は省略可能です。 注釈が指定されていない場合は、既定値が使用されます。

注釈	説明	Default
azure.workload.identity/client-id	Microsoft Entra アプリケーションを表す クライアント ID を表します。
azure.workload.identity/tenant-id	Azure AD アプリケーションが登録される Microsoft Entra アプリケーションが登録されています。	AZURE_TENANT_ID 環境変数 (azure-wi-webhook-config ConfigMap から抽出されたもの)。
azure.workload.identity/service-account-token-expiration	投影されたサービス アカウント トークンの expirationSeconds フィールドを 表します。 これは、サービス アカウント トークンの更新中のエラーによって発生する ダウンタイムを防ぐために構成する省略可能なフィールドです。 Kubernetes サービス アカウント トークンの有効期限は、Microsoft Entra トークンと関連付けられていません。 Microsoft Entra トークンは、発行されてから 24 時間で有効期限が切れます。	3600 サポートされる範囲は 3600 から 86400 です。

ポッド ラベル

Note

ワークロード ID を使用するアプリケーションの場合、ワークロード ID を使用する必要があるポッドに対して一貫した信頼性の高い動作を提供するため、AKS がワークロード ID を Fail Close シナリオに移動するよう、ポッド スペックに azure.workload.identity/use: "true" ラベルを追加する必要があります。 それ以外の場合、ポッドは再起動後に失敗します。

Label	説明	推奨値	必須
azure.workload.identity/use	このラベルは、ポッド テンプレート スペックで必要です。このラベルを持つポッドのみが、Azure 固有の環境変数と予測されるサービス アカウント トークン ボリュームを挿入するために、azure-workload-identity mutating admission webhook によって変更されます。	true	はい

ポッドの注釈

すべての注釈は省略可能です。 注釈が指定されていない場合は、既定値が使用されます。

注釈	説明	Default
azure.workload.identity/service-account-token-expiration	投影されたサービス アカウント トークンの expirationSeconds フィールドを表しています。 これは、サービス アカウント トークンの更新中のエラーが原因のダウンタイムを防ぐために構成する省略可能なフィールドです。 Kubernetes サービス アカウント トークンの有効期限は、Microsoft Entra トークンと関連付けられていません。 Microsoft Entra トークンは、発行されてから 24 時間で有効期限が切れます。 1	3600 サポートされる範囲は 3600 から 86400 です。
azure.workload.identity/skip-containers	投影されたサービス アカウント トークン ボリュームの追加をスキップする、セミコロンで区切られたコンテナーの一覧を表します。 たとえば、container1;container2 のようにします。	既定では、サービス アカウントに azure.workload.identity/use: true というラベルが付いている場合、投影されたサービス アカウント トークン ボリュームはすべてのコンテナーに追加されます。
azure.workload.identity/inject-proxy-sidecar	プロキシ init コンテナーとプロキシ サイドカーをポッドに挿入します。 プロキシ サイドカーは、IMDS へのトークン要求をインターセプトし、フェデレーション ID 資格情報を持つユーザーに代わって Microsoft Entra トークンを取得するために使われます。	true
azure.workload.identity/proxy-sidecar-port	プロキシ サイドカーのポートを表します。	8000

¹ サービス アカウントにも注釈が付けられる場合に優先されます。

Microsoft Entra ワークロード ID に移行する方法

ポッドマネージド ID が既に実行されているクラスターでは、2 つの方法のいずれかでワークロード ID を使用するように構成できます。 最初のオプションでは、ポッドマネージド ID に対して実装しているものと同じ構成を使用できます。 名前空間内のサービス アカウントに ID で注釈を付けると、Microsoft Entra ワークロード ID を有効にし、注釈をポッドに挿入できるようになります。

2 つ目のオプションは、Azure ID クライアント ライブラリの最新バージョンを使用するようにアプリケーションを書き換える方法です。

移行プロセスを合理化および容易にするために、アプリケーションで行われる IMDS トランザクションを OpenID Connect (OIDC) に変換する移行サイドカーを開発しました。 移行サイドカーは長期的なソリューションを意図したものではなく、ワークロード ID で迅速に稼働させる方法です。 アプリケーション内で移行サイドカーを実行すると、アプリケーション IMDS トランザクションが OIDC にプロキシされます。 もう 1 つの方法は、OIDC 認証をサポートする Azure ID クライアント ライブラリのサポートされているバージョンにアップグレードすることです。

次の表は、ワークロード ID の移行またはデプロイに関する推奨事項をまとめたものです。

シナリオ	説明
新規または既存のクラスターのデプロイでは、Azure ID クライアント ライブラリのサポートされているバージョンが実行されます	移行手順は必要ありません。 サンプル デプロイ リソース: 新しいクラスターにワークロード ID をデプロイして構成する
新規または既存のクラスターのデプロイでは、Azure ID クライアント ライブラリのサポートされないバージョンが実行されます	サポートされているバージョンの Azure ID SDK を使用するようにコンテナー イメージを更新するか、移行サイドカーを使用します。

次のステップ

• 移行オプションとしてワークロード ID を使用して認証するようにポッドを設定する方法については、ワークロード ID を使用したアプリケーション認証の最新化に関する記事を参照してください。
• 「ワークロード ID を使用して AKS クラスターをデプロイして構成する」を参照してください。これは、Azure Kubernetes Service クラスターをデプロイし、ワークロード ID を使用するようにサンプル アプリケーションを構成するのに役立ちます。