Registro personalizado de aplicativo cliente para o CLI do Agent 365

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

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 seis permissões uma a uma:

   Permissão	Propósito
   AgentIdentityBlueprint.ReadWrite.All	Gerenciar configurações do Blueprint do Agente
   AgentIdentityBlueprint.UpdateAuthProperties.All	Atualizar permissões herdáveis do Agente Blueprint
   Application.ReadWrite.All	Criar e gerenciar aplicações e Blueprints de Agentes
   DelegatedPermissionGrant.ReadWrite.All	Conceder permissões para blueprints de agentes
   Directory.Read.All	Leia os dados do diretório para validação
   User.ReadWrite.All	Criar usuários do agente, definir o local de uso e atribuir licenças

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

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:

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All
• AgentIdentityBlueprint.UpdateAuthProperties.All
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All
• User.ReadWrite.All

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: No registro do aplicativo no centro de administração do Microsoft Entra, acesse 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 aplicativo> 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.

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.