Registro personalizado de aplicativo cliente para CLI do Agente 365

A CLI do Agente 365 exige um registro personalizado de aplicativo cliente no seu tenant do Microsoft Entra ID para autenticar e gerenciar os Blueprints de Identidade do Agente.

Pré-requisitos

Para registrar o aplicativo (Passos 1 e 2):

• Por padrão, qualquer usuário do tenant pode registrar aplicações no centro de administração do Microsoft Entra. No entanto, administradores de inquilinos podem restringir essa capacidade.

Para adicionar permissões e conceder consentimento (Passo 3):

• Um desses cargos administrativos é obrigatório:
  • Administrador de Inscrição: Recomendado - pode gerenciar cadastros 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

Passo 1: Registrar a inscrição

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

1. Acesse o centro de administração do Microsoft Entra
2. Selecionar cadastros de aplicativos
3. Selecione Novo registro
4. Entrar:
   • Nome: Agent365 CLI (ou seu nome preferido)
   • Tipos de conta suportados: Contas apenas neste diretório organizacional (Inquilino único)
   • Redirecionar URI: Selecione cliente público/nativo (móvel e desktop) → Enter http://localhost:8400/
5. Escolha Registrar

Passo 2: Copiar o ID do Aplicativo (cliente)

Na página de Visão Geral do app, copie o ID do aplicativo (cliente) (formato GUID). Insira esse valor ao usar o a365 config init comando.

Passo 3: Configurar permissões da API

Escolha o método apropriado:

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

Opção A: Centro de Administração do Microsoft Entra (Método Padrão)

Use esse método se as permissões beta estiverem visíveis no seu locatário.

1. No registro do seu app, vá para permissões da API

2. Selecione Adicionar uma permissão → Microsoft Graph → Permissões Delegadas

   Importante

   Você DEVE usar permissões Delegadas (NÃO permissões de Aplicação). O CLI autentica de forma interativa – você faz login e ele age em seu nome. Veja Tipo de permissão errado se você acidentalmente adicionar permissões de Aplicação.

3. Adicione estas cinco permissões uma por uma:

   Permissão	Propósito
   AgentIdentityBlueprint.ReadWrite.All	Gerenciar configurações do Agent Blueprint (API beta)
   AgentIdentityBlueprint.UpdateAuthProperties.All	Permissões herdadas do Agent Blueprint (API beta)
   Application.ReadWrite.All	Criar e gerenciar aplicações e Projetos de Agentes
   DelegatedPermissionGrant.ReadWrite.All	Conceder permissões para projetos de agentes
   Directory.Read.All	Leia os dados do diretório para validação

   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 para as cinco permissões

4. Selecione Conceder consentimento administrativo para [Seu Inquilino]

   • Por que isso é obrigatório? Os Agentes Identity Blueprints são recursos em todo o tenant que múltiplos usuários e aplicativos podem consultar. 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 seu inquilino.

5. Verifique todas as permissões que 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: API Microsoft Graph (para permissões beta)

Use este método se AgentIdentityBlueprint.* as permissões não estiverem visíveis no centro de administração do Microsoft Entra.

1. Open Graph Explorer

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 a API do Graph. Para completar isso, você precisa:

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

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

Obtenha seu ID de principal de serviço

Um principal de serviço é a identidade do seu app no seu tenant, exigida antes de conceder permissões via API.

1. Defina o método Graph Explorer para GET e use esta URL (substitua <YOUR_CLIENT_APP_ID> pelo ID real do seu cliente de aplicação a partir da Etapa 2: 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 retornado é 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 é 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ê deveria 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. Este é 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. Este é seu GRAPH_RESOURCE_ID.

Criar permissões delegadas

Esta chamada de API concede consentimento de administrador para todo o locatário para todas as cinco permissões, incluindo as duas permissões beta que não são visíveis no 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": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

2. Selecione Executar consulta.

   • Se você receber 201 Created resposta: Sucesso! O scope campo na resposta mostra todos os cinco 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 erro Request_MultipleObjectsWithSameKeyValue: Uma bolsa 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 usando 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. Este é YOUR_GRANT_ID.

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

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

   Corpo do Pedido:

   {
      "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

4. Selecione Executar consulta. Você deve receber uma 200 OK resposta com as cinco permissões disponíveis no scope campo.

Resolução de problemas

Esta seção contém informações sobre como solucionar erros no registro de aplicativos personalizados do cliente.

Tipo de permissão errado (Delegado vs Aplicação)

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.

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. Acesse o centro >de administração do Microsoft EntraRegistros> de aplicativos Permissões da API do seu app >
2. Remova quaisquer permissões de aplicação (elas aparecem como "Aplicação" na coluna Tipo )
3. Adicione as mesmas permissões que as permissões delegadas
4. Conceda novamente consentimento do administrador

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

Sintoma: Você usou a Opção B: API Microsoft Graph (para permissões beta) para adicionar permissões beta, mas elas desapareceram após selecionar Conceder consentimento de administrador no centro de administração do Microsoft Entra.

Causa raiz: o centro de administração do Microsoft Entra não mostra permissões beta na interface, então, quando você seleciona Conceder consentimento de administrador, ele só concede as permissões visíveis e sobrescreve o consentimento concedido pela API.

Por que isso acontece:

1. Você usa a API do Graph (Opção B) para adicionar todas as cinco permissões, incluindo permissões beta
2. A chamada de API já consentType: "AllPrincipals"concede consentimento de administrador para todo o locatário
3. Você vai ao centro de administração do Microsoft Entra e vê apenas três permissões porque as permissões beta são invisíveis
4. Você seleciona Conceder consentimento de administrador achando que precisa
5. O centro de administração do Microsoft Entra sobrescreve seu consentimento concedido pela API com apenas as três permissões visíveis
6. Suas duas permissões beta agora foram excluídas

Solução:

• Nunca use o consentimento do administrador do centro de administração do Microsoft Entra após o método da API: O método da API já concede consentimento do administrador
• Se você acidentalmente deletou permissões beta, execute novamente a Opção B Passo 3 (Conceder consentimento do administrador usando a API do Graph) para restaurá-las. Você recebe um Request_MultipleObjectsWithSameKeyValue erro - siga os passos para atualizar permissões delegadas.
• Verifique o scope campo na POST resposta ou PATCH para verificar se todas as cinco permissões estão listadas

Erros de validação

A CLI valida automaticamente seu aplicativo cliente ao ser executado a365 setup ou a365 config init.

Problemas comuns:

• App não encontrado: Verifique se você copiou o ID do aplicativo (cliente) (não o ID do objeto)
• Permissões faltantes: Adicionar todas as cinco permissões necessárias
• Consentimento do administrador não concedido:
  • Se você usou a Opção A (apenas centro de administração Microsoft Entra): Selecione Conceder consentimento de administrador no centro de administração Microsoft Entra
  • Se você usou a Opção B (API do Graph): Reexecute a POST solicitação de ou PATCH . NÃO use o botão de consentimento do centro de administração do Microsoft Entra
• Tipo de permissão errado: Use permissões delegadas, não permissões de aplicação

Para solução detalhada de problemas, veja Registrar uma aplicação no Microsoft Entra ID.

Melhores práticas de segurança

Certo:

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

Não:

• Permissão para conceder pedidos (Usar apenas Delegado)
• Compartilhe o ID do Cliente publicamente
• Conceda outras permissões desnecessárias
• Use o aplicativo para outros propósitos

Próximas etapas

Agora que você registrou seu aplicativo cliente personalizado, pode usá-lo com a CLI do Agente 365:

• Comece com a CLI do Agente 365 - Instale e configure a CLI com seu aplicativo cliente
• Configure o blueprint e a instância do agente - Crie e configure a identidade do seu agente
• Implante e publique agentes - Implante seu agente no Azure e publique no Microsoft 365