onboarding em massa do Agent 365 com PowerShell

Use o onboarding em massa do Agent 365 para reduzir tarefas de configuração repetitivas ao integrar vários agentes. Defina identidades de agentes, patrocinadores, proprietários e cadastros em um CSV revisável, valide seus relacionamentos antes de provisionar e revise os resultados em um relatório consolidado. Os scripts validam o arquivo completo, calculam a ordem das dependências e então criam cada objeto usando o Microsoft Graph.

Use este fluxo de trabalho depois de entender como integrar um único agente com a CLI do Agent 365. Quando precisar integrar vários agentes ao mesmo tempo ou repetir o onboarding de locatários, defina os objetos e seus relacionamentos em um único arquivo CSV, em vez de executar o fluxo de onboarding da CLI separadamente para cada agente.

Este artigo fornece as instruções de integração em massa de ponta a ponta, desde a configuração de automação da aplicação e requisitos de CSV até validação, execução e solução de problemas.

O que o fluxo de trabalho cria

Cada linha CSV representa um objeto. Os relacionamentos compatíveis são:

Blueprint
  |
  +-- AgentIdentity
        |-- AgentUser
        +-- AgentRegistration

Um usuário de agente e um registro de agente são filhos independentes de uma identidade de agente. Uma falha em um não impede que se tente o outro.

Para mais informações sobre esses objetos, veja identidade do Agent 365.

Prerequisites

Antes de começar, verifique se você tem:

• Um tenant onde o Microsoft Agent 365 está disponível.
• PowerShell 7 ou posterior.
• Use o Git para clonar o repositório DevTools.
• O Microsoft.Graph.Authentication módulo PowerShell versão 2.x.
• É necessário ser um Administrador de Funções com Privilégios ou superior para ter o consentimento único de permissão do aplicativo de automação.
• Um patrocinador para cada novo blueprint e identidade de agente.
• Proprietários, gerentes e proprietários de registro que já existem no Microsoft Entra ID.
• Um domínio de locatário verificado para o nome UPN do novo agente.
• Uma licença apropriada e um local de uso de duas letras se o CSV atribuir uma licença a um usuário agente.

Os usuários do Agente estão disponíveis apenas para locatários que participam do programa de pré-visualização da Frontier.

Instale o módulo Microsoft Graph obrigatório:

Install-Module Microsoft.Graph.Authentication -Scope CurrentUser

Obtenha os scripts

Clone o repositório DevTools do Agent 365 e depois mude para o diretório de registro em massa:

git clone https://github.com/microsoft/Agent365-devTools.git
Set-Location .\Agent365-devTools\scripts\bulk-agent-registration

Mantenha os scripts nesse diretório juntos. A365-BulkOnboarding.ps1 invoca A365-AutomationOrchestrator.ps1, que invoca os scripts de provisão específicos de objetos.

Configurar autenticação

O onboarding em massa pode ser executado sem vigilância usando um aplicativo de automação de propriedade do locatário ou uma identidade gerenciada atribuída ao sistema. Também pode rodar interativamente com autenticação delegada.

Complete a configuração da aplicação, o consentimento de permissão e a configuração da autenticação antes do primeiro lote. Para cada lote subsequente, prepare o CSV, valide o plano, execute o onboarding e revise os resultados.

As execuções somente por aplicativo utilizam funções de aplicativo concedidas à entidade de serviço do aplicativo de automação ou da identidade gerenciada — e não a função de administrador do operador.

As concessões de permissão para a identidade do runner são separadas da configuração do GrantAdminConsent CSV, que solicita consentimento para permissões declaradas por um blueprint ou identidade do agente. Revise quaisquer ações de consentimento pendentes no relatório de execução.

O onboarding em massa suporta estes métodos de autenticação de runner:

Credenciais de identidade federadas e seleção gerenciada de identidade atribuída pelo usuário não são suportadas como métodos de autenticação do runner.

Crie a aplicação de automação

Faça login interativamente como Administrador Global ou Administrador de Papéis Privilegiados e crie uma aplicação de automação para todos os tipos de objetos suportados. Crie o aplicativo sem um segredo do cliente ou certificado para que você possa adicionar e gerenciar suas credenciais separadamente no centro de administração do Microsoft Entra:

.\New-A365AutomationApp.ps1 `
    -TenantId <tenant-id> `
    -Interactive `
    -DisplayName 'A365 Provisioning Automation' `
    -Scenario All `
    -SkipGrant

O script cria ou reutiliza o aplicativo e a entidade de serviço e declara as permissões de aplicativo necessárias do Microsoft Graph e os escopos delegados. O aviso de que nenhuma credencial foi adicionada é esperado; o aplicativo não pode autenticar até que você adicione um segredo do cliente ou um certificado. Como o comando usa -SkipGrant, ele não concede consentimento do administrador.

Após o término do comando, peça a um administrador para abrir a URL do Portal impressa pelo script. No centro de administração do Microsoft Entra, selecione Conceder consentimento de administrador para as permissões declaradas. Não comece a integração em massa até que o consentimento administrativo esteja completo. Você pode executar o script novamente para conciliar a aplicação com as declarações de permissão que faltam.

Registre o ID do aplicativo (cliente) da aplicação de automação. Não use o ID do objeto principal de serviço quando um comando pedir -ClientId.

Analise as permissões do aplicativo

-Scenario Alldeclara a união destas permissões de aplicação Microsoft Graph:

Os AgentUser, AgentIdentity, Registration e All cenários também declaram escopos delegados para suas operações interativas selecionadas. Os escopos de registro são declarados por padrão e podem ser suprimidos. Uma execução não assistida que usa Auth=Same depende das permissões da aplicação na tabela anterior.

Configurar campos de autenticação

Defina uma tabela hash de autenticação e reutilize-a para validação e execução.

Segredo do cliente

No centro de administração do Microsoft Entra, vá em Identity>Applications>Registros de aplicativo e selecione o aplicativo de automação. Selecione Certificados & segredos>Segredos do cliente>Novo segredo do cliente, insira uma descrição e expiração, e então selecione Adicionar. Copie o valor secreto imediatamente e armazene-o de forma segura; ele não aparece novamente depois que você sai da página. Para mais informações, veja Adicionar credenciais ao seu aplicativo.

Leia o segredo do cliente como um SecureString em vez de colocá-lo diretamente na linha de comando:

$clientSecret = Read-Host -Prompt 'Automation application client secret' -AsSecureString
$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    ClientSecret = $clientSecret
}

Segredos de clientes são menos seguros que certificados e devem ser limitados a testes ou automação de curta duração. Para automação de produção não assistida, use um certificado ou identidade gerenciada atribuída pelo sistema.

Certificate

Para automação de produção, obtenha um certificado da autoridade certificadora da sua organização. Para ambientes de teste, veja Criar um certificado público autoassinado para autenticar sua aplicação. Na página Certificados & segredos do aplicativo de automação, selecione Certificados>, faça upload do arquivo público .cer, .pem ou .crt e então selecione Adicionar. O runner precisa de acesso à chave privada; o aplicativo de automação armazena apenas o certificado público. Para mais informações sobre autenticação por certificado somente para aplicativo, consulte Usar autenticação somente para aplicativo com o SDK do Microsoft Graph PowerShell.

Use o thumbprint do certificado que contém a chave privada:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    CertificateThumbprint = '<certificate-thumbprint>'
}

Para um lote que pode conter linhas AgentUser, instale o certificado em Cert:\CurrentUser\My. Para usar um certificado de Cert:\LocalMachine\My em todos os tipos de objeto, passe-o como um objeto de certificado em vez de usar sua impressão digital.

Alternativamente, forneça o certificado como um X509Certificate2 objeto:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    Certificate = Get-Item 'Cert:\CurrentUser\My\<certificate-thumbprint>'
}

Ou carregar a chave privada de um PFX protegido por senha:

$pfxPassword = Read-Host -Prompt 'PFX password' -AsSecureString
$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    CertificatePath = 'C:\secure\a365-automation.pfx'
    CertificatePassword = $pfxPassword
}

Forneça apenas uma fonte de certificado. -CertificatePassword é válido apenas com -CertificatePath.

Identidade gerenciada atribuída pelo sistema

Ative uma identidade gerenciada atribuída pelo sistema no recurso do Azure que executa os scripts. Conceda as permissões de aplicativo necessárias do Microsoft Graph da tabela anterior diretamente ao principal de serviço da identidade gerenciada. Para instruções, veja Conceder e revogar permissões de API para identidades gerenciadas.

$authParameters = @{
    TenantId = '<tenant-id>'
    UseManagedIdentity = $true
}

Não inclua ClientId com UseManagedIdentity. Os scripts usam a identidade do host atribuída pelo sistema e não suportam a seleção de uma identidade atribuída pelo usuário.

Entrada delegada interativa

Use um ID de cliente de aplicação controlado pelo chamador para que o mesmo exemplo também suporte arquivos CSV que contenham linhas AgentUser:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    Interactive = $true
}

Quando você fornece ClientId, a autorização interativa depende dos escopos delegados consentidos daquela aplicação e dos papéis de diretório do usuário logado. New-A365AutomationApp.ps1 -Scenario All declara os escopos delegados e possibilita fluxos de cliente público. Siga a URL de consentimento do administrador impressa pelo script de configuração antes da primeira execução interativa. Se um lote não contiver linhas AgentUser, você pode omitir ClientId; os scripts então usam o cliente PowerShell Microsoft Graph e seus escopos consentidos. As operações do AgentUser exigem um papel adequado, como Administrador do ID do Agente. Para informações de contexto, consulte Usar comandos de autenticação do Microsoft Graph PowerShell.

Preparar o arquivo CSV

Inicie com o sample-bulk-onboarding.csv. Mantenha todos os cabeçalhos na amostra, mesmo quando uma coluna não se aplica a uma linha. Deixe os valores não aplicáveis em branco.

A amostra contém linhas representativas para cada tipo de objeto suportado. Substitua seus domínios de exemplo, identidades, proprietários, patrocinadores, gerentes e valores de licença por valores do seu locatário.

Definir relações

As quatro primeiras colunas definem o grafo-objeto:

Para criar identidades de agentes sob um blueprint existente, adicione uma Blueprint linha âncora cujo ExistingId é o ID do aplicativo do blueprint. Dê a cada nova linha de AgentIdentity uma ParentKey que corresponda à Key da linha da âncora.

Defina valores para cada tipo de objeto

Valide o plano de onboarding

Antes de criar qualquer objeto de locatário, passe o CSV completo por -WhatIf:

.\A365-BulkOnboarding.ps1 `
    -CsvPath .\sample-bulk-onboarding.csv `
    @authParameters `
    -WhatIf

O script valida todo o CSV antes de fazer uma solicitação ao Microsoft Graph. Ele relata todos os erros estruturais detectados juntos, incluindo:

• Cabeçalhos ausentes ou desconhecidos.
• Faltam os valores obrigatórios.
• Chaves duplicadas.
• Tipos de objetos não suportados.
• Valores GUID, UPN, Booleano ou JSON inválidos.
• Combinações inválidas de ParentKey ou ExistingId.
• Um pai com o tipo de objeto errado.
• Ciclos de dependência.
• Valores em colunas que não se aplicam ao tipo de objeto da linha.

Se a validação for bem-sucedida, o comando imprime o plano de dependência. Em -WhatIf, o script não envia nenhuma linha de onboarding para o Microsoft Graph.

A validação bem-sucedida confirma que o CSV passa nas verificações estruturais. Não confirma se objetos de tenant podem ser resolvidos ou se o aplicativo tem as permissões necessárias para criá-los.

Executar integração em massa

Depois que o plano -WhatIf parecer correto, execute o onboarding e salve os logs e o relatório agregado:

.\A365-BulkOnboarding.ps1 `
    -CsvPath .\sample-bulk-onboarding.csv `
    @authParameters `
    -LogPath .\logs `
    -OutputJsonPath .\bulk-onboarding-result.json

O script processa os pais antes de seus filhos, mantendo a ordem do CSV entre linhas não relacionadas. Se uma linha falhar:

• O script marca seus descendentes como SkippedDependency e não os envia para o Microsoft Graph.
• Árvores de dependência independentes continuam.
• O comando escreve o resumo do console e o relatório agregado antes de sair.
• O comando retorna um código de saída não nulo se alguma linha tiver o valor Failed ou SkippedDependency.

Revise os resultados

Os status da linha final são:

O -OutputJsonPath parâmetro cria um A365BulkProvisioningRunReport para toda a execução. Revise o relatório para:

• O status e o ID resolvido para cada linha.
• Etapas com falha e detalhes do erro.
• Ações de consentimento do administrador pendentes.
• Identificadores de blueprint, identidade, usuário e registro criados.

Logs do script em massa, orquestrador e scripts filhos compartilham um ID de correlação quando usam o mesmo -LogPath.

O relatório omite os segredos do cliente Blueprint, a menos que você use -IncludeBlueprintSecretsInOutputexplicitamente . O relatório nunca inclui entradas de autenticação, tokens de acesso ou senhas de certificados.

Verificar integração

Após a execução:

• Revise o status de cada linha e o ID do objeto resultante.
• Verifique se os registros esperados aparecem na administração do Agent 365.
• Verifique os patrocinadores e responsáveis designados.
• Se você solicitou usuários-agente ou licenças, verifique essas atribuições.
• Revise e conclua as ações pendentes de consentimento do administrador.

Recuperação de uma execução parcial

Você pode consultar blueprints existentes e identidades de agentes através ExistingId de linhas de âncora. Essa opção não é suportada para linhas de agent-user ou de registro.

Corrija a falha e prepare um lote revisado de retentativas baseado no estado observado do locatário, em vez de reexecutar cegamente linhas bem-sucedidas.

Solução de problemas

Use a tabela a seguir para resolver problemas comuns de integração.

Para questões gerais de produto e CLI, veja o guia de solução de problemas do Agent 365. Para relatar um problema com esses scripts, use Agent 365 DevTools issues.

Próximas Etapas 

Após a integração dos seus agentes:

• Valide sua integração com o Agent 365.
• Publicar um agente no centro de administração do Microsoft 365.
• Saiba mais sobre a identidade do Agente 365.