Kubelogin を使用して Azure Kubernetes Service でユーザーを認証する

Azure の kubelogin プラグインは、Microsoft Entra 認証を実装するクライアントゴー資格情報 プラグイン です。 kubelogin プラグインには、kubectl コマンドライン ツールでは使用できない機能が用意されています。

Microsoft Entra ID と統合され、Kubernetes バージョン 1.24 以降を実行している Azure Kubernetes Service (AKS) クラスターでは、kubelogin 形式が自動的に使用されます。

この記事では、AKS でサポートされているすべての Microsoft Entra 認証方法に kubelogin を使用する方法の概要と例を示します 。

制限事項

• Microsoft Entra JSON Web Token (JWT) 要求には、最大 200 個のグループを含めることができます。 グループが 200 を超える場合は、アプリケーション ロールの使用を検討してください。
• Microsoft Entra ID で作成されたグループは、表示名ではなく ObjectID 値によってのみ含まれます。 この sAMAccountName コマンドは、オンプレミスの Windows Server Active Directory から同期されるグループに対してのみ使用できます。
• AKS では、サービス プリンシパルの認証方法は、以前のバージョンの Azure Active Directory ではなく、マネージド Microsoft Entra ID でのみ機能します。
• Microsoft Entra テナントで Microsoft Entra 条件付きアクセス ポリシーが設定されている場合、デバイス コードの認証方法は機能しません。 そのシナリオでは、Web ブラウザーの対話型認証を使用します。

認証のしくみ

kubelogin とのほとんどの対話では、サブコマンドを使用します convert-kubeconfig 。 サブコマンドは、環境変数で --kubeconfig 指定された kubeconfig ファイルを KUBECONFIG 使用して、指定された認証方法に基づいて最終的な kubeconfig ファイルを exec 形式に変換します。

kubelogin が実装する認証方法は、Microsoft Entra OAuth 2.0 トークン付与フローです。 次のパラメーター フラグは、kubelogin サブコマンドで使用するのが一般的です。 一般に、これらのフラグは、AKS から kubeconfig ファイルを取得するときに使用する準備ができています。

• --tenant-id: Microsoft Entra テナント ID。
• --client-id: パブリック クライアント アプリケーションのアプリケーション ID。 このクライアント アプリは、デバイス コード、Web ブラウザー対話型、OAuth 2.0 リソース所有者パスワード資格情報 (ROPC) (ワークフロー ID) サインイン メソッドでのみ使用されます。
• --server-id: Web アプリまたはリソース サーバーのアプリケーション ID。 トークンはこのリソースに発行されます。

Note

各認証方法では、トークンはファイル システムにキャッシュされません。

認証方法

次のセクションでは、サポートされている認証方法とその使用方法について説明します。

• デバイス コード
• Azure CLI
• Web ブラウザーの対話型
• サービス プリンシパル
• マネージド ID
• ワークロード ID

デバイス コード

デバイス コードは、サブコマンドの既定の convert-kubeconfig 認証方法です。 -l devicecode パラメーターは省略可能です。 この認証方法は、ユーザーがブラウザー セッションからサインインするようにデバイス コードに求めます。

kubelogin プラグインと exec プラグインが導入される前は、kubectl の Azure 認証方法でデバイス コード フローのみがサポートされていました。 以前のバージョンのライブラリを使用して、プレフィックスを持つ要求を持つトークンをaudiencespn:生成しました。 これは、代理 (OBO) フローを使用する AKS マネージド Microsoft Entra ID と互換性がありません。 サブコマンドを convert-kubeconfig 実行すると、kubelogin は対象ユーザー要求からプレフィックスを削除 spn: します。

要件に以前のバージョンの機能の使用が含まれている場合は、引数を追加します --legacy 。 以前のバージョンの Azure Active Directory クラスターで kubeconfig ファイルを使用している場合、kubelogin によってフラグが自動的に --legacy 追加されます。

このサインイン方法では、アクセス トークンと更新トークンが ${HOME}/.kube/cache/kubelogin ディレクトリにキャッシュされます。 このパスをオーバーライドするには、パラメーターを --token-cache-dir 含めます。

AKS Microsoft Entra 統合クラスターで Kubernetes 1.24 以前を使用している場合は、次のコマンドを実行して kubeconfig ファイル形式を手動で変換する必要があります。

export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

キャッシュされたトークンをクリーンするには、次のコマンドを実行します。

kubelogin remove-tokens

Note

条件付きアクセス ポリシーが Microsoft Entra テナントで構成されている場合、デバイス コードのサインイン方法は機能しません。 このシナリオでは、Web ブラウザーの対話型メソッドを使用します。

Azure CLI

Azure CLI 認証方法では、Azure CLI が確立したサインイン コンテキストを使用してアクセス トークンを取得します。 トークンは、次と同じ Microsoft Entra テナント az loginで発行されます。 kubelogin では、トークンは Azure CLI によって既に管理されているため、トークン キャッシュ ファイルに書き込まれません。

Note

この認証方法は、AKS マネージド Microsoft Entra ID でのみ機能します。

次の例は、Azure CLI メソッドを使用して認証する方法を示しています。

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

Azure CLI 構成ディレクトリが ${HOME} ディレクトリの外部にある場合は、サブコマンドで--azure-config-dirパラメーターをconvert-kubeconfig使用します。 このコマンドは、環境変数が構成された kubeconfig ファイルを生成します。 kubectl コマンドを実行するときに環境変数を AZURE_CONFIG_DIR このディレクトリに設定することで、同じ構成を取得できます。

Web ブラウザーの対話型

Web ブラウザーの対話型認証方法によって、ユーザーをサインインさせる Web ブラウザーが自動的に開きます。 ユーザーが認証されると、ブラウザーは検証済みの資格情報を使用してローカル Web サーバーにリダイレクトします。 この認証方法は、条件付きアクセス ポリシーに準拠しています。

このメソッドを使用して認証を行うと、アクセス トークンは ${HOME}/.kube/cache/kubelogin ディレクトリにキャッシュされます。 このパスは、パラメーターを --token-cache-dir 使用してオーバーライドできます。

Bearer token

次の例は、Web ブラウザーの対話型フローでベアラー トークンを使用する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

所有証明トークン

次の例は、Web ブラウザーの対話型フローで所有証明 (PoP) トークンを使用する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

サービス プリンシパル

この認証方法では、サービス プリンシパルを使用してユーザーをサインインします。 資格情報を指定するには、環境変数を設定するか、コマンド ライン引数で資格情報を使用します。 使用できるサポートされている資格情報は、パスワードまたは Personal Information Exchange (PFX) クライアント証明書です。

この方法を使用する前に、次の制限事項を考慮してください。

• このメソッドは、マネージド Microsoft Entra ID でのみ機能します。
• サービス プリンシパルは、最大 200 個の Microsoft Entra グループのメンバーにすることができます。

環境変数

次の例は、環境変数を使用してクライアント シークレットを設定する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<Service Principal Name (SPN) client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

その後、次のコマンドを実行します。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_SECRET=<SPN secret>

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

コマンドライン引数

次の例は、コマンド ライン引数でクライアント シークレットを設定する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --client-id <SPN client ID> --client-secret <SPN client secret>

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

警告

コマンド ライン引数メソッドは、kubeconfig ファイルにシークレットを格納します。

クライアント証明書

次の例は、クライアント証明書を使用してクライアント シークレットを設定する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

その後、次のコマンドを実行します。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

PoP トークンと環境変数

次の例は、環境変数から取得するクライアント シークレットを使用する PoP トークンを設定する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

マネージド ID

Microsoft Entra 認証を サポートするリソースに接続するアプリケーションには、マネージド ID 認証方法を使用します。 たとえば、Azure 仮想マシン、仮想マシン スケール セット、Azure Cloud Shell などの Azure リソースへのアクセスが挙げられます。

既定のマネージド ID

次の例は、既定のマネージド ID を使用する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

特定の ID

次の例は、特定の ID でマネージド ID を使用する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

ワークロード ID

ワークロード ID 認証方法では、Microsoft Entra とフェデレーションされた ID 資格情報を使用して、AKS クラスターへのアクセスを認証します。 この方法では、Microsoft Entra 統合認証が使用されます。 これは、次の環境変数を設定することによって機能します。

• AZURE_CLIENT_ID: ワークロード ID とフェデレーションされている Microsoft Entra アプリケーション ID。
• AZURE_TENANT_ID: Microsoft Entra テナント ID。
• AZURE_FEDERATED_TOKEN_FILE: Kubernetes 投影サービス アカウント (JWT) トークンなど、ワークロード ID の署名付きアサーションを含むファイル。
• AZURE_AUTHORITY_HOST: Microsoft Entra 機関のベース URL。 たとえば、https://login.microsoftonline.com/ のようにします。

外部システムにサービス プリンシパルの資格情報を格納することなく、ワークロード ID を使用して、GitHub や ArgoCD などの CI/CD システムから Kubernetes クラスターにアクセスできます。 GitHub から OpenID Connect (OIDC) フェデレーションを構成するには、OIDC フェデレーションの例を参照してください。

次の例は、ワークロード ID を使用する方法を示しています。

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

次の kubectl コマンドを実行して、ノード情報を取得します。

kubectl get nodes

AKS で kubelogin を使用する方法

AKS では、ファースト パーティの Microsoft Entra アプリケーションのペアが使用されます。 これらのアプリケーション ID はすべての環境で同じです。

サーバー側で使用される AKS Microsoft Entra サーバー アプリケーション ID は .6dae42f8-4368-4678-94ff-3960e28e3630 AKS クラスターにアクセスするアクセス トークンは、このアプリケーションに対して発行する必要があります。 ほとんどの kubelogin 認証方法では、次の方法でkubelogin get-token使用--server-idする必要があります。

kubelogin がユーザーの代わりにパブリック クライアント認証を実行するために使用する AKS Microsoft Entra クライアント アプリケーション ID は、80faf920-1908-4b52-b5ef-a8e7bedfc67a クライアント アプリケーション ID は、デバイス コードと Web ブラウザーの対話型認証方法で使用されます。

関連するコンテンツ

• AKS マネージド Microsoft Entra ID の統合方法に関する記事で 、AKS と Microsoft Entra ID を統合 する方法について説明します。
• AKS でマネージド ID の使用を開始するには、AKS でのマネージド ID の使用に関する記事を参照してください。
• AKS でワークロード ID の使用を開始するには、「AKS での ワークロード ID の使用」を参照してください。