Registro personalizado de aplicativo cliente para o CLI do Agent 365

A CLI do Agente 365 precisa de um registro de aplicativo cliente personalizado em seu locatário 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 API

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 Microsoft Entra

2. Selecione App registrations

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.
   • 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

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. Insira esse valor ao usar o a365 config init comando.

4. Configurar permissões de API

Escolha o método apropriado:

• Option A: Use Microsoft Entra Central de Administração para todas as permissões (se as permissões beta estiverem visíveis)
• Option B: use o Microsoft Graph API 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 as permissões beta estiverem visíveis no 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 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	Atualizar permissões herdáveis 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 todas as cinco permissões.

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

   • Por que isso é obrigatório? Os Modelos de Identidade do Agente são recursos do arrendatário a que múltiplos usuários e aplicativos podem fazer referência. 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 Graph API (para permissões beta)

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

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 Graph API. 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 cinco permissões, incluindo as duas permissões beta que não estão visíveis no centro de administração 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 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 id valor 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": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

4. Selecione Executar consulta. Você deve receber uma resposta 200 OK com todas as cinco 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.

Próximas etapas

Após registrar seu aplicativo cliente personalizado, use-o com a CLI do Agent 365 no ciclo de vida do desenvolvimento do Agent 365:

Resolução de problemas

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: Executando o comando a365 config init ou a365 setup 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 configuration to see validation messages
a365 config init

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:

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All [Beta]
• AgentIdentityBlueprint.UpdateAuthProperties.All [Beta]
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All

Consentimento do administrador concedido incorretamente

Sintoma: A validação falha mesmo com permissões adicionadas.

Causa raiz: O consentimento do administrador não é concedido, ou é concedido incorretamente.

Solução: A solução correta depende do método que você usou:

Se você acidentalmente utilizar o centro de administração do Microsoft Entra após a opção B: Você excluiu suas permissões beta. Siga Atualize permissões delegadas para restaurá-las.

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. Acesse Microsoft Entra admin center>Registro de aplicativos> Seu aplicativo >Permissões da 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 o consentimento do administrador no Centro de Administração do Microsoft Entra.

Symptom: você usou Option B: Microsoft Graph API (Para Permissões Beta) para adicionar permissões beta, mas elas desaparecem depois que você seleciona Consentimento do administrador do Grant no centro de administração Microsoft Entra.

Root cause: O Centro de Administração do Microsoft Entra não mostra 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 Graph API (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 inquilino.
3. Você vai para Microsoft Entra centro de administração 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 substitui o consentimento que você concedeu pela API por apenas as três permissões visíveis.
6. Suas duas permissões beta agora foram deletadas.

Solução:

• Não use consentimento de administrador do centro de administração do Microsoft Entra após o método de API: o método de API já concede consentimento de administrador.
• Se você excluir permissões beta acidentalmente, execute novamente Option B Etapa 3 (Conceder consentimento do administrador usando Graph API) para restaurá-las. Se receber um Request_MultipleObjectsWithSameKeyValue erro, siga os passos para atualizar permissões delegadas.
• Para verificar se todas as cinco permissões estão listadas, verifique 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.