Autenticar e adquirir tokens para agentes autónomos

Agentes autónomos realizam operações usando a sua própria identidade em vez de atuarem como delegados de um utilizador. Para operar de forma segura, um agente autónomo deve autenticar-se com o Microsoft Entra ID, obter tokens de acesso e obter as permissões apropriadas. Este artigo guia-o pelo processo de ponta a ponta:

Configurar as credenciais do cliente.
Peça um token para o modelo de identidade do agente.
Solicite um token de identidade de agente.
Conceder permissões de candidatura (consentimento do administrador).
(Opcional) Crie e autentique como conta de utilizador de um agente para recursos que requerem uma identidade de utilizador.

Observação

Este artigo aborda agentes autónomos que operam com a sua própria identidade. Se o seu agente precisar de agir em nome de um utilizador iniciado, veja Autenticar utilizadores e adquirir tokens para agentes interativos.

Pré-requisitos

Antes de implementar a autenticação de token de agente, certifique-se de que tem:

Um plano de identidade de agente.
A identidade de um agente. Precisas do ID de cliente com identidade do agente.
Compreensão dos protocolos OAuth em ID do Agente Microsoft Entra.

Para autorização de administrador, também precisa de:

Privilégios de administrador no seu tenant do Microsoft Entra ID.
Compreender as permissões específicas que o seu agente exige.

Para a autenticação da conta de utilizador do agente, também precisa de:

Compreensão das contas de utilizador dos agentes em ID do Agente Microsoft Entra.

Configure as credenciais dos seus clientes

Obtenha os dados da credencial do seu cliente. Isto pode ser o seu segredo de cliente, um certificado ou uma identidade gerida que está a usar como credencial de identidade federada.

Advertência

Os segredos do cliente não devem ser usados como credenciais do cliente em ambientes de produção para modelos de identidade de agentes por motivos de segurança. Em vez disso, utilize métodos de autenticação mais seguros, como credenciais de identidade federada (FIC) com identidades geridas ou certificados de cliente. Estes métodos proporcionam maior segurança ao eliminar a necessidade de armazenar segredos sensíveis diretamente na configuração da sua aplicação.

Microsoft Graph API
Microsoft.Identity.Web

Reúna a credencial que configurou no plano de identidade do agente. Precisa de um dos seguintes:

Identidade gerida (recomendado): O ID do cliente de identidade gerida e um token do Serviço de Metadados de Instância Azure (IMDS).
Certificado: A impressão digital do certificado ou ficheiro PFX.
Segredo do cliente (apenas desenvolvimento): O valor secreto.

Para produção, use uma identidade gerida como credencial de identidade federada:

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

Para desenvolvimento e testes locais, pode usar um cliente secreto em vez disso:

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

Solicitar um token para o modelo de identidade do agente

Ao solicitar o token para o modelo de identidade do agente, forneça o ID do cliente da identidade do agente no parâmetro fmi_path (Federated Managed Identity). Este parâmetro indica ao Microsoft Entra ID em que nome o blueprint está a atuar.

Ao usar um segredo de cliente durante o desenvolvimento local, forneça o client_secret parâmetro. Para certificados e identidades geridas, use client_assertion e client_assertion_type em vez disso.

Microsoft Graph API
Microsoft.Identity.Web

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>

Com Microsoft. Identity.Web, não precisas de pedir explicitamente um token para o blueprint de identidade do agente. Microsoft. Identity.Web faz isso por si.

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

Solicitar um token de identidade de agente

Microsoft Graph API
Microsoft.Identity.Web

Depois de tiveres o token blueprint de identidade do agente (T1), usa-o para pedir o token de identidade do agente.

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>

Microsoft. Identity.Web trata dos detalhes do protocolo de aquisição de tokens por si, desde que utilize o novo services.AddAgentIdentities() na sua coleção de serviços na inicialização da aplicação.

Inicialize a aplicação:

// 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();

Use o .WithAgentIdentity() padrão para solicitar tokens de acesso:

// 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);
});

Conceder permissões de aplicativo

Os agentes frequentemente precisam de tomar ações no Microsoft Graph e noutros serviços web que exigem uma permissão de aplicação do Microsoft Entra ID (representada como funções de app). Os agentes autónomos precisam de solicitar estas permissões a um administrador do Microsoft Entra ID.

Existem duas formas de conceder permissões de aplicação a um agente autónomo:

Um administrador pode criar um appRoleAssignment usando APIs Microsoft Graph ou PowerShell.
O agente pode encaminhar o administrador para uma página de consentimento usando uma URL de consentimento do administrador.

Criar uma atribuição de funções de aplicação através de APIs

Use os passos seguintes para obter uma atribuição de função na aplicação.

Obtenha um token de acesso com as permissões Application.Read.All da aplicação e AppRoleAssignment.ReadWrite.All.
Obtenha o ID do objeto da entidade principal do serviço de recurso ao qual está a tentar aceder. Por exemplo, para encontrar o ID do objeto principal do serviço Microsoft Graph:
1. Vai ao centro de administração Microsoft Entra.
2. Navegue até Entra ID -->Aplicações Empresariais
3. Filtrar por Tipo de Aplicação == Aplicações Microsoft
4. Pesquise por Microsoft Graph.
Obtenha o ID único da função da aplicação que pretende atribuir.

Criar a atribuição de funções na aplicação:

Microsoft Graph API
Microsoft Graph PowerShell

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>"
}

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

Solicitar autorização a um administrador de inquilinos

Para conceder permissões delegadas, construa o URL de autorização que é usado para alertar o administrador. O parâmetro de função é usado para especificar as permissões solicitadas pela aplicação.

Certifique-se de usar o ID do cliente de identidade do agente na solicitação seguinte.

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

As implementações do agente podem redirecionar o administrador para este URL de várias formas, como incluí-lo numa mensagem enviada ao administrador numa janela de chat. Quando o administrador é redirecionado para esta URL, é-lhe pedido que faça login e conceda consentimento às permissões especificadas no parâmetro de escopo. Neste momento, deve usar o URI de redirecionamento listado, que direciona o administrador para uma página em branco após conceder o consentimento.

Depois de conceder à sua candidatura as permissões necessárias, peça um novo token de acesso ao agente para que as permissões entrem em vigor.

Autenticar como conta de utilizador de um agente

Para além de operar apenas com tokens de aplicações, os agentes autónomos podem autenticar-se como a conta de utilizador de um agente. As contas de utilizador dos agentes são um tipo especial de conta de utilizador no Microsoft Entra, concebida especificamente para uso por agentes. São mais frequentemente usados quando um agente precisa de se ligar a sistemas que exigem a existência de uma conta de utilizador, por exemplo, uma caixa de correio, um canal do Teams ou outros recursos específicos do utilizador.

Cada identidade de agente só pode ter a conta de utilizador de um agente associado, e a conta de utilizador de cada agente só pode ser associada a uma única identidade de agente.

Obtenha autorização para criar contas de utilizador dos agentes

Para criar as contas de utilizador dos agentes, o blueprint de identidade do seu agente deve receber a permissão AgentIdUser.ReadWrite.IdentityParentedBy da aplicação no inquilino. Pode obter autorização de uma de duas formas:

Solicite autorização do agente. Certifique-se de usar o seu plano de identidade de agente como client_id, não como a identidade do agente.
Crie manualmente uma atribuição de função de aplicativo no locatário. Utilize o ID do objeto principal do serviço do modelo de identidade do agente como o valor principalId, e não o do ID da aplicação (cliente).

Se quiser usar um cliente diferente, em vez do modelo de identidade do agente, para criar as contas de utilizador dos agentes, esse cliente precisa de obter a permissão delegada ou a permissão de aplicação.

Crie a conta de utilizador de um agente

Crie a conta de utilizador de um agente usando o blueprint de identidade do seu agente ou outro cliente aprovado. A forma recomendada de criar a conta de utilizador de um agente é utilizando o modelo de identidade do seu agente. É necessário um token de acesso para criar a conta de utilizador de um agente.

REST
Microsoft.Identity.Web

Depois de ter um token de acesso com a permissão necessária, faça o seguinte pedido:

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
}

Para usar Microsoft.Identity.Web para criar a conta de utilizador de um agente, siga estes passos:

Adicione o seguinte ao seu ficheiro de configuração:

{
  "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
    }
  }
}

Adicionar pacotes necessários

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

Configurar serviços.

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();

Crie o endpoint de criação da conta de utilizador do agente.

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;
    }
})

Depois de criares a conta de utilizador do teu agente, não precisas de configurar mais nada. Estas contas não têm credenciais e só podem ser autenticadas usando o protocolo descrito nas secções seguintes.

As contas de utilizador dos agentes comportam-se como qualquer outra conta de utilizador. Antes de poderes pedir tokens usando a conta de utilizador do teu agente, precisas de autorizar a identidade do agente para agir em seu nome. Pode autorizar a identidade do agente através da autorização de administrador ou criar manualmente um utilizando o Microsoft Graph ou o Microsoft Graph PowerShell.

Para o Microsoft Graph, a sua solicitação corresponde ao seguinte exemplo:

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"
}

Para o Microsoft Graph PowerShell, use o seguinte script:

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"
}

Solicitar o token da conta de utilizador de um agente

Para autenticar a conta de utilizador de um agente, precisa de seguir um processo de três passos:

Obtenha um token como modelo de identidade do agente.
Usa esse token para obter outro token como identidade do agente.
Use ambos os tokens anteriores para obter outro token como conta de utilizador do agente.

REST
Microsoft.Identity.Web

Primeiro, solicite um token como modelo de identidade do agente, conforme descrito em Solicitar um token para o modelo de identidade do agente. Depois de ter o seu token de aplicação de agente, use-o para solicitar uma Credencial de Identidade Federada (FIC) para a identidade do seu agente:

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>

Isto devolve um token de troca (T2) para a identidade do agente. Use-o no próximo pedido para obter um token delegado para a conta de utilizador do agente:

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>

Isto dá-lhe um token de acesso delegado que pode usar para chamar o Microsoft Graph como conta de utilizador do seu agente. Pode usar user_id=<user-object-id> em vez de username=<UPN> para o identificador de utilizador.

Microsoft.Identity.Web trata da aquisição de tokens por si. Use o .WithAgentUserIdentity() padrão para pedir tokens de acesso.

// 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);
});

Também pode usar o nome principal da conta de utilizador do agente em vez do ID do objeto.

Comentários

Esta página foi útil?

Last updated on 2026-04-09