Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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.Allde Microsoft Graph delegadas eAgentIdentity.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
webURI 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.
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.Em permissões de API, adicione estas permissões Microsoft Graph > Delegadas:
-
AgentIdentityBlueprint.ReadWrite.All. -
AgentIdentity.ReadWrite.All.
-
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.
Instale o módulo de autenticação do Microsoft Graph PowerShell e entre com o aplicativo de gerenciamento.
Connect-MgGraphabre 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, ScopesConfirme que
Account,TenantIdeClientIdidentificam o operador, o locatário e o aplicativo de gerenciamento pretendidos, e queScopesinclui 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.
Crie o blueprint com
isSingleInstancedefinido comotrue. Substitua<sponsor-user-object-id>pela ID do objeto do patrocinador. É necessário um patrocinador; a atribuição do proprietário é opcional.Mantenha
isSingleInstance: truepara 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>" ] }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.
Crie a ID do agente. Defina
agentIdentityBlueprintIdcomo a ID do objeto do blueprint, não suaappId.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>" ] }Salve a
idda identidade da resposta201 Created. Essa é a ID do objeto da identidade do agente, não a ID do objeto blueprint ou a ID do cliente OAuth.Leia a identidade para verificar o resultado:
GET https://graph.microsoft.com/beta/servicePrincipals/<agent-identity-object-id>?$select=id,appId,displayName,agentIdentityBlueprintId,instanceModeVerifique os valores retornados:
Property Valor esperado @odata.type#microsoft.graph.agentIdentity.appIdO appIddo blueprint.agentIdentityBlueprintIdO ID do objeto do blueprint. instanceModesingleInstance.
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.
Leia a configuração de redirecionamento atual:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,web,publicClientAtualize 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.
Leia a coleção atual de certificados:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,keyCredentialsAdicione 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.
Leia as declarações atuais:
GET https://graph.microsoft.com/beta/applications/<blueprint-object-id>?$select=id,appId,requiredResourceAccessAdicione 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:
- Autenticar usuários em uma API de agente ASP.NET Core.
- Chame uma API personalizada como um agente com ASP.NET Core.
- Configure o sidecar do SDK de autenticação.
- Fazer login de usuários a partir de um agente em um dispositivo de usuário final.
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.