Criar uma identidade para seu agente com Microsoft Graph (versão prévia)

Registre seu agente para que ele possa se autenticar com Microsoft Entra ID e solicitar acesso às APIs. Essa configuração cria uma única identidade para o agente, compartilhada por suas instalações ou réplicas.

Este procedimento usa Microsoft Graph beta. Para um agente de nuvem, configure uma credencial para seu runtime. Para um agente instalado em um dispositivo de usuário final, use a configuração de redirecionamento de cliente público sem uma credencial. Seu tutorial de chamada identifica as seções necessárias.

Importante

As identidades de agente de instância única estão em versão prévia. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou ter recursos restritos. Para obter mais informações, consulte Os Termos de Licença Universal para Serviços Online.

Prerequisites

  • Um tenant do Microsoft Entra habilitado para provisionamento de instância única no Microsoft Graph. Confirme a disponibilidade de visualização e a habilitação do locatário com seu representante do Microsoft antes de começar. Para solicitar tokens após a instalação, confirme também se a autenticação de instância única está habilitada; O provisionamento e a autenticação são habilitados separadamente.
  • Uma conta autorizada a criar e atualizar blueprints de identidade do agente e identidades de agente, como um Administrador de ID do Agente.
  • Um aplicativo de gerenciamento público de locatário único separado com consentimento do administrador para as permissões AgentIdentityBlueprint.ReadWrite.All de Microsoft Graph delegadas e AgentIdentity.ReadWrite.Allou permissão para configurar o cliente de gerenciamento.
  • Um administrador que pode conceder consentimento às permissões do Graph do aplicativo de gerenciamento.
  • O identificador de objeto de um usuário que pode ser atribuído como o patrocinador do blueprint. Os exemplos também atribuem esse usuário como proprietário.
  • Para logon interativo, um URI de redirecionamento apropriado para o tipo de cliente. Para consentimento do administrador baseado em navegador, um web URI de redirecionamento, mesmo que o agente use apenas as credenciais do cliente no runtime.
  • Para testes de cliente confidencial local, um certificado X.509 e um armazenamento seguro para sua chave privada. Um agente hospedado no Azure pode usar, em vez disso, uma credencial federada de identidade gerenciada. Um cliente somente público não precisa de uma credencial.
  • Para acessar a API, são necessários a ID do cliente do aplicativo de recurso e as IDs das permissões delegadas ou das funções de aplicativo de que o agente precisa.

Execute os exemplos HTTP por meio Microsoft Graph PowerShell, conforme descrito abaixo, ou use um cliente REST que possa enviar cabeçalhos e corpos de solicitação JSON. Em um cliente REST, envie o token de gerenciamento como um token bearer no cabeçalho Authorization de cada solicitação do Graph. Nunca use o token de acesso de runtime do agente para solicitações de gerenciamento.

Confirmar a transferência do administrador

Antes de criar objetos, concorde com a transferência de responsabilidade a seguir. O consentimento do gerenciamento e o consentimento da API de runtime do agente são aprovações separadas.

Quem Action Pronto quando
Administrador de locatário e representante da Microsoft. Confirme se o provisionamento em versão prévia e a autenticação estão habilitados. O tenant dá suporte a solicitações de registro e token para essa configuração.
Administrador autorizado. Aprove as duas permissões do Graph do cliente de gerenciamento listadas acima. O operador pode entrar nesse cliente com os dois escopos consentidos.
Desenvolvedor ou operador autorizado. Conclua as etapas de registro abaixo. A ID do objeto blueprint, a ID do objeto de identidade do agente e a ID do cliente compartilhado são registradas.
Proprietário da API e administrador de consentimento. Forneça os identificadores de API e aprove as permissões exigidas pelo tutorial de chamada. As concessões de runtime necessárias são verificadas antes da primeira chamada à API.

Envie ao administrador sua ID de locatário, ID do cliente de gerenciamento e permissões de API solicitadas. Mantenha a planilha do identificador junto com as etapas de instalação.

Se você estiver seguindo um tutorial HTTPS local, confirme também se o certificado HTTPS de desenvolvimento é confiável em seu computador antes da entrada do navegador. Siga o processo de confiança da sua organização em vez de desabilitar a validação do TLS.

Configurar o cliente de gerenciamento

O cliente de gerenciamento autentica um administrador ou operador autorizado para criar o registro do agente. É separado da identidade de runtime do agente. Um login existente no CLI do Azure não estabelece esse contexto de gerenciamento.

  1. Registre um aplicativo no mesmo locatário. Selecione Contas somente neste diretório organizacional. Em Autenticação, adicione a plataforma de aplicativos móveis e de área de trabalho com o URI http://localhostde redirecionamento.

  2. Em permissões de API, adicione estas permissões Microsoft Graph > Delegadas:

    • AgentIdentityBlueprint.ReadWrite.All.
    • AgentIdentity.ReadWrite.All.
  3. Peça a um administrador autorizado que conceda consentimento a essas permissões. Para obter informações sobre o consentimento do administrador, consulte Permissões e consentimento no plataforma de identidade da Microsoft.

  4. Instale o módulo de autenticação do Microsoft Graph PowerShell e entre com o aplicativo de gerenciamento. Connect-MgGraph abre um navegador para o usuário conectado:

    Install-Module Microsoft.Graph.Authentication -Scope CurrentUser
    
    Connect-MgGraph `
      -ClientId "<management-app-client-id>" `
      -TenantId "<tenant-id>" `
      -Scopes "AgentIdentityBlueprint.ReadWrite.All", "AgentIdentity.ReadWrite.All" `
      -ContextScope Process
    
    $context = Get-MgContext
    if (-not $context -or -not $context.Account) {
        throw "Microsoft Graph sign-in didn't establish a delegated management context. Stop before creating objects."
    }
    $context | Select-Object Account, TenantId, ClientId, Scopes
    

    Confirme que Account, TenantId e ClientId identificam o operador, o locatário e o aplicativo de gerenciamento pretendidos, e que Scopes inclui ambas as permissões. Se um escopo estiver ausente ou o consentimento for solicitado novamente, pare e tenha um administrador autorizado para verificar o registro e o consentimento do aplicativo antes de continuar.

No Windows, se Connect-MgGraph falhar antes de entrar com é necessário configurar um identificador de janela, use a opção de entrada do navegador documentada para seu cliente de gerenciamento personalizado:

Set-MgGraphOption -DisableLoginByWAM $true

Execute o mesmo Connect-MgGraph comando novamente. Isso altera a interface do usuário de autenticação, não os requisitos de acesso do locatário; conclua a entrada como o operador autorizado e não ignore uma negação de conformidade. A configuração persiste entre as sessões do PowerShell. Se o WAM tiver sido habilitado antes desta alteração, restaure-o com Set-MgGraphOption -DisableLoginByWAM $false quando terminar.

Use Invoke-MgGraphRequest para executar os exemplos HTTP sem copiar ou exibir um token de acesso. Por exemplo, copie o corpo JSON de Criar o blueprint em $body, substituindo o espaço reservado do patrocinador:

$body = @'
<JSON-request-body>
'@

$blueprint = Invoke-MgGraphRequest -Method POST `
    -Uri "https://graph.microsoft.com/beta/applications" `
    -Headers @{ "OData-Version" = "4.0" } `
    -ContentType "application/json" -Body $body

$blueprintObjectId = $blueprint.id
$agentClientId = $blueprint.appId

Para solicitações posteriores, use o método, o URI completo, os cabeçalhos e o corpo JSON mostrados em cada exemplo HTTP. Omita -Body em uma solicitação GET. O módulo fornece o cabeçalho de autorização. Para obter a sintaxe de comando, consulte Invoke-MgGraphRequest.

Se o registro ou consentimento forem negados, peça ao administrador do locatário para concluir essa configuração. Não conceda essas permissões de gerenciamento ao agente para contornar um erro de autorização.

Criar o blueprint

O blueprint é o registro que contém as credenciais e as configurações de autenticação do agente.

  1. Crie o blueprint com isSingleInstance definido como true. Substitua <sponsor-user-object-id> pela ID do objeto do patrocinador. É necessário um patrocinador; a atribuição do proprietário é opcional.

    Mantenha isSingleInstance: true para este tutorial: ele cria uma identidade para o agente, incluindo suas instalações ou réplicas. Essa propriedade não pode ser alterada após a criação.

    POST https://graph.microsoft.com/beta/applications
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
      "displayName": "Contoso Operations Agent",
      "signInAudience": "AzureADMyOrg",
      "isSingleInstance": true,
      "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ],
      "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ]
    }
    
  2. Da resposta 201 Created, salve os seguintes valores:

    • id: O ID do objeto do blueprint, usado para referenciá-lo no Microsoft Graph.
    • appId: o ID do aplicativo (cliente), usado em solicitações OAuth.

O exemplo cria um blueprint de locatário único com signInAudience definido como AzureADMyOrg.

Provisionar a identidade do agente

Crie a identidade separadamente de seu registro de blueprint. Siga a solicitação abaixo diretamente; essa configuração não requer um principal de blueprint.

  1. Crie a ID do agente. Defina agentIdentityBlueprintId como a ID do objeto do blueprint, não sua appId.

    POST https://graph.microsoft.com/beta/servicePrincipals/microsoft.graph.agentIdentity
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "displayName": "Contoso Operations Agent",
      "agentIdentityBlueprintId": "<blueprint-object-id>",
      "sponsors@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/<sponsor-user-object-id>"
      ]
    }
    
  2. Salve a id da identidade da resposta 201 Created. Essa é a ID do objeto da identidade do agente, não a ID do objeto blueprint ou a ID do cliente OAuth.

  3. Leia a identidade para verificar o resultado:

    GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceMode
    

    Verifique os valores retornados:

    Property Valor esperado
    @odata.type #microsoft.graph.agentIdentity.
    appId O appId do blueprint.
    agentIdentityBlueprintId O ID do objeto do blueprint.
    instanceMode singleInstance.

Não provisione uma nova identidade para cada instalação, processo ou sessão do usuário. Eles usam o mesmo ID do cliente.

Configurar URIs de redirecionamento

Para o fluxo de código de autorização, registre o URI de redirecionamento na plataforma que corresponde ao cliente. Um cliente confidencial usa web; um cliente público usa publicClient.

O procedimento de consentimento do administrador baseado em navegador também requer um web URI de redirecionamento, mesmo para um agente que usa apenas as credenciais do cliente no runtime. O redirecionamento manipula o retorno de chamada de consentimento, não a solicitação de token de credenciais do cliente. Ignore esta seção somente se nem o fluxo de código de autorização nem o consentimento do administrador baseado em navegador forem necessários.

  1. Leia a configuração de redirecionamento atual:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClient
    
  2. Atualize a coleção de redirecionamento apropriada. O exemplo a seguir mostra os dois tipos de cliente; inclua apenas as plataformas que seu agente usa. Mantenha todas as URIs de redirecionamento existentes que ainda são necessárias.

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "web": {
        "redirectUris": [
          "https://agent.contoso.com/signin"
        ]
      },
      "publicClient": {
        "redirectUris": [
          "http://localhost"
        ]
      }
    }
    

    Uma atualização bem-sucedida retorna 204 No Content. Coleções de URI de redirecionamento são substituídas, não acrescentadas. Não substitua uma configuração existente por este exemplo sem preservar suas URIs.

O mesmo blueprint pode registrar ambas as plataformas. Cada solicitação de autorização usa o URI de redirecionamento para seu tipo de cliente. Um cliente público não envia uma credencial, mesmo que um componente confidencial use um certificado no mesmo blueprint. Não altere isFallbackPublicClient para alternar entre esses cenários de código de autorização.

Adicionar um certificado para clientes confidenciais

Para testes de cliente confidencial local, registre apenas o certificado público no blueprint. O runtime mantém a chave privada para autenticação.

Ignore esta seção para um cliente público apenas. Para um agente hospedado no Azure usando federação de identidade gerenciada, configure a credencial federada e continue com Declarar as permissões da API.

Para um computador de desenvolvimento Windows, você pode criar um certificado autoassinado e exportar seu certificado público e PFX protegido por senha. Mantenha o PFX fora da árvore de origem. Use o certificado público DER codificado em Base64 para key abaixo, não o PFX ou o cabeçalho e o rodapé de um arquivo PEM. Por exemplo:

$publicCertificate = Get-PfxCertificate -FilePath "<absolute-path-to-public-cer>"
$publicCertificateBase64 = [Convert]::ToBase64String($publicCertificate.RawData)

$publicCertificateBase64 Cole na solicitação de registro. O valor público não é uma credencial; o PFX e sua senha são. Para desenvolvimento ou produção não Windows, use o processo de emissão de certificados e armazenamento de chaves privadas da sua organização.

  1. Leia a coleção atual de certificados:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentials
    
  2. Adicione seu certificado público, mantendo quaisquer credenciais de chave existentes que ainda são necessárias. A solicitação a seguir mostra um registro inicial sem certificados existentes:

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "keyCredentials": [
        {
          "type": "AsymmetricX509Cert",
          "usage": "Verify",
          "key": "<base64-encoded-DER-certificate>",
          "displayName": "Contoso Operations Agent certificate"
        }
      ]
    }
    

    Uma atualização bem-sucedida retorna 204 No Content. Nunca carregue a chave privada ou distribua-a com um cliente público.

Para obter diretrizes sobre formato de certificado e declaração de cliente, consulte plataforma de identidade da Microsoft credenciais de certificado.

Declarar as permissões de API

Declare apenas as permissões de que o agente precisa. Use Scope para uma permissão delegada e Role para uma permissão de aplicativo. Os valores em resourceAccess são IDs de permissão expostos pelo aplicativo de recurso, não nomes de permissões.

  1. Leia as declarações atuais:

    GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccess
    
  2. Adicione as entradas de recurso e permissão, preservando declarações existentes que ainda são necessárias. O exemplo mostra uma permissão delegada e uma permissão de aplicativo; remova uma das entradas se o agente não precisar dela.

    PATCH https://graph.microsoft.com/beta/applications/<blueprint-object-id>
    OData-Version: 4.0
    Content-Type: application/json
    
    {
      "@odata.type": "#microsoft.graph.agentIdentityBlueprint",
      "requiredResourceAccess": [
        {
          "resourceAppId": "<resource-app-id>",
          "resourceAccess": [
            {
              "id": "<delegated-permission-id>",
              "type": "Scope"
            },
            {
              "id": "<app-role-id>",
              "type": "Role"
            }
          ]
        }
      ]
    }
    

    Uma atualização bem-sucedida retorna 204 No Content.

Essas declarações não concedem acesso. O consentimento do usuário ou administrador concede permissões delegadas e um administrador concede permissões de aplicativo. As permissões concedidas pertencem diretamente à ID do Agente.

Se o agente também receber chamadas de um aplicativo front-end, exponha um URI do identificador e o escopo delegado no blueprint. Preserve quaisquer escopos de API existentes e defina requestedAccessTokenVersion como 2. O front-end solicita esse escopo para obter um token cujo público é o ID do cliente compartilhado.

Solucionar problemas de solicitações do Graph

Se uma solicitação falhar, inspecione o status HTTP e a resposta de erro do Graph antes de alterar as permissões ou tentar novamente a operação.

Resposta Verificação
400 Bad Request Ler error.code e error.message. Verifique o esquema de solicitação do ponto de extremidade, as referências de patrocinador necessárias, as IDs de objeto e os valores de propriedade necessários.
401 Unauthorized Adquira um token de acesso válido para Microsoft Graph e envie-o no Authorization cabeçalho.
403 Forbidden Confirme se o aplicativo de gerenciamento tem as permissões delegadas necessárias e o consentimento do administrador, se o usuário conectado está autorizado para a operação e o locatário está habilitado para a visualização.

Para obter detalhes, consulte respostas de erro do Microsoft Graph. Quando você entra em contato com um administrador ou suporte da Microsoft, inclua o status HTTP, o código de erro e request-id o cabeçalho de resposta. Não inclua tokens de acesso ou outras credenciais.

Próxima etapa

Retorne ao tutorial que trouxe você aqui:

Para obter solicitações OAuth diretas e o modelo de identidade por trás dessa configuração, consulte Autenticar a identidade do agente e modos de instância de blueprint de identidade do agente.