Используйте идентификацию рабочих нагрузок в Microsoft Entra с Azure Kubernetes Service (AKS)

Рабочие нагрузки, развернутые в кластере AKS, требуют учетных данных приложения Microsoft Entra или управляемых удостоверений для доступа к защищенным ресурсам Microsoft Entra, таким как Azure Key Vault и Microsoft Graph. Идентификация рабочей нагрузки Microsoft Entra интегрируется с возможностями, собственными для Kubernetes, для федерации с внешними поставщиками удостоверений, что позволяет назначать идентификаторы рабочим нагрузкам для проверки подлинности и доступа к другим службам и ресурсам.

Примечание.

Идентификатор рабочей нагрузки охватывает сценарий pod-to-Azure в AKS — как приложения, работающие в модулях, проходят проверку подлинности в службах, защищенных Microsoft Entra. Другие сценарии идентификации (проверка подлинности и авторизация на уровне управления, а также управляемые удостоверения в кластере в Azure) см. в разделе "Доступ и удостоверения" для AKS.

Идентификатор рабочей нагрузки Microsoft Entra использует проекцию тома токена учетной записи службы (или учетную запись службы), чтобы pod могли использовать идентификацию Kubernetes. Токен Kubernetes выдан и федерация OpenID Connect (OIDC) позволяет приложениям Kubernetes безопасно получать доступ к ресурсам Azure с помощью идентификатора Microsoft Entra, основанного на учетных записях службы с аннотированием.

Можно использовать идентификатор рабочей нагрузки Microsoft Entra с клиентскими библиотеками удостоверений Azure или коллекцией Библиотеки проверки подлинности Microsoft (MSAL) и регистрацией приложения, чтобы легко пройти проверку подлинности и получить доступ к облачным ресурсам Azure.

Примечание.

Вы можете использовать Соединитель служб, чтобы помочь вам автоматически настроить некоторые шаги. Дополнительные сведения см. в разделе "Что такое соединитель службы"?

Предпосылки

AKS поддерживает Workload ID Microsoft Entra на версии 1.22 и выше.
Azure CLI версии 2.47.0 или более поздней. Запустите az --version, чтобы определить версию и запустите az upgrade для обновления версии. Если вам необходимо выполнить установку или обновление, см. статью Установка Azure CLI 2.0.

Ограничения

Для каждого управляемого удостоверения можно иметь не более 20 федеративных учетных данных.
Для распространения учетных данных федеративного удостоверения после их первоначального добавления требуется несколько секунд.
Надстройка "виртуальных узлов", основанная на проекте с открытым исходным кодом "Virtual Kubelet", не поддерживается.
Создание учетных данных федеративного удостоверения не поддерживается для управляемых удостоверений, назначаемых пользователем, в этих регионах.

Клиентские библиотеки идентификации Azure

В клиентских библиотеках удостоверений Azure выберите один из следующих подходов:

Используйте DefaultAzureCredential, который пытается использовать WorkloadIdentityCredential.
Создайте экземпляр ChainedTokenCredential, который включает в себя WorkloadIdentityCredential.
Используйте WorkloadIdentityCredential напрямую.

При запросе токенов с помощью WorkloadIdentityCredential передавайте области в формате Microsoft Entra ID v2 <resource>/.default, например https://management.azure.com/.default. Необработанный URI ресурса, такой как https://management.azure.com/, может завершиться ошибкой, поскольку идентификация рабочей нагрузки использует конечную точку токенов Microsoft Entra v2, а не поток IMDS resource, используемый управляемой идентификацией. Дополнительные сведения о том, как работают области действия в конечной точке токена v2, см. в статье Получение токена.

В следующей таблице приведена минимальная версия пакета, необходимая для каждой клиентской библиотеки экосистемы языков:

Экосистема	Библиотека	Минимальная версия
.NET	Azure.Identity	1.9.0
C++	azure-identity-cpp	1.6.0
Иди	azidentity	1.3.0
Java	azure-identity	1.9.0
Node.js	@azure/identity	3.2.0
Python	azure-identity	1.13.0

Примеры кода клиентской библиотеки удостоверений Azure

В следующих примерах кода используется DefaultAzureCredential. Этот тип учетных данных использует переменные среды, инъектированные мутацией удостоверения рабочей нагрузки вебхук, для проверки подлинности в Azure Key Vault. Чтобы просмотреть примеры с помощью одного из других подходов, обратитесь к клиентским библиотекам, зависящим от экосистемы.

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

string keyVaultUrl = Environment.GetEnvironmentVariable("<key-vault-url>");
string secretName = Environment.GetEnvironmentVariable("<secret-name>");

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

KeyVaultSecret secret = await client.GetSecretAsync(secretName);

#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("<key-vault-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;
}

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("<key-vault-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)
   }
}

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("<key-vault-url>");
        String secretName = env.get("<secret-name>");

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

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

const main = async () => {
    const keyVaultUrl = process.env["<key-vault-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);
});

import os

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

def main():
    keyvault_url = os.getenv('<key-vault-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()

Библиотека проверки подлинности Майкрософт (MSAL)

Следующие клиентские библиотеки являются минимальной версией:

Экосистема	Библиотека	Изображение	Пример	Имеет Windows
.NET	Библиотека проверки подлинности Майкрософт для dotnet	`ghcr.io/azure/azure-workload-identity/msal-net:latest`	Ссылка	Да
Иди	Библиотека аутентификации Microsoft для Go	`ghcr.io/azure/azure-workload-identity/msal-go:latest`	Ссылка	Да
Java	Библиотека проверки подлинности Майкрософт для java	`ghcr.io/azure/azure-workload-identity/msal-java:latest`	Ссылка	Нет
JavaScript	Библиотека проверки подлинности Майкрософт для js	`ghcr.io/azure/azure-workload-identity/msal-node:latest`	Ссылка	Нет
Python	Библиотека проверки подлинности Майкрософт для Python	`ghcr.io/azure/azure-workload-identity/msal-python:latest`	Ссылка	Нет

Принцип работы

В этой модели безопасности кластер AKS выступает в качестве издателя маркеров. Microsoft Entra ID использует OIDC для обнаружения открытых ключей подписания и проверки подлинности токена учетной записи службы перед обменом его на токен Microsoft Entra. Рабочая нагрузка может обменять токен учетной записи службы, встроенный в его том, на токен Microsoft Entra с помощью библиотеки Azure Identity или MSAL.

В следующей таблице описаны необходимые конечные точки издателя OIDC для идентификатора рабочей нагрузки Microsoft Entra.

Конечная точка	Описание
`{IssuerURL}/.well-known/openid-configuration`	Также известен как документ обнаружения OIDC. Эта запись содержит метаданные о конфигурациях эмитента.
`{IssuerURL}/openid/v1/jwks`	Здесь содержатся открытые ключи подписывания, которые Microsoft Entra ID использует для проверки подлинности токена учетной записи службы.

На следующей схеме показана последовательность проверки подлинности с помощью OIDC:

Автоматическая смена сертификата веб-перехватчика

Аналогично другим надстройкам веб-перехватчика, операция автоматического обновления сертификата кластера обновляет сертификат.

Метки и аннотации учетной записи службы

Идентификация рабочей нагрузки Microsoft Entra поддерживает следующие сопоставления, связанные с сервисной учетной записью:

Один к одному, где учетная запись службы ссылается на объект Microsoft Entra.
Многие-к-одному, где несколько учетных записей служб ссылаются на один и тот же объект Microsoft Entra.
Один ко многим, где учетная запись службы ссылается на несколько объектов Microsoft Entra путем изменения аннотации идентификатора клиента. Дополнительные сведения см. в статье "Как объединить несколько удостоверений с учетной записью Kubernetes".

Примечание.

При обновлении заметок учетной записи службы необходимо перезапустить pod, чтобы изменения вступили в силу.

Если вы использовали управляемое пользователем удостоверение Microsoft Entra pod, то думайте о учетной записи службы как субъекте безопасности Azure, за исключением того, что учетная запись службы является частью основного API Kubernetes, а не пользовательского определения ресурсов (CRD). В следующих разделах описывается список доступных меток и аннотаций, которые можно использовать для настройки поведения при обмене токена учетной записи службы на токен доступа Microsoft Entra.

Аннотации учетной записи службы

Все заметки являются необязательными. Если заметка не указана, используется значение по умолчанию.

Аннотация	Описание	По умолчанию
`azure.workload.identity/client-id`	Представляет приложение Microsoft Entra Идентификатор клиента, используемый с модулем pod.
`azure.workload.identity/tenant-id`	Представляет идентификатор клиента Azure, в котором Приложение 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.

Метки Pod

Примечание.

Для приложений, использующих идентификатор рабочей нагрузки Microsoft Entra, необходимо добавить метку azure.workload.identity/use: "true" в спецификацию pod для AKS, чтобы переместить идентификацию рабочей нагрузки в сценарий Fail Close, обеспечивая согласованное и надежное поведение подов, которые должны использовать идентификацию рабочей нагрузки. В противном случае модули pod завершаются сбоем после перезапуска.

Метка	Описание	Рекомендуемое значение	Обязательное поле
`azure.workload.identity/use`	Эта метка требуется в спецификации шаблона пода. Только поды с этой меткой мутируются с помощью мутационного admission webhook azure-workload-identity для инъекции специфичных для Azure переменных окружения и проецируемого тома токена учетной записи службы.	истинно	Да

Аннотации pod

Все заметки являются необязательными. Если заметка не указана, используется значение по умолчанию.

Аннотация	Описание	По умолчанию
`azure.workload.identity/service-account-token-expiration`	Дополнительные сведения см. в аннотациях учетной записи службы . Аннотации Pod имеют приоритет над аннотациями учетной записи службы.	3600 Поддерживаемый диапазон — 3600–86400.
`azure.workload.identity/skip-containers`	Представляет разделенный точкой с запятой список контейнеров, для которых следует пропустить добавление проецируемого объема токена учетной записи службы. Например, `container1;container2`.	По умолчанию том проецируемого токена учетной записи службы добавляется ко всем контейнерам, если модуль помечен меткой `azure.workload.identity/use: true`.
`azure.workload.identity/inject-proxy-sidecar`	Внедряет контейнер инициализацию прокси-сервера и боковую панель прокси-сервера в модуль pod. Прокси-сервер используется для перехвата запросов маркеров в IMDS и получения маркера Microsoft Entra от имени пользователя с федеративными учетными данными удостоверения.	неправда
`azure.workload.identity/proxy-sidecar-port`	Представляет порт сайдкара прокси-сервера.	8000

Используйте привязки identity и прямую федерацию в одной рабочей нагрузке

Проецируемый токен сервисной учётной записи имеет только одну аудиторию. Если привязки идентификационных данных включены, вебхук привязки идентификационных данных задаёт для токена по умолчанию, на который ссылается AZURE_FEDERATED_TOKEN_FILE, значение audience api://AKSIdentityBinding, которое использует прокси привязки идентификационных данных.

Для прямой федерации Идентификация рабочей нагрузки Microsoft Entra (без привязок идентификаторов) требуется токен с аудиторией api://AzureADTokenExchange. Повторное использование файла токена привязки удостоверения при прямой федерации завершается ошибкой AADSTS700212, так как аудитория учетных данных федеративного удостоверения не соответствует аудитории токена.

Чтобы использовать привязки удостоверений для одного управляемого удостоверения и прямую федерацию для другого в рамках одной рабочей нагрузки, спроецируйте второй токен учетной записи службы с аудиторией api://AzureADTokenExchange и укажите в коде прямой федерации этот файл:

apiVersion: v1
kind: Pod
metadata:
  name: workload-with-ib-and-direct-fic
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: workload-sa
  containers:
  - name: app
    image: <image>
    volumeMounts:
    - name: direct-fic-token
      mountPath: /var/run/secrets/direct-fic
      readOnly: true
    env:
    - name: DIRECT_FIC_TOKEN_FILE
      value: /var/run/secrets/direct-fic/token
  volumes:
  - name: direct-fic-token
    projected:
      sources:
      - serviceAccountToken:
          path: token
          audience: api://AzureADTokenExchange
          expirationSeconds: 3600

Используйте AZURE_FEDERATED_TOKEN_FILE для процесса привязки удостоверения, а файл настраиваемого токена, например DIRECT_FIC_TOKEN_FILE, — для процесса прямого потока учетных данных федеративного удостоверения.

Переход на Идентификация рабочей нагрузки Microsoft Entra

Кластеры, уже работающие с управляемой идентификацией Pod, можно настроить для использования Идентификация рабочей нагрузки Microsoft Entra одним из двух способов:

Используйте ту же конфигурацию, что и для pod-управляемой идентичности. Учетной записи службы в пространстве имен можно добавить аннотацию с идентификатором для включения Идентификация рабочей нагрузки Microsoft Entra и внедрения аннотаций в поды.
Перепишите ваше приложение, чтобы использовать последнюю версию клиентской библиотеки идентификации Azure.

Чтобы упростить процесс миграции, мы разработали вспомогательный модуль миграции, который преобразует транзакции службы метаданных экземпляров (IMDS), выполняемые вашим приложением, в OIDC. Сайдкар миграции не предназначен для долгосрочных решений, а служит способом быстрого запуска с использованием Идентификация рабочей нагрузки Microsoft Entra. Запуск бокового автомобиля миграции в прокси приложения выполняет транзакции IMDS приложения к OIDC. Альтернативный подход — обновление до поддерживаемой версии клиентской библиотеки удостоверений Azure, которая поддерживает проверку подлинности OIDC.

В следующей таблице приведены рекомендации по миграции или развертыванию для кластера AKS:

Сценарий	Описание
Новое или существующее развертывание кластера запускает поддерживаемую версию клиентской библиотеки удостоверений Azure	Никаких шагов миграции не требуется. Примеры ресурсов развертывания: развертывание и настройка идентификатора рабочей нагрузки Microsoft Entra в новом кластере
Новое или существующее развертывание кластера выполняет неподдерживаемую версию клиентской библиотеки идентификационных данных Azure.	Обновите образ контейнера, чтобы использовать поддерживаемую версию пакета SDK для удостоверений Azure или использовать боковику миграции.

Следующие шаги

Сведения о настройке модуля pod для проверки подлинности с помощью удостоверения рабочей нагрузки в качестве параметра миграции см. в статье "Модернизация проверки подлинности приложения с помощью идентификатора рабочей нагрузки Microsoft Entra".
См. раздел "Развертывание и настройка кластера AKS с помощью идентификатора рабочей нагрузки Microsoft Entra", который помогает развернуть кластер и настроить пример приложения для использования идентификатора рабочей нагрузки.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-06-12

Используйте идентификацию рабочих нагрузок в Microsoft Entra с Azure Kubernetes Service (AKS)

Предпосылки

Ограничения

Клиентские библиотеки идентификации Azure

Примеры кода клиентской библиотеки удостоверений Azure

Библиотека проверки подлинности Майкрософт (MSAL)

Принцип работы

Автоматическая смена сертификата веб-перехватчика

Метки и аннотации учетной записи службы

Аннотации учетной записи службы

Метки Pod

Аннотации pod

Используйте привязки identity и прямую федерацию в одной рабочей нагрузке

Переход на Идентификация рабочей нагрузки Microsoft Entra

Следующие шаги

Обратная связь

Дополнительные ресурсы