Partilhar via

Crie um plano de identidade de agente

Um esquema de identidade de agente é usado para criar identidades de agentes e tokens de requisição usando essas identidades. Este guia guia-o na criação de um blueprint de identidade de agente usando a Microsoft Graph REST API e o Microsoft Graph PowerShell.

Pré-requisitos

Antes de criar o seu plano de identidade de agente, certifique-se de que tem:

  • Compreender os planos de identidade do agente
  • Administrador de Funções Privilegiadas necessário para conceder permissões
  • Um dos seguintes papéis é necessário para criar um blueprint: Desenvolvedor de ID de Agente ou Administrador de ID de Agente. Prefiro a função de Administrador de ID de Agente.

Autorizar um cliente a criar esquemas de identidade de agente

Neste artigo, utiliza o Microsoft Graph PowerShell ou outro cliente para criar o blueprint da identidade do seu agente. Deve autorizar este cliente a criar um modelo de identidade de agente. O cliente requer uma das seguintes permissões do Microsoft Graph:

  • AgentIdentityBlueprint.Create (permissão delegada)
  • AgentIdentityBlueprint.Create (permissão de aplicação)

Apenas um Administrador Global ou um Administrador de Funções Privilegiadas pode conceder estas permissões ao cliente. Para conceder estas permissões, um administrador pode:

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

Crie um plano de identidade de agente

Criar um blueprint funcional de identidade de agente no seu tenant requer dois passos:

  1. Crie um AgentIdentityBlueprint no inquilino.
  2. Crie um AgentIdentityBlueprintPrincipal no inquilino.

O principal criado neste 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 o seguinte pedido.

Sugestão

Inclua sempre 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 esquema de identidade de agente, registe-o appId para os próximos passos no guia. De seguida, crie um princípio de serviço para o seu plano de identidade do agente:

Para criar um service principal, primeiro precisa obter um token de acesso com a permissão AgentIdentityBlueprint.Create. Depois de ter um token de acesso, faça o seguinte pedido:

Sugestão

Inclua sempre 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 plano de identidade do agente

Para solicitar tokens de acesso usando o plano de identidade do agente, deve adicionar uma credencial de cliente. Recomendamos a utilização de uma identidade gerida como credencial federada de identidade para implementações em produção. Para desenvolvimento e testes locais, use um segredo do cliente.

Adicione uma identidade gerida como credencial usando o seguinte pedido:

Para enviar este pedido, primeiro precisa de 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 inquilinos, outros tipos de credenciais de aplicação, incluindo keyCredentials, passwordCredentials, e trustedSubjectNameAndIssuers também são suportadas. Este tipo de credenciais não é recomendado para produção, mas pode ser conveniente para desenvolvimento e testes locais. Para adicionar uma credencial de palavra-passe:

Para enviar este pedido, primeiro precisa de 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 guardar de forma segura o passwordCredential valor gerado. Não pode ser visualizado após a criação inicial. Também pode usar certificados de cliente como credenciais; ver Adicionar uma credencial de certificado.

Configurar identificador, URI e âmbito

Para receber requisições de utilizadores e outros agentes, é necessário definir um URI identificador e um âmbito OAuth para o modelo de identidade do agente.

Para enviar este pedido, primeiro precisa de 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 eliminar identidades de agentes

  • Last updated on