Registro personalizado de aplicativo cliente para o CLI do Agent 365

A CLI do Agent 365 precisa de um registro de aplicativo cliente personalizado no tenant do Microsoft Entra ID para autenticar e gerenciar modelos de identidade do agente.

Este artigo divide o processo em quatro etapas principais:

1. Aplicação de registro
2. Defina o URI de Redirecionamento
3. Copiar ID do Aplicativo (cliente)
4. Configurar permissões de APIrequer privilégios de administrador

Se tiver problemas, consulte a seção de Solução de Problemas .

Pré-requisitos

Antes de começar, verifique se você tem acesso ao centro de administração Microsoft Entra e, se necessário, a uma das funções de administrador necessárias para conceder consentimento.

Para registrar o aplicativo

Por padrão, qualquer usuário no locatário pode registrar aplicativos no Centro de administração do Microsoft Entra. No entanto, administradores de inquilinos podem restringir essa capacidade. Se você não puder registrar seu aplicativo, entre em contato com seu administrador.

Para adicionar permissões e conceder consentimento

Você precisa de uma dessas funções administrativas para 4. Configurar permissões de API.

• Administrador de Aplicativos: Recomendado - pode gerenciar registros de aplicativos e conceder consentimento
• Administrador de Aplicações em Nuvem: Pode gerenciar registros de aplicativos e conceder consentimento
• Administrador Global: Tem todas as permissões, mas não é obrigatório

Registro de Aplicativo

Essas instruções resumem todas as instruções para criar um cadastro de aplicativo.

1. Vá para centro de administração do Microsoft Entra

2. Selecione Registros de aplicativo

3. Selecione Novo registro

4. Digite:

   • Nome: Insira um nome significativo para seu app, como my-agent-app. Os usuários do aplicativo veem esse nome e você pode alterá-lo a qualquer momento. Você pode ter vários registros de aplicativo com o mesmo nome.

     Dica

     Se você quiser usar o fluxo sem configuração a365 setup all --agent-name, nomeie o aplicativo exatamente Agent 365 CLI. A CLI procura o aplicativo cliente por esse nome de exibição conhecido automaticamente, portanto, você não precisa copiar a ID do cliente em um arquivo de configuração.

   • Tipos de conta suportados: Contas apenas neste diretório organizacional (Inquilino único)

   • Redirecionar URI: Selecione cliente público/nativo (móvel e desktop) e entre http://localhost:8400/

5. Escolha Registrar

A CLI requer três URIs de redirecionamento no total. A CLI adiciona automaticamente todos os que estão ausentes quando você executa a365 setup requirements:

Veja o que a CLI configura automaticamente para obter detalhes.

2. Definir o URI de redirecionamento

1. Vá até Visão Geral e copie o valor ID de Aplicação (cliente).
2. Vá em Autenticação (prévia) e selecione Adicionar URI de Redirecionamento.
3. Selecione aplicativos móveis e desktop e defina o valor para ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, onde {client-id} está o valor da aplicação (ID do cliente) que você copiou.
4. Selecione Configurar para adicionar o valor.

3. Copiar ID do Aplicativo (cliente)

Na página de Visão Geral do app, copie o ID do aplicativo (cliente) no formato GUID. Você usa esse valor ao executar a365 setup all ou ao criar a365.config.jsonmanualmente.

4. Configurar permissões de API

Escolha o método apropriado:

• Option A: Use o centro de administração do Microsoft Entra para todas as permissões (se as permissões beta estiverem visíveis)
• Option B: use o Microsoft API do Graph para adicionar todas as permissões (recomendado se as permissões beta não estiverem visíveis)

Opção A: centro de administração do Microsoft Entra (Método Standard)

Use esse método se você puder ver permissões beta em seu locatário.

1. No registro do aplicativo, acesse as permissões de API.

2. Selecione Adicionar uma permissão>Microsoft Graph>Permissões delegadas.

   Importante

   Você deve usar permissões delegadas (não permissões de aplicativo). O CLI autentica de forma interativa – você faz login e ele age em seu nome. Para saber mais, consulte Tipo de permissão incorreto.

3. Adicione estas treze permissões uma a uma:

   Permissão	Purpose
   AgentIdentityBlueprintPrincipal.Create	Criar o principal de serviço do Blueprint do agente (API beta)
   AgentIdentityBlueprint.ReadWrite.All	Gerenciar configurações do Agent Blueprint (API beta)
   AgentIdentityBlueprint.UpdateAuthProperties.All	Atualizar permissões herdáveis do Agent Blueprint (API beta)
   AgentIdentityBlueprint.AddRemoveCreds.All	Adicionar ou remover segredos do cliente e credenciais de identidade federadas em blueprints (API beta)
   AgentIdentityBlueprint.DeleteRestore.All	Excluir aplicações do Agent Blueprint durante o cleanup (API beta)
   AgentInstance.ReadWrite.All	Registrar e gerenciar instâncias de agente por meio da API do Registro do Agente (API beta)
   AgentIdentity.Create.All	Criar identidades de agente a partir de blueprints (API beta)
   AgentIdentity.DeleteRestore.All	Excluir entidades de serviço de identidade do agente durante a limpeza (API beta)
   AgentIdentity.Read.All	Ler dados de identidade do agente (API beta)
   AgentRegistration.ReadWrite.All	Ler e gravar todos os registros do agente
   DelegatedPermissionGrant.ReadWrite.All	Conceder permissões para projetos de agentes
   Directory.Read.All	Leia os dados do diretório para validação
   User.Read	Ler o perfil de usuário conectado para atribuição de proprietário do blueprint

   Note

   AgentRegistration.ReadWrite.All é necessário para a instalação do agente. O validador da CLI verifica essa permissão explicitamente. Ele deve estar presente no registro do aplicativo e ter o consentimento do administrador concedido.

   Para cada permissão:

   • Na caixa de busca, digite o nome da permissão (por exemplo, AgentIdentityBlueprint.ReadWrite.All).
   • Marque a caixa de seleção ao lado da permissão.
   • Selecione Adicionar Permissões.
   • Repita o processo para todas as treze permissões.

4. Selecione Conceder consentimento administrativo para [Seu Inquilino].

   • Por que isso é necessário? Projetos de identidade do agente são recursos abrangentes para o locatário que vários usuários e aplicativos podem referenciar. Sem consentimento de todo o inquilino, a CLI falha durante a autenticação.
   • E se falhar? Você precisa de Administrador de Aplicações, Administrador de Aplicações em Nuvem ou Administrador Global. Peça ajuda ao administrador do locatário.

5. Verifique se todas as permissões mostram marcas verdes em Status.

Se as permissões beta (AgentIdentityBlueprint.*) não estiverem visíveis, prossiga para a Opção B.

Opção B: Microsoft API do Graph (para permissões beta)

Use este método se a central de administração do Microsoft Entra não mostrar permissões AgentIdentityBlueprint.*.

1. Abra o Explorador de Grafos.

2. Faça login com sua conta de administrador (Administrador de Aplicações ou Administrador de Aplicações em Nuvem).

3. Conceda consentimento do administrador usando API do Graph. Para concluir esta etapa, você precisa:

   • ID do principal de serviço Você precisa de um SP_OBJECT_ID valor variável.
   • ID de recurso do grafo. Você precisa de um GRAPH_RESOURCE_ID valor variável.
   • Crie (ou atualize) permissões delegadas usando o tipo de recurso oAuth2PermissionGrant com os valores das variáveis SP_OBJECT_ID e GRAPH_RESOURCE_ID.

Use as informações das seções a seguir para completar essas etapas.

Obtenha seu ID de principal de serviço

Um principal de serviço é a identidade do seu aplicativo no seu inquilino. Você precisa dela antes de poder conceder permissões pela API.

1. Defina o método Graph Explorer para GET e use essa URL. Substitua <YOUR_CLIENT_APP_ID> pelo ID real da sua aplicação no cliente a partir da Etapa 3: Copiar ID da Aplicação (cliente):

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
   

2. Selecione Executar consulta.

   • Se a consulta for bem-sucedida, o valor que será retornado é o seu SP_OBJECT_ID.

   • Se a consulta falhar com um erro de permissões, selecione a aba Modificar permissões , consinta com as permissões necessárias e então selecione Executar consulta novamente. O valor retornado é o seu SP_OBJECT_ID.

   • Se a consulta devolver resultados vazios ("value": []), crie o principal de serviço usando os seguintes passos:

     1. Defina o método para POST e use esta URL:

        https://graph.microsoft.com/v1.0/servicePrincipals
        

        Corpo da Solicitação (substitua YOUR_CLIENT_APP_ID pelo ID real do seu cliente da Aplicação):

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. Selecione Executar consulta. Você deverá receber uma 201 Created resposta. O id valor retornado é seu SP_OBJECT_ID.

Obtenha o ID do seu recurso Graph

1. Defina o método Graph Explorer para GET e use esta URL:

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
   

2. Selecione Executar consulta.

   • Se a consulta for bem-sucedida, copie o id valor. Esse valor é o seu GRAPH_RESOURCE_ID.
   • Se a consulta falhar com um erro de permissões, selecione a aba Modificar permissões , consinta com as permissões necessárias e então selecione Executar consulta novamente. Copie o valor id. Esse valor é o seu GRAPH_RESOURCE_ID.

Criar permissões delegadas

Essa chamada de API concede consentimento de administrador em todo o locatário para todas as treze permissões, incluindo as permissões beta que não estão visíveis em centro de administração do Microsoft Entra.

1. Defina o método Graph Explorer para POST e use esta URL e corpo da solicitação:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants
   

   Corpo do Pedido:

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentIdentity.Read.All AgentRegistration.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

2. Selecione Executar consulta.

   • Se você receber 201 Created resposta: Sucesso! O scope campo na resposta mostra todos os treze nomes de permissão. Você acabou.
   • Se a consulta falhar com um erro de permissões (provavelmente DelegatedPermissionGrant.ReadWrite.All), selecione a aba Modificar permissões , consinta com DelegatedPermissionGrant.ReadWrite.All, e então selecione Executar consulta novamente.
   • Se você receber o erro Request_MultipleObjectsWithSameKeyValue: Uma concessão já existe. Talvez alguém tenha adicionado permissões antes. Veja a seguir : Atualizar permissões delegadas.

Atualizar permissões delegadas

Quando você receber um Request_MultipleObjectsWithSameKeyValue erro ao usar os passos para criar permissões delegadas, use esses passos para atualizar as permissões delegadas.

1. Defina o método Graph Explorer para GET e use esta URL:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
   

2. Selecione Executar consulta. Copie o valor id da resposta. Esse valor é YOUR_GRANT_ID.

3. Defina o método Graph Explorer para PATCH e use essa URL com YOUR_GRANT_ID.

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>
   

   Corpo do Pedido:

   {
      "scope": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentIdentity.Read.All AgentRegistration.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

4. Selecione Executar consulta. Você deve obter uma resposta 200 OK com todas as treze permissões no campo scope.

Melhores práticas de segurança

Revise essas diretrizes para manter o registro do seu aplicativo seguro e em conformidade.

Certo:

• Use o registro de inquilino único.
• Conceda apenas as permissões delegadas necessárias.
• Audite permissões regularmente.
• Remova o app quando não for mais necessário.

Não:

• Conceda permissões de aplicativo. Use apenas delegado.
• Compartilhe o ID do cliente publicamente.
• Conceda outras permissões desnecessárias.
• Use o app para outros propósitos.

O que a CLI configura automaticamente

Quando você executa a365 setup requirements, a CLI valida o registro do aplicativo e pode precisar fazer alterações. Antes de aplicar as alterações, a CLI mostra um resumo e solicita confirmação:

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

Para ignorar o prompt de confirmação (por exemplo, em um ambiente de CI), use o --yes sinalizador:

a365 setup requirements --yes

A tabela a seguir descreve cada alteração que a CLI pode fazer:

Se você recusar o prompt, a CLI não modificará o registro do aplicativo. Se forem necessárias alterações para que a CLI funcione, você poderá configurá-las manualmente no Centro de administração do Microsoft Entra ou executar novamente com --yes.

Próximas Etapas 

Depois de registrar seu aplicativo cliente personalizado, use-o com a CLI do Agent 365 para concluir a configuração do Agente 365:

Troubleshooting

Esta seção descreve como solucionar erros com o registro de aplicativos de cliente personalizados.

Falha na validação da CLI durante a configuração

Sintoma: A execução de a365 setup ou a365 setup requirements falha com erros de validação relacionados ao seu aplicativo cliente personalizado.

Solução: Use esta lista de verificação para verificar se o registro do seu aplicativo está correto:

# Run requirements validation to see validation messages
a365 setup requirements

Resultado esperado: O CLI exibe Custom client app validation successful.

Se você não obtiver o resultado esperado, verifique cada uma das seguintes verificações:

Permissão Delegada Necessária:

• AgentIdentityBlueprintPrincipal.Create [Beta]
• AgentIdentityBlueprint.ReadWrite.All [Beta]
• AgentIdentityBlueprint.UpdateAuthProperties.All [Beta]
• AgentIdentityBlueprint.AddRemoveCreds.All [Beta]
• AgentIdentityBlueprint.DeleteRestore.All [Beta]
• AgentInstance.ReadWrite.All [Beta]
• AgentIdentity.Create.All [Beta]
• AgentIdentity.DeleteRestore.All [Beta]
• AgentIdentity.Read.All [Beta]
• AgentRegistration.ReadWrite.All
• DelegatedPermissionGrant.ReadWrite.All
• Directory.Read.All
• User.Read

Consentimento do administrador concedido incorretamente

Sintoma: A validação falha mesmo que você tenha adicionado permissões.

Causa raiz: Você não concedeu o consentimento do administrador, ou concedeu-o incorretamente.

Solução: Em seu registro de aplicativo no centro de administração do Microsoft Entra, vá para permissões de API e selecione Conceder consentimento de administrador para [Seu Locatário]. Verifique se todas as permissões mostram marcas verdes em Status.

Falha na criação do blueprint: o consentimento do administrador não foi concedido.

Sintoma: a365 setup all exibe "Consentimento do aplicativo delegado garantido com sucesso", mas, logo em seguida, falha durante a criação do blueprint com:

Admin consent has not been granted for this application.
Share this URL with an Application Administrator or Global Administrator to grant consent:
  https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Root cause: seu locatário já tem um registro oauth2PermissionGrant para seu aplicativo cliente personalizado (de uma execução de instalação parcial anterior ou de uma ação anterior de "Conceder consentimento do administrador" em centro de administração do Microsoft Entra para outros escopos), mas esse registro está sem o escopo necessário (AgentIdentityBlueprint.ReadWrite.All). A CLI detecta o escopo ausente e apresenta uma URL de consentimento para um administrador concluir a concessão.

Solução:

Compartilhe a URL de consentimento impressa na saída de erro com um Administrador de Aplicativo ou Administrador Global. A URL tem a seguinte aparência:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent?client_id=<client-app-id>

Depois que o administrador conceder consentimento, execute a365 setup all --agent-name <name>novamente .

Se você tiver acesso de administrador, poderá abrir a URL diretamente em um navegador para conceder consentimento sem esperar.

Tipo de permissão errado

Sintoma: O CLI falha com erros de autenticação ou erros de permissão negada.

Causa raiz: Você adicionou permissões de aplicação em vez de permissões delegadas.

Esta tabela descreve os diferentes tipos de permissões.

Por que delegar?

• Você faz login de forma interativa (autenticação do navegador)
• A CLI realiza ações como você (as trilhas de auditoria mostram sua identidade)
• Mais seguro - limitado pelas suas permissões reais
• Garante responsabilidade e conformidade

Solução:

1. Vá para centro de administração do Microsoft Entra>Registros de aplicativos> Seu aplicativo >Permissões de API
2. Remova quaisquer permissões de aplicação. Essas permissões aparecem como Aplicação na coluna Tipo .
3. Adicione as mesmas permissões que as permissões delegadas .
4. Conceda o consentimento do administrador novamente.

Permissões beta desaparecem após consentimento do administrador no centro de administração do Microsoft Entra

Sintoma: você usou Opção B: Microsoft API do Graph (Para Permissões Beta) para adicionar permissões beta, mas elas desaparecem depois que você seleciona Conceder consentimento do administrador no Centro de Administração do Microsoft Entra.

Root cause: O Centro de Administração do Microsoft Entra não exibe permissões beta na interface do usuário. Quando você seleciona Conceder consentimento do administrador, o portal concede consentimento apenas para as permissões visíveis e sobrescreve o consentimento concedido pela API.

Por que isso acontece:

1. Use a API do Graph (Opção B) para adicionar todas as treze permissões, incluindo permissões beta.
2. A chamada de API já consentType: "AllPrincipals"concede consentimento de administrador para todo o inquilino.
3. Você vai para centro de administração do Microsoft Entra e vê apenas um subconjunto de permissões porque as permissões beta são invisíveis no portal.
4. Você seleciona Conceder consentimento de administrador achando que precisa.
5. O centro de administração do Microsoft Entra substitui o consentimento que foi concedido pela API por apenas as permissões visíveis.
6. Suas permissões beta agora são excluídas.

Solução:

• Não use o consentimento do administrador no centro de administração do Microsoft Entra após o método de API: o método de API já concede consentimento do administrador.
• Se você excluir permissões beta acidentalmente, execute novamente Option B Etapa 3 (Conceder consentimento do administrador usando API do Graph) para restaurá-las. Se receber um Request_MultipleObjectsWithSameKeyValue erro, siga os passos para atualizar permissões delegadas.
• Para verificar se todas as treze permissões estão listadas, confira o campo scope na resposta POST ou PATCH.

App não encontrado durante a validação

Sintoma: CLI relata Application not found ou Invalid client ID erros.

Solution:

1. Verifique se você copiou o ID da aplicação (cliente) no formato GUID, e não o ID do Objeto:

   • Vá para Centro de Administração do Microsoft Entra>Registros de Aplicativos> Seu aplicativo >Visão Geral
   • Copie o valor sob ID de Aplicação (cliente)
   • O formato deve ser: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Verifique se o aplicativo existe no seu locatário:

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

Learn como registrar um aplicativo no Microsoft Entra ID.