Enrôlement en masse de l’Agent 365 avec PowerShell

Utilisez l’intégration en bloc d’Agent 365 pour réduire les tâches de configuration répétitives lors de l’intégration de plusieurs assistants. Définissez les identités des assistants, les sponsors, les propriétaires et les inscriptions dans un seul fichier CSV pouvant être examiné, validez les relations entre ces éléments avant le provisionnement, puis examinez les résultats dans un rapport consolidé. Les scripts valident le fichier complet, calculent l’ordre des dépendances, puis créent chaque objet en utilisant Microsoft Graph.

Utilisez ce flux de travail après avoir compris comment intégrer un seul agent avec la CLI de l’Agent 365. Lorsque vous devez intégrer plusieurs agents simultanément ou répéter l’onboarding des tenants, définissez les objets et leurs relations dans un seul fichier CSV au lieu d’exécuter le flux d’intégration de la CLI séparément pour chaque agent.

Cet article fournit les instructions d’intégration en masse de bout en bout, depuis la configuration des applications automatisées et les exigences CSV jusqu’à la validation, l’exécution et le dépannage.

Ce que crée le workflow

Chaque ligne CSV représente un objet. Les relations prises en charge sont :

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

Un utilisateur d’agent et une inscription d’agent sont des enfants indépendants d’une identité d’agent. Un échec dans l’un n’empêche pas l’autre d’être tenté.

Pour plus d’informations sur ces objets, voir Identité Agent 365.

Prerequisites

Avant de commencer, assurez-vous d’avoir :

• Un tenant où Microsoft Agent 365 est disponible.
• PowerShell 7 ou version ultérieure.
• Git pour cloner le dépôt DevTools.
• Le Microsoft.Graph.Authentication module PowerShell version 2.x.
• Un rôle d’Administrateur de rôle privilégié ou rôle supérieur pour le consentement unique aux autorisations de l’application d’automatisation.
• Un sponsor pour chaque nouveau blueprint et identité d’assistant.
• Propriétaires, gestionnaires et titulaires d’enregistrement déjà présents dans Microsoft Entra ID.
• Un domaine de locataire vérifié pour chaque nom d’utilisateur principal (UPN) de nouvel assistant.
• Une licence appropriée et un emplacement d’utilisation indiqué par un code à deux lettres si le fichier CSV attribue une licence à un utilisateur d’assistant.

Les utilisateurs d’agents sont disponibles uniquement pour les locataires participant au programme de prévisualisation Frontier.

Installez le module Microsoft Graph requis :

Install-Module Microsoft.Graph.Authentication -Scope CurrentUser

Récupérez les scripts

Clonez le dépôt DevTools Agent 365, puis passez au répertoire d’enregistrement en masse :

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

Gardez les scripts dans ce répertoire ensemble. A365-BulkOnboarding.ps1 invoque A365-AutomationOrchestrator.ps1, qui invoque les scripts de provisionnement spécifiques à l’objet.

Configurer l’authentification

L’intégration en masse peut s’exécuter sans surveillance en utilisant une application d’automatisation détenue par le locataire ou une identité managée attribuée par le système. Il peut également s’exécuter de manière interactive grâce à une authentification déléguée.

Terminez la configuration de l’application, le consentement aux permissions et la configuration de l’authentification avant le premier lot. Pour chaque lot suivant, préparez le CSV, validez le plan, effectuez l’intégration et examinez les résultats.

Les exécutions App-only utilisent des rôles applicatifs accordés au principal de service de l’application d’automatisation ou de l’identité gérée — et non au rôle d’administrateur de l’opérateur.

Les autorisations accordées à l’identité d’exécution sont distinctes du paramètre GrantAdminConsent du fichier CSV, qui demande le consentement aux autorisations déclarées par un blueprint ou une identité d’assistant. Examinez les actions de consentement en attente dans le rapport d’exécution.

L’intégration en masse prend en charge ces méthodes d’authentification runner :

Les identifiants d’identité fédérés et la sélection d’identité gérée attribuée par l’utilisateur ne sont pas pris en charge comme méthodes d’authentification par runner.

Créer l’application d’automatisation

Connectez-vous de manière interactive en tant qu’administrateur général ou administrateur de rôle privilégié et créez une application d’automatisation pour tous les types d’objets pris en charge. Créez l’application sans secret client ni certificat afin de pouvoir ajouter et gérer ses identifiants séparément dans le centre d’administration Microsoft Entra :

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

Le script crée ou réutilise l’application et le principal de service et déclare les autorisations d’application Microsoft Graph et les portées déléguées requises. L’avertissement indiquant qu’aucune information d’identification n’a été ajoutée est attendu ; l’application ne peut pas s’authentifier tant que vous n’avez pas ajouté un secret client ou un certificat. Parce que la commande utilise -SkipGrant, elle n’accorde pas le consentement de l’admin.

Une fois la commande terminée, demandez à un administrateur d’ouvrir l’URL du portail affichée par le script. Dans le centre d’administration Microsoft Entra, sélectionnez Accorder le consentement administrateur pour les autorisations déclarées. Ne commencez pas l’intégration en bloc tant que le consentement de l’administrateur n’a pas été accordé. Vous pouvez réexécuter le script pour mettre en conformité l’application et les déclarations d’autorisations manquantes.

Enregistrez le ID d’application (client) de l’application d’automatisation. N’utilisez pas l’ID d’objet de son principal de service lorsqu’une commande demande le paramètre -ClientId.

Examinez les autorisations de l’application

-Scenario Alldéclare l’union de ces permissions d’application Microsoft Graph :

Les scénarios AgentUser, AgentIdentity, Registration et All déclarent également des portées déléguées pour leurs opérations interactives sélectionnées. Les étendues d’inscription sont déclarées par défaut et peuvent être désactivées. Une exécution non surveillée qui utilise Auth=Same dépend des permissions d’application dans la table précédente.

Configurer les paramètres d’authentification

Définissez une table de hachage d’authentification et réutilisez-la pour la validation et l’exécution.

Secret de client

Dans le centre d’administration Microsoft Entra, accédez à Identité>Applications>Inscriptions d’applications, et sélectionnez l’application d’automatisation. Sélectionnez Certificats & secrets>Secrets client>Nouveau secret client, saisissez une description et une expiration, puis sélectionnez Ajouter. Copiez immédiatement la valeur secrète et stockez-la en toute sécurité ; elle n’apparaît plus après avoir quitté la page. Pour plus d’informations, voir Ajouter des identifiants à votre application.

Lisez la clé secrète client en tant que SecureString au lieu de la saisir directement dans la ligne de commande :

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

Les secrets client sont moins sécurisés que les certificats et leur utilisation devrait être limitée aux tests ou à l’automatisation éphémère. Pour une automatisation de la production non surveillée, utilisez un certificat ou une identité managée assignée par le système.

Certificate

Pour l’automatisation de la production, obtenez un certificat auprès de l’autorité de certification de votre organisation. Pour les environnements de test, voir Créer un certificat public auto-signé pour authentifier votre application. Dans la page Certificats & secrets de l’application d’automatisation, sélectionnez Certificats>Charger un certificat, chargez le fichier public .cer, .pem ou .crt, puis sélectionnez Ajouter. Le runner a besoin d’accéder à la clé privée ; l’application d’automatisation ne stocke que le certificat public. Pour plus d’informations sur l’authentification par certificat app-only, voir Utiliser l’authentification app-only avec le SDK PowerShell Microsoft Graph.

Utilisez l’empreinte digitale du certificat contenant la clé privée :

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

Pour un lot pouvant contenir des lignes AgentUser, installez le certificat dans Cert:\CurrentUser\My. Pour utiliser un certificat à partir de Cert:\LocalMachine\My pour tous les types d’objet, passez-le comme un objet de certificat au lieu d’utiliser son empreinte digitale.

Sinon, il faut fournir le certificat sous forme d’objet X509Certificate2 :

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

Ou chargez la clé privée depuis un PFX protégé par mot de passe :

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

Fournissez une seule source de certificat. -CertificatePassword est valable uniquement avec -CertificatePath.

Identité gérée attribuée par le système

Activez une identité managée assignée par le système sur la ressource Azure qui exécute les scripts. Accorder directement au principal de service de l’identité gérée les autorisations d’application Microsoft Graph requises du tableau précédent. Pour les instructions, voir Accorder et révoquer les permissions API aux identités gérées.

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

N’incluez pas ClientId avec UseManagedIdentity. Les scripts utilisent l’identité système attribuée à l’hôte et ne permettent pas de sélectionner une identité assignée par l’utilisateur.

Connexion interactive déléguée

Utilisez un identifiant client d’application contrôlé par l’appelant afin que le même exemple prenne également en compte les fichiers CSV contenant des lignes AgentUser :

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

Lorsque vous fournissez ClientId, l’autorisation interactive dépend des autorisations déléguées consenties à cette application et des rôles de répertoire de l’utilisateur connecté. New-A365AutomationApp.ps1 -Scenario All déclare les étendues déléguées et permet les flux de client public. Suivez l’URL de consentement administrateur imprimée par le script de configuration avant la première exécution interactive. Si un lot ne contient pas de lignes AgentUser, vous pouvez omettre ClientId; les scripts utilisent alors le client PowerShell Microsoft Graph et les étendues autorisées pour celui-ci. Les opérations AgentUser nécessitent un rôle approprié, tel qu’Administrateur d’ID d’assistant. Pour plus d’informations, voir Utiliser les commandes d’authentification PowerShell de Microsoft Graph.

Préparer le fichier CSV

Commencez avec sample-bulk-onboarding.csv. Gardez chaque en-tête dans l’exemple, même si une colonne ne s’applique pas à une ligne. Laissez les valeurs non applicables vides.

L’échantillon contient des lignes représentatives pour chaque type d’objet pris en charge. Remplacez les exemples de domaines, d’identités, de propriétaires, de sponsors, de responsables et de valeurs de licence par les valeurs correspondantes de votre locataire.

Définir des relations

Les quatre premières colonnes définissent le graphe objet :

Pour créer des identités d’agent sous un blueprint existant, ajoutez une Blueprint ligne d’ancrage dont le ExistingId est l’ID de l’application blueprint. Attribuez à chaque nouvelle ligne AgentIdentity une valeur ParentKey correspondant à la valeur Key de la ligne d’ancrage.

Définissez les valeurs pour chaque type d’objet

Validez le plan d’intégration

Avant de créer des objets dans le locataire, exécutez une simulation sur l’ensemble du fichier CSV à l’aide du paramètre -WhatIf :

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

Le script valide l’ensemble du CSV avant d’effectuer une requête Microsoft Graph. Il rapporte ensemble toutes les erreurs structurelles détectées, y compris :

• En-têtes manquants ou inconnus.
• Il manque des valeurs requises.
• Clés en double.
• Types d’objets non pris en charge.
• Valeurs GUID, UPN, booléennes ou JSON invalides.
• Combinaisons ParentKey ou ExistingId non valides.
• Un parent du mauvais type d’objet.
• Cycles de dépendance.
• Des valeurs dans les colonnes qui ne s’appliquent pas au type d’objet de la ligne.

Si la validation réussit, la commande imprime le plan de dépendance. Avec -WhatIf, le script n’envoie aucune ligne d’intégration vers Microsoft Graph.

Une validation réussie confirme que le CSV passe les contrôles structurels. Cela ne confirme pas que les objets de locataire peuvent être identifiés ni que l’application dispose des autorisations nécessaires pour les créer.

Exécuter une intégration en bloc

Une fois que le -WhatIf plan semble correct, lancez l’intégration et enregistrez les journaux et le rapport agrégé :

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

Le script traite les parents avant leurs enfants tout en conservant l’ordre CSV entre des lignes non liées. Si une ligne échoue :

• Le script marque ses descendants comme SkippedDependency et ne les envoie pas à Microsoft Graph.
• Les arbres de dépendances indépendants continuent.
• La commande écrit le résumé de la console et le rapport agrégé avant de se terminer.
• La commande renvoie un code de sortie non nul si une des lignes est Failed ou SkippedDependency.

Passer en revue les résultats.

Les statuts finaux des lignes sont les suivants :

Le -OutputJsonPath paramètre en crée un A365BulkProvisioningRunReport pour toute l’exécution. Consultez le rapport pour :

• Le statut et l’identifiant résolu pour chaque ligne.
• Étapes en échec et détails de l’erreur.
• Actions de consentement de l’administrateur en attente.
• Identifiants de blueprint, d’identité, d’utilisateur et d’enregistrement créés.

Les journaux issus du script en masse, de l’orchestrateur et des scripts enfants partagent un identifiant de corrélation lorsqu’ils utilisent le même -LogPath.

Le rapport omet les secrets client Blueprint sauf si vous utilisez -IncludeBlueprintSecretsInOutputexplicitement . Le rapport n’inclut jamais d’entrées d’authentification, de jetons d’accès ou de mots de passe de certificat.

Vérifier l’intégration

Après l’exécution :

• Examinez le statut de chaque ligne et l’identifiant de l’objet résultant.
• Vérifiez que les enregistrements attendus apparaissent dans l’administration de l’Agent 365.
• Vérifiez les sponsors et propriétaires assignés.
• Si vous avez demandé la création d’utilisateurs d’assistants ou l’attribution de licences, vérifiez que ces opérations ont bien été effectuées.
• Examinez et complétez les actions de consentement de l’administrateur en attente.

Récupérer après une exécution partielle

Vous pouvez faire référence aux plans existants et aux identités des agents via les lignes d’ancrage ExistingId. Cette option n’est pas prise en charge pour les lignes agent-utilisateur ou d’enregistrement.

Corrigez l’échec et préparez un lot de réessai révisé basé sur l’état observé du tenant, plutôt que de relancer aveuglément des lignes réussies.

Troubleshooting

Utilisez le tableau suivant pour résoudre les problèmes courants d’intégration.

Pour les problèmes généraux liés au produit et à la ligne de commande, consultez le guide de dépannage de l’Agent 365. Pour signaler un problème avec ces scripts, utilisez Agent 365 DevTools issues.

Étapes suivantes

Après la prise en main de vos assistants :

• Validez votre intégration Agent 365.
• Publier un assistant dans le centre d’administration Microsoft 365.
• En savoir plus sur l’identité de l’Agent 365.