Краткое описание

Предоставление OAuth 2.0-идентичностей для AI-агентов с учётными данными для каждого экземпляра и журналом аудита через Microsoft Graph.

• Создаёт Blueprints идентичностей агентов (шаблоны приложений), BlueprintPrincipals (служебные учётные записи) и идентичности агентов для каждого экземпляра, каждая с независимыми выделениями прав и областью аудита

• Реализует двухшаговый обмен токенами fmi_path для автономных и от имени кого-либо (OBO) потоков, с поддержкой Workload Identity Federation, клиентских секретов и межтенантных сценариев

• Предоставляет Microsoft.Identity.Web.AgentIdentities для .NET и контейнеризованный Microsoft Entra SDK for AgentID (sidecar) с поддержкой Python, Node, Go и Java

• Выделяет права приложений и делегированные права, ограниченные для каждой идентичности агента, через appRoleAssignments и oauth2PermissionGrants; учётные данные хранятся в Blueprint, а не в отдельных идентичностях агентов

Microsoft Entra Agent ID

Создание и управление идентичностями с поддержкой OAuth 2.0 для AI-агентов с использованием Microsoft Graph. Каждый экземпляр агента получает уникальную идентичность, журнал аудита и независимо ограниченные выделения прав.

Быстрая справка

Свойство	Значение
Сервис	Microsoft Entra Agent ID
API	Microsoft Graph (https://graph.microsoft.com/v1.0)
Требуемая роль	Agent Identity Developer, Agent Identity Administrator или Application Administrator
Модель объектов	Blueprint (приложение) → BlueprintPrincipal (SP) → Agent Identity (SP)
Обмен при выполнении	Двухшаговый обмен через fmi_path (автономный и OBO)
.NET-помощник	Microsoft.Identity.Web.AgentIdentities
Полиглот-помощник	Microsoft Entra SDK for AgentID (sidecar-контейнер)

Когда использовать этот навык

• Предоставление нового Blueprint идентичности агента и BlueprintPrincipal

• Создание идентичностей агентов для каждого экземпляра под Blueprint

• Настройка учётных данных (FIC, Managed Identity или клиентский секрет) на Blueprint

• Реализация двухшагового обмена токенами через fmi_path при выполнении (автономный или OBO)

• Межтенантные потоки токенов агентов

• Развёртывание Microsoft Entra SDK for AgentID (sidecar) для полиглотных агентов (Python, Node, Go, Java)

• Выделение для каждой идентичности агента прав приложений (appRoleAssignments) или делегированных прав (oauth2PermissionGrants)

• Диагностика ошибок Agent ID, таких как AADSTS82001, AADSTS700211 или PropertyNotCompatibleWithAgentIdentity

Инструменты MCP

Инструмент	Назначение
mcp_azure_mcp_documentation	Поиск по Microsoft Learn для получения актуальной информации об установке Agent ID, формах Graph API и конфигурации SDK

Специализированный MCP-сервер идентичности агента на данный момент отсутствует. Этот навык поддерживает прямые вызовы Microsoft Graph API (PowerShell или Python requests). Используйте mcp_azure_mcp_documentation для проверки тел запросов и endpoint-ов по актуальной документации перед запуском.

Перед началом работы

Используйте инструмент mcp_azure_mcp_documentation для поиска актуальной документации по Agent ID на Microsoft Learn:

• "Microsoft Entra Agent ID setup instructions"

• "Microsoft Entra SDK for AgentID"

Проверяйте тела запросов и endpoint-ы в соответствии с установленной версией SDK — формы Graph API развиваются.

Концептуальная модель

Agent Identity Blueprint (приложение)         ← один на тип/проект агента
  └── BlueprintPrincipal (служебная учётная запись)    ← ОБЯЗАТЕЛЬНО создаётся явно
        ├── Agent Identity (SP): agent-1        ← один на экземпляр агента
        ├── Agent Identity (SP): agent-2
        └── Agent Identity (SP): agent-3

Понятие	Описание
Blueprint	Объект приложения, определяющий тип/класс агента. Хранит учётные данные (секрет, сертификат, федеративная идентичность).
BlueprintPrincipal	Служебная учётная запись для Blueprint в тенанте. Не создаётся автоматически.
Agent Identity	Идентичность только на основе служебной учётной записи для одного экземпляра агента. Не может хранить собственные учётные данные.
Sponser	Пользователь (или группа, для идентичности агента), ответственный за идентичность. Обязателен при создании.

Предварительные требования

Требуемые роли Entra

Одна из: Agent Identity Developer, Agent Identity Administrator или Application Administrator.

PowerShell (интерактивная настройка)

PowerShell 7+

Install-Module Microsoft.Graph.Applications -Scope CurrentUser -Force

### Python (программное provisioning)

pip install azure-identity requests

## Аутентификация

> DefaultAzureCredential не поддерживается. Токены Azure CLI содержат Directory.AccessAsUser.All, который API Agent Identity жёстко отклоняют (403). Используйте отдельную регистрацию приложения с client_credentials, либо Connect-MgGraph с явными делегированными scopes.

### PowerShell (делегирование)

Connect-MgGraph -Scopes @( "AgentIdentityBlueprint.Create", "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentityBlueprintPrincipal.Create", "AgentIdentity.Create.All", "User.Read" )

### Python (приложение)

import os, requests from azure.identity import ClientSecretCredential

credential = ClientSecretCredential( tenant_id=os.environ["AZURE_TENANT_ID"], client_id=os.environ["AZURE_CLIENT_ID"], client_secret=os.environ["AZURE_CLIENT_SECRET"], ) token = credential.get_token("https://graph.microsoft.com/.default")

GRAPH = "https://graph.microsoft.com/v1.0" headers = { "Authorization": f"Bearer {token.token}", "Content-Type": "application/json", "OData-Version": "4.0", }

## Основной рабочий процесс

### Шаг 1: Создание Agent Identity Blueprint

Используйте типизированный endpoint. Sponsors должны быть **Users** при создании Blueprint. Этот фрагмент предполагает использование клиента `requests` и словаря `headers` из блока аутентификации Python выше.

import subprocess import requests

user_id = subprocess.run( ["az", "ad", "signed-in-user", "show", "--query", "id", "-o", "tsv"], capture_output=True, text=True, check=True, ).stdout.strip()

blueprint_body = { "displayName": "My Agent Blueprint", "sponsors@odata.bind": [ f"https://graph.microsoft.com/v1.0/users/{user_id}" ], } resp = requests.post( f"{GRAPH}/applications/microsoft.graph.agentIdentityBlueprint", headers=headers, json=blueprint_body, ) resp.raise_for_status()

blueprint = resp.json() app_id = blueprint["appId"] blueprint_obj_id = blueprint["id"]

### Шаг 2: Создание BlueprintPrincipal

> Обязательно. Создание Blueprint НЕ создаёт автоматически его service principal. Пропуск этого шага приводит к:
> 400: The Agent Blueprint Principal for the Agent Blueprint does not exist.

sp_body = {"appId": app_id} resp = requests.post( f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal", headers=headers, json=sp_body, ) resp.raise_for_status()

Делайте ваши скрипты provisioning идемпотентными — всегда проверяйте наличие BlueprintPrincipal, даже если Blueprint уже существует.

### Шаг 3: Создание Agent Identities

Sponsors для Agent Identity могут быть **Users или Groups**.

agent_body = { "displayName": "my-agent-instance-1", "agentIdentityBlueprintId": app_id, "sponsors@odata.bind": [ f"https://graph.microsoft.com/v1.0/users/{user_id}" ], } resp = requests.post( f"{GRAPH}/servicePrincipals/microsoft.graph.agentIdentity", headers=headers, json=agent_body, ) resp.raise_for_status() agent = resp.json() agent_sp_id = agent["id"]

## Аутентификация во время выполнения

Agents аутентифицируются во время выполнения с использованием учётных данных, настроенных на **Blueprint** (не на Agent Identity — Agent Identities не могут хранить учётные данные).

| Вариант | Сценарий использования | Учётные данные на Blueprint |
| --- | --- | --- |
| Managed Identity + WIF | Production (хостинг на Azure) | Federated Identity Credential |
| Client secret | Локальная разработка / тестирование | Password credential |
| Microsoft Entra SDK for AgentID | Полигональные / 3P agents | Sidecar container получает токены через HTTP |

Для двухэтапного обмена `fmi_path` (токен родителя → Graph-токен для каждого Agent Identity), который обеспечивает каждому экземпляру agent уникальный claim `sub` и журнал аудита, см. [references/runtime-token-exchange.md](https://github.com/microsoft/azure-skills/blob/HEAD/.github/plugins/azure-skills/skills/entra-agent-id/references/runtime-token-exchange.md).

Для OBO (agent действует от имени пользователя), см. [references/obo-blueprint-setup.md](https://github.com/microsoft/azure-skills/blob/HEAD/.github/plugins/azure-skills/skills/entra-agent-id/references/obo-blueprint-setup.md).

Для контейнеризированного полигонального sidecar аутентификации (Python, Node, Go, Java — без встраивания SDK), см. [references/sdk-sidecar.md](https://github.com/microsoft/azure-skills/blob/HEAD/.github/plugins/azure-skills/skills/entra-agent-id/references/sdk-sidecar.md).

Для деталей настройки MI+WIF и client-secret, см. [references/oauth2-token-flow.md](https://github.com/microsoft/azure-skills/blob/HEAD/.github/plugins/azure-skills/skills/entra-agent-id/references/oauth2-token-flow.md).

### .NET быстрый путь

Для .NET-сервисов используйте **`Microsoft.Identity.Web.AgentIdentities`** — он берёт на себя управление Federated Identity Credential и двухэтапный обмен. См. README пакета на `github.com/AzureAD/microsoft-identity-web` в каталоге `src/Microsoft.Identity.Web.AgentIdentities/`.

## Предоставление разрешений (для каждого Agent Identity)

Agent Identities поддерживают как application permissions (автономные), так и delegated permissions (OBO). Назначения разрешений привязываются **к каждому Agent Identity**, а не к BlueprintPrincipal.

### Application permissions (автономные)

graph_sp = requests.get( f"{GRAPH}/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'", headers=headers, ).json()["value"][0]

user_read_all = next(r for r in graph_sp["appRoles"] if r["value"] == "User.Read.All")

requests.post( f"{GRAPH}/servicePrincipals/{agent_sp_id}/appRoleAssignments", headers=headers, json={ "principalId": agent_sp_id, "resourceId": graph_sp["id"], "appRoleId": user_read_all["id"], }, ).raise_for_status()

### Delegated permissions (OBO)

from datetime import datetime, timedelta, timezone

expiry = (datetime.now(timezone.utc) + timedelta(days=3650)).strftime("%Y-%m-%dT%H:%M:%SZ")

requests.post( f"{GRAPH}/oauth2PermissionGrants", headers=headers, json={ "clientId": agent_sp_id, "consentType": "AllPrincipals", "resourceId": graph_sp["id"], "scope": "User.Read Tasks.ReadWrite Mail.Send", "expiryTime": expiry, }, ).raise_for_status()

Административные URL для согласия в браузере не работают для Agent Identities — используйте `oauth2PermissionGrants` для программного делегированного согласия.

## Многотенантные Agent Identities

Blueprints могут быть многотенантными (`signInAudience: AzureADMultipleOrgs`). При обмене токенами между тенантами:

> Шаг 1 обмена родительского токена ДОЛЖЕН нацеливаться на домашний тенант Agent Identity, а не Blueprint. Неправильный тенант → AADSTS700211: No matching federated identity record found.

См. [references/runtime-token-exchange.md](https://github.com/microsoft/azure-skills/blob/HEAD/.github/plugins/azure-skills/skills/entra-agent-id/references/runtime-token-exchange.md) для полных примеров между тенантами.

## Справочник API

| Операция | Метод | Endpoint |
| --- | --- | --- |
| Создание Blueprint | POST | /applications/microsoft.graph.agentIdentityBlueprint |
| Создание BlueprintPrincipal | POST | /servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal |
| Создание Agent Identity | POST | /servicePrincipals/microsoft.graph.agentIdentity |
| Добавление FIC к Blueprint | POST | /applications/{id}/microsoft.graph.agentIdentityBlueprint/federatedIdentityCredentials |
| Получение списка Agent Identities | GET | /servicePrincipals/microsoft.graph.agentIdentity |
| Предоставление application permission | POST | /servicePrincipals/{id}/appRoleAssignments |
| Предоставление delegated permission | POST | /oauth2PermissionGrants |
| Удаление Agent Identity | DELETE | /servicePrincipals/{id} |
| Удаление Blueprint | DELETE | /applications/{id} |

Base URL: `https://graph.microsoft.com/v1.0`.

## Необходимые разрешения Graph

| Разрешение | Назначение |
| --- | --- |
| AgentIdentityBlueprint.Create | Создание Blueprints |
| AgentIdentityBlueprint.ReadWrite.All | Чтение/обновление Blueprints |
| AgentIdentityBlueprintPrincipal.Create | Создание BlueprintPrincipals |
| AgentIdentity.Create.All | Создание Agent Identities |
| AgentIdentity.ReadWrite.All | Чтение/обновление Agent Identities |
| Application.ReadWrite.All | CRUD Blueprint над объектами приложений |
| AppRoleAssignment.ReadWrite.All | Предоставление application permissions |
| DelegatedPermissionGrant.ReadWrite.All | Предоставление delegated permissions |

Предоставьте административное согласие (обязательно для application permissions):

az ad app permission admin-consent --id <client-id>

После административного согласия токены могут не включать новые claims в течение 30–120 секунд — повторяйте запрос с экспоненциальной задержкой.

## Лучшие практики

- **Всегда создавайте BlueprintPrincipal после Blueprint** — он не создаётся автоматически.

- **Используйте типизированные endpoint'ы** (`/applications/microsoft.graph.agentIdentityBlueprint`) вместо голых `/applications` с `@odata.type`.

- **Учётные данные хранятся на Blueprint** — Agent Identities не могут хранить секреты/сертификаты (`PropertyNotCompatibleWithAgentIdentity`).

- **Указывайте `OData-Version: 4.0`** в каждом запросе к Graph.

- **Используйте Workload Identity Federation для production** — client secrets только для локальной разработки.

- **Устанавливайте `identifierUris: ["api://{appId}"]` на Blueprint** перед разрешением scope OAuth2.

- **Никогда не используйте токены Azure CLI** для API Agent Identity — `Directory.AccessAsUser.All` вызывает жёсткий 403.

- **Используйте `fmi_path`** с `client_credentials` — НЕ RFC 8693 `urn:ietf:params:oauth:grant-type:token-exchange` (возвращает `AADSTS82001`).

- **Всегда используйте scope `/.default`** на обоих шагах обмена — отдельные scopes приводят к ошибкам.

- **Шаг 1 нацеливается на домашний тенант Agent Identity** в многотенантных сценариях.

- **Предоставляйте разрешения для каждого Agent Identity**, а не BlueprintPrincipal.

- **Обрабатывайте задержки распространения разрешений** — повторяйте запросы с 403 с задержкой 30–120 секунд после административного согласия.

- **Держите Entra SDK for AgentID на localhost** — никогда не открывайте через LoadBalancer или Ingress.

## Решение проблем

| Ошибка | Причина | Решение |
| --- | --- | --- |
| AADSTS82001 | Использован RFC 8693 token-exchange grant | Используйте client_credentials с fmi_path |
| AADSTS700211 | Шаг 1 обмена родительского токена нацелен на неправильный тенант | Нацельтесь на домашний тенант Agent Identity |
| AADSTS50013 | Пользовательский OBO-токен нацелен на Graph, а не Blueprint | Используйте api://{blueprint_app_id}/access_as_user |
| AADSTS65001 | Отсутствует grant или использованы отдельные scopes | Используйте /.default и проверьте oauth2PermissionGrants |
| 403 Authorization_RequestDenied | Нет grant для данного Agent Identity | Добавьте через appRoleAssignments или oauth2PermissionGrants |
| PropertyNotCompatibleWithAgentIdentity | Попытка добавить учётные данные к SP Agent Identity | Размещайте учётные данные на Blueprint |
| Agent Blueprint Principal does not exist | BlueprintPrincipal не создан | Шаг 2 основного рабочего процесса |
| AADSTS650051 при административном согласии | SP уже существует от частичного согласия | Предоставьте напрямую через appRoleAssignments |

## Справочники

| Файл | Содержание |
| --- | --- |
| references/runtime-token-exchange.md | Двухэтапный обмен fmi_path: автономный + OBO, между тенантами |
| references/oauth2-token-flow.md | MI + WIF (production) и client secret (локальная разработка) |
| references/obo-blueprint-setup.md | Настройка Blueprint как OAuth2 API для OBO |
| references/sdk-sidecar.md | Microsoft Entra SDK for AgentID — архитектура, конфигурация, endpoint'ы |
| references/sdk-sidecar-deployment.md | Шаблоны кода SDK (Python/TypeScript), манифесты Docker/Kubernetes, безопасность, решение проблем |
| references/known-limitations.md | Документированные ограничения, организованные по категориям |

### Внешние ссылки

| Ресурс | URL |
| --- | --- |
| Руководство по настройке Agent ID | https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-setup-instructions |
| Настройка с помощью AI | https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-id-ai-guided-setup |
| Microsoft Entra SDK for AgentID | https://learn.microsoft.com/en-us/entra/msidweb/agent-id-sdk/overview |
| Microsoft.Identity.Web.AgentIdentities (.NET) | https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.AgentIdentities/README.AgentIdentities.md |

Установка

npx skills add https://github.com/microsoft/azure-skills --skill entra-agent-id