Registro personalizado de aplicativo cliente para o CLI do Agent 365

A CLI do Agent 365 precisa de um registro personalizado de aplicativo cliente no seu locatário do Microsoft Entra ID para autenticar e gerenciar Blueprints 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 a centro de administração do Microsoft Entra e, se necessário, 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 config init ou 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 como ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, em que {client-id} é o valor Application (ID do cliente) copiado.
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 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 as 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 doze permissões uma a uma:

   Permissão	Propósito
   AgentIdentityBlueprintPrincipal.Create	Criar a entidade 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)
   AgentRegistrations.ReadWrite.All	Registrar e gerenciar agentes por meio da API de Registros do Agente (API beta)
   DelegatedPermissionGrant.ReadWrite.All	Conceder permissões para blueprints 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

   Observação

   AgentRegistrations.ReadWrite.All é necessário para a instalação do agente. A CLI adquire essa permissão silenciosamente por meio de .default e o validador do Agent 365 CLI não a verifica explicitamente, mas ela deve estar presente no registro do aplicativo e com 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 para todas as doze permissões.

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

   • Por que isso é obrigatório? Os Blueprints de Identidade do Agente são recursos do locatário aos quais vários 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 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 da Entidade de serviço. Você precisa de um SP_OBJECT_ID valor variável.
   • ID de recurso do Graph. 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

Uma entidade de serviço é a identidade do seu aplicativo no seu locatário. 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> pela ID real do seu cliente do Aplicativo a partir da Etapa 3: Copiar ID do Aplicativo (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 valor id 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 doze permissões, incluindo as duas permissões beta que não estã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": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentRegistrations.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 doze 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": "AgentIdentityBlueprintPrincipal.Create AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All AgentIdentityBlueprint.AddRemoveCreds.All AgentIdentityBlueprint.DeleteRestore.All AgentInstance.ReadWrite.All AgentIdentity.Create.All AgentIdentity.DeleteRestore.All AgentRegistrations.ReadWrite.All DelegatedPermissionGrant.ReadWrite.All Directory.Read.All User.Read"
   }
   

4. Selecione Executar consulta. Você deve receber uma resposta 200 OK com as doze permissões disponíveis 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 config init ou 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 config init --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 em centro de administração do Microsoft Entra ou executar novamente com --yes.

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:

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

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.

Causa raiz: 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. Você usa a API do Graph (Opção B) para adicionar todas as onze permissões, incluindo permissões beta.
2. A chamada de API com consentType: "AllPrincipals"já concede consentimento de administrador para todo o locatário.
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 concedido pela API com somente 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 onze 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 aplicativo> Seu aplicativo >Overview
   • 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.