Compartilhar via

Criar um plano de identidade do agente

Um plano de identidade do agente é usado para criar identidades de agente e solicitar tokens com essas identidades de agente. Este guia explica como criar um blueprint de identidade de agente usando a API REST do Microsoft Graph e o Microsoft Graph PowerShell.

Pré-requisitos

Antes de criar o blueprint de identidade do agente, verifique se você tem:

  • entender os planos de identidade do agente
  • Administrador de Funções Privilegiadas é necessário para conceder permissões
  • Uma das seguintes funções necessárias para criar um blueprint: Desenvolvedor de ID do Agente ou Administrador de ID do Agente. Prefira a função de administrador de ID do agente.

Autorizar um cliente a criar modelos de identidade de agente

Neste artigo, você usará o Microsoft Graph PowerShell ou outro cliente para criar o blueprint de identidade do agente. Você deve autorizar este cliente a criar um modelo de identidade do agente. O cliente requer uma das seguintes permissões do Microsoft Graph:

  • AgentIdentityBlueprint.Create (permissão delegada)
  • AgentIdentityBlueprint.Create (permissão do aplicativo)

Somente um Administrador Global ou Administrador de Funções Com Privilégios pode conceder essas permissões ao cliente. Para conceder essas permissões, um administrador pode:

  • Use o comando Connect-MgGraph.
  • Execute um script para criar um oAuth2PermissionGrant ou appRoleAssignment no inquilino.

Criar um plano de identidade do agente

A criação de um blueprint de identidade de agente funcional em seu locatário requer duas etapas:

  1. Crie um AgentIdentityBlueprint locatário.
  2. Crie um AgentIdentityBlueprintPrincipal locatário.

O principal criado nesse caso é diferente da identidade do agente usada pelo agente.

Primeiro, obtenha um token de acesso com a permissão AgentIdentityBlueprint.Create. Depois de ter um token de acesso, faça a solicitação a seguir.

Dica

Sempre inclua o cabeçalho OData-Version ao usar @odata.type.

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

{
  "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
  "displayName": "My Agent Identity Blueprint",
  "sponsors@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/<id>",
  ],
	"owners@odata.bind": [
	  "https://graph.microsoft.com/v1.0/users/<id>"
	]
}

Depois de criar um modelo de identidade do agente, registre o appId para utilizá-lo nas próximas etapas do guia. Em seguida, crie um principal de serviço para o blueprint de identidade do seu agente:

Para criar a entidade de serviço (service principal), primeiro você precisa obter um token de acesso com a permissão AgentIdentityBlueprint.Create. Depois de ter um token de acesso, faça a seguinte solicitação:

Dica

Sempre inclua o cabeçalho OData-Version ao usar @odata.type.

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

{
  "appId": "<agent-blueprint-app-id>"
}

Configurar credenciais para o modelo de identidade do agente

Para solicitar tokens de acesso usando o modelo de identidade do agente, você deve adicionar uma informação de autenticação de cliente. É recomendável usar uma identidade gerenciada como uma credencial de identidade federada para implantações de produção. Para desenvolvimento e teste local, use um segredo do cliente.

Adicione uma identidade gerenciada como uma credencial usando a seguinte solicitação:

Para enviar essa solicitação, primeiro você precisa obter um token de acesso com a permissão AgentIdentityBlueprint.AddRemoveCreds.All.

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/federatedIdentityCredentials
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "name": "my-msi",
    "issuer": "https://login.microsoftonline.com/<my-test-tenant-id>/v2.0",
    "subject": "<msi-principal-id>",
    "audiences": [
        "api://AzureADTokenExchange"
    ]
}

Em alguns locatários, outros tipos de credenciais de aplicativo, incluindo keyCredentials, passwordCredentialse trustedSubjectNameAndIssuers também têm suporte. Esses tipos de credenciais não são recomendados para produção, mas podem ser convenientes para testes e desenvolvimento locais. Para adicionar uma credencial de senha:

Para enviar essa solicitação, primeiro você precisa obter um token de acesso com a permissão delegada AgentIdentityBlueprint.AddRemoveCreds.All

POST https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>/addPassword
Content-Type: application/json
Authorization: Bearer <token>

{
  "passwordCredential": {
    "displayName": "My Secret",
    "endDateTime": "2026-08-05T23:59:59Z"
  }
}

Certifique-se de armazenar com segurança o passwordCredential valor gerado. Ele não pode ser exibido após a criação inicial. Você também pode usar certificados de cliente como credenciais; consulte Adicionar uma credencial de certificado.

Configurar o URI do identificador e o seu escopo

Para receber solicitações de entrada de usuários e outros agentes, você precisa definir uma URI de identificação e um escopo OAuth para seu blueprint de identidade do agente.

Para enviar essa solicitação, primeiro você precisa obter um token de acesso com a permissão AgentIdentityBlueprint.ReadWrite.All.

PATCH https://graph.microsoft.com/beta/applications/<agent-blueprint-object-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>

{
    "identifierUris": ["api://<agent-blueprint-id>"],
    "api": {
      "oauth2PermissionScopes": [
        {
          "adminConsentDescription": "Allow the application to access the agent on behalf of the signed-in user.",
          "adminConsentDisplayName": "Access agent",
          "id": "<generate-a-guid>",
          "isEnabled": true,
          "type": "User",
          "value": "access_agent"
        }
      ]
  }
}

Conteúdo relacionado

Criar e excluir identidades do agente

  • Last updated on