Проверка подлинности и получение маркеров для автономных агентов

Автономные агенты выполняют операции, используя собственное удостоверение, а не выступая в качестве делегата пользователя. Для безопасной работы автономный агент должен пройти проверку подлинности с помощью Microsoft Entra ID, получить маркеры доступа и предоставить соответствующие разрешения. В этой статье вас проведут через полный процесс:

1. Настройте учетные данные клиента.
2. Запросить токен для шаблона удостоверения агента.
3. Запрос токена удостоверения агента.
4. Предоставление разрешений приложения (согласие администратора).
5. (Необязательно) Создание и проверка подлинности в качестве учетной записи пользователя агента для ресурсов, требующих удостоверения пользователя.

Замечание

В этой статье рассматриваются автономные агенты, работающие с собственным удостоверением. Если агенту необходимо действовать от имени пользователя, вошедшего в систему, см. статью "Проверка подлинности пользователей" и получение маркеров для интерактивных агентов.

Необходимые условия

Перед внедрением аутентификации агента с помощью токена убедитесь, что у вас есть:

• Схема удостоверения агента.
• Удостоверение агента. Вам нужен идентификатор клиента агента.
• Понимание протоколов OAuth в Microsoft Entra ID для агентов.

Для авторизации администратора также требуется:

• Права администратора в клиенте Microsoft Entra ID.
• Понимание конкретных разрешений, необходимых агенту.

Для проверки подлинности учетной записи пользователя агента также потребуется:

• Понимание учетных записей пользователей агентов в Microsoft Entra ID для агентов.

Настройка учетных данных клиента

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

Предупреждение

Секреты клиента не должны использоваться в качестве учетных данных клиента в рабочих средах для схем удостоверений агента из-за рисков безопасности. Вместо этого используйте более безопасные методы проверки подлинности, такие как учетные данные федеративной идентификации (FIC) с управляемыми идентификациями или клиентские сертификаты. Эти методы обеспечивают повышенную безопасность, устраняя необходимость хранения конфиденциальных секретов непосредственно в конфигурации приложения.

Соберите учетные данные, настроенные в схеме удостоверения агента. Вам потребуется одно из следующих действий:

• Managed identity (рекомендуется): идентификатор клиента для управляемого удостоверения и маркер из службы метаданных экземпляра Azure (IMDS).
• Сертификат: отпечаток сертификата или PFX-файл.
• Секрет клиента (только для разработки): значение секрета.

Майкрософт. Identity.Web

Для рабочей среды используйте управляемое удостоверение как федеративное удостоверение.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "<managed-identity-client-id>"
      }
    ]
  }
}

Только для локальной разработки и тестирования можно использовать секрет клиента:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "<your-tenant-id>",
    "ClientId": "<agent-blueprint-clientid>",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Запрос токена для шаблона удостоверения агента

При запросе токена для чертежа идентификации агента укажите идентификатор клиента агента в параметре fmi_path (параметр маршрута федеративного управляемого удостоверения). Этот параметр сообщает Microsoft Entra ID, какой агентский идентификатор используется планом.

При использовании секрета клиента во время локальной разработки укажите client_secret параметр. Для сертификатов и управляемых удостоверений используйте client_assertion и client_assertion_type вместо этого.

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-blueprint-client-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_secret=<client-secret>
&fmi_path=<agent-identity-client-id>

Майкрософт. Identity.Web

С Майкрософт.Identity.Web, вам не нужно явно запрашивать токен для шаблона удостоверения агента. Майкрософт. Identity.Web это делает для вас.

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.AgentIdentities

Запрос токена удостоверения агента

После получения токена плана идентификации агента (T1) используйте его, чтобы запросить токен удостоверения агента.

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-client-id>
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token-T1>

Майкрософт. Identity.Web

Майкрософт.Identity.Web выполняет задачи протокола приобретения токенов для вас, при условии что вы используете новый services.AddAgentIdentities() в коллекции служб при инициализации приложения.

Инициализация приложения:

// Program.cs
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.Resource;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration);
builder.Services.AddAgentIdentities();
builder.Services.AddInMemoryTokenCaches();

Используйте шаблон .WithAgentIdentity() для запроса токенов доступа.

// In an API endpoint or service method where HttpContext is available
app.MapGet("/call-api", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    AuthorizationHeaderProviderOptions options =
        new AuthorizationHeaderProviderOptions().WithAgentIdentity("<agent-identity-client-id>");

    // Request agent identity tokens
    string authorizationHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForAppAsync("https://graph.microsoft.com/.default", options);

    // The authHeader contains "Bearer " + the access token
    return Results.Ok(authorizationHeader);
});

Предоставление разрешений для приложения

Агенты часто должны выполнять действия в Microsoft Graph и других веб-службах, требующих разрешения приложения Microsoft Entra ID (представленных в виде ролей приложения). Автономные агенты должны запрашивать эти разрешения от администратора Microsoft Entra ID.

Существует два способа предоставления автономному агенту разрешений приложения:

• Администратор может создать appRoleAssignment с помощью API Microsoft Graph или PowerShell.
• Агент может направить администратора на страницу согласия с помощью URL-адреса согласия администратора.

Создание назначения роли приложения с помощью API

Чтобы получить назначение роли приложения, выполните следующие действия.

1. Получите токен доступа с разрешениями приложения Application.Read.All и AppRoleAssignment.ReadWrite.All.

2. Получите идентификатор объекта субъекта-службы ресурсов, к которому вы пытаетесь получить доступ. Например, чтобы найти идентификатор объекта субъекта-службы Microsoft Graph:

   1. Перейдите к Центр администрирования Microsoft Entra.
   2. Перейдите к Entra ID -->Enterprise Applications
   3. Фильтрация по типу приложения == Майкрософт Приложения
   4. Найдите Microsoft Graph.

3. Получите уникальный идентификатор роли приложения, которую вы хотите назначить.

4. Создайте назначение роли приложения:

   Microsoft API Graph

   POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
   Authorization: Bearer <token>
   Content-Type: application/json
   
   {
     "principalId": "<agent-identity-id>",
     "resourceId": "<microsoft-graph-sp-object-id>",
     "appRoleId": "<app-role-id>"
   }
   

   Microsoft Graph PowerShell

   Connect-MgGraph -Scopes "Application.Read.All AppRoleAssignment.ReadWrite.All" -TenantId <your-test-tenant>
   
   # Get the service principal for Microsoft Graph (well-known app ID)
   $graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"
   
   # Get your application's service principal (replace with your app's client ID)
   $agentId = "<agent-identity-id>"
   
   # Find the App Role ID for "User.ReadBasic.All"
   $userReadBasicRole = $graphSp.AppRoles | Where-Object {
       $_.Value -eq "User.ReadBasic.All" -and $_.AllowedMemberTypes -contains "Application"
   }
   
   # Assign the app role
   New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $agentId `
       -PrincipalId $agentId `
       -ResourceId $graphSp.Id `
       -AppRoleId $userReadBasicRole.Id
   

---

Запрос авторизации от администратора клиента

Чтобы предоставить делегированные разрешения, создайте URL-адрес авторизации, используемый для запроса администратора. Параметр роли используется для указания запрошенных разрешений приложения.

Обязательно используйте идентификатор клиента агента в следующем запросе.

https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&redirect_uri=https://entra.microsoft.com/TokenAuthorize
&state=xyz123

Реализации агента могут перенаправлять администратора на этот URL-адрес различными способами, например включить его в сообщение, отправленное администратору в окне чата. Когда администратор перенаправляется по этому URL-адресу, им предлагается войти и предоставить согласие на разрешения, указанные в параметре области. На данный момент необходимо использовать указанный URI перенаправления, который направляет администратора на пустую страницу после предоставления согласия.

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

Аутентифицируйтесь как учетная запись пользователя агента

Помимо использования маркеров только для приложений, автономные агенты могут аутентифицироваться как учетная запись пользователя агента. Учетные записи пользователей агентов — это особый тип учетной записи пользователя в Microsoft Entra, созданной для использования агентами. Они чаще всего используются, когда агенту необходимо подключиться к системам, которым требуется наличие учетной записи пользователя, например почтового ящика, канала Teams или других ресурсов для конкретного пользователя.

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

Получение авторизации для создания учетных записей пользователей агентов

Чтобы создать учетные записи пользователей агентов, необходимо предоставить удостоверению агента разрешение на использование приложения AgentIdUser.ReadWrite.IdentityParentedBy в клиенте. Вы можете получить авторизацию одним из двух способов:

• Запрос авторизации агента. Не забудьте использовать проект удостоверения агента в качестве client_id, а не само удостоверение агента.
• Вручную создайте appRoleAssignment в клиенте. Используйте идентификатор объекта сервисного принципала в схеме удостоверения агента в качестве principalId значения, а не идентификатор приложения (клиента).

Если вы хотите использовать другого клиента вместо схемы шаблона агента для создания учетных записей пользователей агентов, этот клиент должен получить AgentIdUser.ReadWrite.All делегированное разрешение или разрешение приложения.

Создание учетной записи пользователя агента

Создайте учетную запись пользователя агента с помощью шаблона удостоверения агента или другого утвержденного клиента. Рекомендуемый способ создания учетной записи пользователя агента — использовать шаблон идентификации агента. Для создания учетной записи пользователя агента требуется маркер доступа .

REST

После того как у вас будет токен доступа с необходимым разрешением, выполните запрос следующим образом:

POST https://graph.microsoft.com/beta/users
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
  "@odata.type": "microsoft.graph.agentUser",
  "displayName": "New Agent User",
  "userPrincipalName": "agentuserupn@tenant.onmicrosoft.com",
  "identityParentId": "{agent-identity-id}",
  "mailNickname": "agentuserupn",
  "accountEnabled": true
}

Майкрософт. Identity.Web

Чтобы использовать Майкрософт.Identity.Web для создания учетной записи пользователя агента, выполните следующие действия.

1. Добавьте следующее в файл конфигурации:

   {
     "AzureAd": {
       "Instance": "https://login.microsoftonline.com/",
       "TenantId": "<my-test-tenant>",
       "ClientId": "<my-agent-blueprint-id>",
       "Scopes": "access_agent",
       "ClientCredentials": [
         {
           "SourceType": "SignedAssertionFromManagedIdentity",
           "ManagedIdentityClientId": "managed-identity-client-id"  // Omit for system-assigned
         }
       ]
     },
   
     "DownstreamApis": {
       "agent-identity": {
         "BaseUrl": "https://graph.microsoft.com",
         "RelativePath": "/v1.0/users",
         "Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
         "RequestAppToken": true
       }
     }
   }
   

2. Добавление необходимых пакетов

   dotnet add package Microsoft.Identity.Web
   dotnet add package Microsoft.Identity.Web.AgentIdentities
   

3. Настройка служб.

   using Microsoft.Identity.Abstractions;
   using Microsoft.Identity.Web.Resource;
   using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;
   
   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
       .EnableTokenAcquisitionToCallDownstreamApi();
   builder.Services.AddAgentIdentities();
   builder.Services.AddInMemoryTokenCaches();
   
   var app = builder.Build();
   app.UseHttpsRedirection();
   app.UseAuthentication();
   app.UseAuthorization();
   app.Run();
   

4. Создайте конечную точку создания учетной записи пользователя агента.

   app.MapPost("/create-agent-id-user", async (HttpContext httpContext) =>
   {
       try
       {
           // Get the service to call the downstream API (preconfigured in the appsettings.json file)
           IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();
   
           var requestBody = new AgentIdUser
           {
               displayName = "my-agent-name",
               mailNickname = "my-agent-alias",
               userPrincipalName = "my-agent-email-address",
               accountEnabled = true,
               identityParentId = "<associated-agent-identity-id>"
           };
   
           // Call the downstream API (Graph) with a POST request to create an agent's user account
           var jsonResult = await downstreamApi.PostForAppAsync<AgentIdUser, AgentIdUser>(
               "agent-identity",
               requestBody
           );
   
           return Results.Json(jsonResult);
       }
       catch (Exception ex)
       {
           return ex.Message;
       }
   })
   

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

Предоставление согласия на удостоверение агента

Учетные записи пользователей агентов работают как любая другая учетная запись пользователя. Прежде чем запрашивать токены с помощью учетной записи пользователя агента, необходимо авторизовать идентификатор агента для действий от его имени. Вы можете авторизовать удостоверение агента с помощью авторизации admin или вручную создать oAuth2PermissionGrant с помощью Microsoft Graph или Microsoft Graph PowerShell.

Для Microsoft Graph запрос, как показано в следующем фрагменте кода:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Authorization: Bearer {token}
Content-Type: application/json

{
  "clientId": "{agent-identity-id}",
  "consentType": "Principal",
  "principalId": "{agent-id-user-object-id}",
  "resourceId": "{ms-graph-service-principal-object-id}",
  "scope": "Mail.Read"
}

Для Microsoft Graph PowerShell используйте следующий сценарий:

Connect-MgGraph -Scopes "DelegatedPermissionGrant.ReadWrite.All" -TenantId <your-test-tenant>

# Get the service principal for Microsoft Graph
$graphSp = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'"

# Get the service principal for your client app
$clientSp = Get-MgServicePrincipal -Filter "appId eq '{agent-identity-id}'"

# Create the delegated permission grant
New-MgOauth2PermissionGrant -BodyParameter @{
    clientId    = $clientSp.Id
    consentType = "Principal"
    principalId = "{agent-id-user-object-id}"
    resourceId  = $graphSp.Id
    scope       = "Mail.Read"
}

Запрос токена учетной записи пользователя агента

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

1. Получите токен в качестве шаблона идентификации агента.
2. Используйте этот токен для получения другого токена в качестве удостоверения агента.
3. Используйте оба предыдущих токена, чтобы получить новый токен для учетной записи пользователя агента.

REST

Сначала запросите маркер в качестве схемы удостоверения агента, как описано в разделе "Запрос маркера для схемы удостоверения агента". После получения токена приложения агента используйте его для запроса федеративного удостоверения личности (FIC) для идентификации агента.

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=api://AzureADTokenExchange/.default
&grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>

Возвращает маркер обмена (T2) для удостоверения агента. Используйте его в следующем запросе, чтобы получить делегированный маркер для учетной записи пользователя агента:

POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<agent-identity-id>
&scope=https://graph.microsoft.com/.default
&grant_type=user_fic
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<agent-blueprint-token>
&user_id=<agent-user-object-id>
&user_federated_identity_credential=<agent-identity-token>

Это дает делегированный токен доступа, позволяющий вызывать Microsoft Graph от имени учетной записи пользователя агента. Вместо идентификатора пользователя можно использовать user_id=<user-object-id>username=<UPN> .

Майкрософт. Identity.Web

Майкрософт.Identity.Web обрабатывает получение токена. Используйте шаблон .WithAgentUserIdentity() для запроса токенов доступа.

// In an API endpoint or service method where HttpContext is available
app.MapGet("/agent-user-token", async (HttpContext httpContext) =>
{
    IAuthorizationHeaderProvider authorizationHeaderProvider =
        httpContext.RequestServices.GetRequiredService<IAuthorizationHeaderProvider>();

    // Configure options for the agent's user account identity
    string agentIdentity = "agent-identity-id";
    string userId = "<user-object-id>";
    var options = new AuthorizationHeaderProviderOptions()
        .WithAgentUserIdentity(agentIdentity, userId);

    // Create a ClaimsPrincipal to enable token caching
    ClaimsPrincipal user = new ClaimsPrincipal();

    // Acquire a user token
    string authHeader = await authorizationHeaderProvider
        .CreateAuthorizationHeaderForUserAsync(
            scopes: ["https://graph.microsoft.com/.default"],
            options: options,
            user: user);

    return Results.Ok(authHeader);
});

Кроме того, вместо идентификатора объекта можно использовать основное имя пользователя учетной записи агента.

Связанный контент

• Атрибуты токена доступа к идентичности агента
• Получить токен при помощи Microsoft Entra SDK для идентификатора агента
• Справочник разрешений Microsoft Graph
• Разрешения и согласие в платформе идентификации Microsoft
• Процесс работы учетной записи пользователя в системах агентов
• Учетные записи пользователей агентов