Incorporación masiva de Agent 365 con PowerShell

Utiliza la incorporación masiva de Agent 365 para reducir la configuración repetitiva al incorporar a varios agentes. Defina las identidades de los agentes, patrocinadores, propietarios y registros en un CSV revisable, valide sus relaciones antes de aprovisionar y revise los resultados en un informe consolidado. Los scripts validan el archivo completo, calculan el orden de dependencias y luego crean cada objeto usando Microsoft Graph.

Use este flujo de trabajo después de entender cómo incorporar a un solo agente con la CLI de Agent 365. Cuando tenga que incorporar a muchos agentes a la vez o repetir la incorporación de inquilinos, defina los objetos y sus relaciones en un solo archivo CSV en lugar de ejecutar el flujo de trabajo de incorporación de CLI por separado para cada agente.

Este artículo proporciona las instrucciones de incorporación masiva de extremo a extremo, desde la configuración de aplicaciones de automatización y los requisitos CSV hasta la validación, ejecución y resolución de problemas.

Important

Los scripts de incorporación masiva son scripts de automatización de PowerShell en el repositorio Agent 365 DevTools. Son independientes de la a365 interfaz de línea de comandos. La aplicación de automatización descrita en este artículo también es independiente de la aplicación cliente interactiva descrita en Registro personalizado de la aplicación cliente para Agent 365 CLI.

Qué crea el flujo de trabajo

Cada fila CSV representa un objeto. Las relaciones admitidas son:

Blueprint
  |
  +-- AgentIdentity
        |-- AgentUser
        +-- AgentRegistration
Object Purpose
Plano técnico de identidad del agente Plantilla de identidad y permisos reutilizable para uno o más agentes.
Identidad del agente Identidad Microsoft Entra utilizada por un agente individual.
Usuario del agente Cuenta de usuario opcional de Microsoft Entra para un agente que necesita recursos licenciados de Microsoft 365, como un buzón de correo.
Registro del agente Registro de inventario que hace que el agente sea detectable en las experiencias administrativas de Agent 365.

Un usuario de agente y un registro de agente son hijos independientes de la identidad de un agente. Un fallo en uno no impide que se intente el otro.

Important

Crear solo una identidad de agente no genera un registro de inventario del Agente 365. Incluye una AgentRegistration fila para cada identidad que deba aparecer en las experiencias administrativas de Agent 365. Un AgentUser es opcional y no es un requisito previo para el registro.

Para más información sobre estos objetos, véase Agent 365 identity.

Prerequisites

Antes de comenzar, asegúrese de que tiene lo siguiente:

  • Un inquilino en el que Microsoft Agent 365 está disponible.
  • PowerShell 7 o posterior.
  • Git para clonar el repositorio de DevTools.
  • El módulo PowerShell versión 2.x de Microsoft.Graph.Authentication.
  • Se requiere un Administrador de roles con privilegios o superior para el consentimiento único para los permisos de la aplicación de automatización.
  • Un patrocinador para cada nueva identidad de agente y plano técnico.
  • Propietarios, gestores y propietarios de registro que ya existen en Microsoft Entra ID.
  • Un dominio de inquilino verificado para cada nuevo nombre principal de usuario (UPN).
  • Una licencia adecuada y una ubicación de uso de dos letras si el CSV asigna una licencia a un usuario agente.

Los usuarios de los agentes solo están disponibles para los tenants que participan en el programa de vista previa de Frontier.

Instala el módulo Microsoft Graph requerido:

Install-Module Microsoft.Graph.Authentication -Scope CurrentUser

Obtén los scripts

Clona el repositorio DevTools de Agent 365 y luego cambia al directorio de registro masivo:

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

Mantén los scripts en este directorio juntos. A365-BulkOnboarding.ps1 invoca A365-AutomationOrchestrator.ps1, que invoca los scripts de provisión específicos de objetos.

Configurar la autenticación

La incorporación masiva puede ejecutarse sin supervisión mediante una aplicación de automatización propiedad del tenant o una identidad gestionada asignada por el sistema. También puede ejecutarse de forma interactiva mediante autenticación delegada.

Completa la configuración de la aplicación, el consentimiento de permisos y la configuración de la autenticación antes del primer lote. Para cada lote siguiente, prepara el CSV, valida el plan, ejecuta el onboarding y revisa los resultados.

Las ejecuciones de solo aplicación utilizan roles de aplicación otorgados al principal de servicio de la aplicación de automatización o de la identidad administrada, no al rol de administrador del operador.

Las concesiones de permisos para la identidad del runner son independientes de la configuración del GrantAdminConsent CSV, que solicita consentimiento para permisos declarados por un blueprint o la identidad del agente. Revisa cualquier acción pendiente de consentimiento en el informe de ejecución.

Important

No uses la aplicación CLI Agent 365 gestionada por Microsoft (f54280f4-395e-4ea8-9e48-bf2d4952aa14) para este flujo de trabajo. Esa aplicación es para autenticación interactiva por CLI y no debe modificarse.

La incorporación masiva admite estos métodos de autenticación de ejecutores:

Method Parameters Uso recomendado
Secreto de cliente -TenantId -ClientId -ClientSecret Pruebas o automatización de corta duración
Certificate -TenantId, -ClientId, y exactamente uno de -CertificateThumbprint, -Certificate, o -CertificatePath Automatización de la producción sin supervisión
Identidad administrada asignada por el sistema -TenantId -UseManagedIdentity Automatización alojada en un recurso de Azure
Inicio de sesión delegado interactivo -TenantId -Interactive; también incluye -ClientId para un lote que contiene filas AgentUser Incorporación basada en modelos

Las credenciales de identidad federadas y la selección de identidad gestionada asignada por el usuario no están soportadas como métodos de autenticación de runner.

Crear la aplicación de automatización

Inicia sesión de forma interactiva como Administrador Global o Administrador de Rol Privilegiado y crea una aplicación de automatización para todos los tipos de objetos soportados. Crea la aplicación sin secreto de cliente ni certificado para poder añadir y gestionar sus credenciales por separado en el centro de administración de Microsoft Entra:

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

El script crea o reutiliza la aplicación y la entidad de servicio y declara los permisos de aplicación de Microsoft Graph requeridos y los ámbitos delegados. Se espera la advertencia de que no se añadió ninguna credencial; la aplicación no puede autenticarse hasta que añades un secreto de cliente o certificado de cliente. Como el comando usa -SkipGrant, no otorga el consentimiento de administrador.

Cuando termine el comando, pide a un administrador que abra la URL del Portal impresa por el script. En el Centro de administración de Microsoft Entra, selecciona Conceder consentimiento de administrador para los permisos declarados. No empiece la incorporación en bloque masiva hasta que el consentimiento del administrador no esté completo. Puede ejecutar el script de nuevo para conciliar la aplicación y las declaraciones de permiso que faltan.

Registre el Id. de la aplicación (cliente) de la aplicación de automatización. No use el id. de objeto de la entidad de servicio cuando un comando solicite -ClientId.

Revisa los permisos de la aplicación

-Scenario Alldeclara el conjunto de estos permisos de aplicación de Microsoft Graph:

Capability Permisos de aplicación
Plano técnico AgentIdentityBlueprint.Create
AgentIdentityBlueprint.Read.All
AgentIdentityBlueprint.ReadWrite.All
AgentIdentityBlueprint.AddRemoveCreds.All
AgentIdentityBlueprintPrincipal.Create
AgentIdentityBlueprintPrincipal.Read.All
AgentIdentityBlueprintPrincipal.ReadWrite.All
Identidad del agente AgentIdentity.Create.All
AgentIdentity.Read.All
AgentIdentity.ReadWrite.All
CustomSecAttributeAssignment.ReadWrite.All
CustomSecAttributeDefinition.Read.All
Registration AgentRegistration.ReadWrite.All
AgentInstance.ReadWrite.All
Usuario del agente AgentIdUser.ReadWrite.All
User.ReadWrite.All
Organization.Read.All
Búsqueda y propiedad de directorios compartidos Application.Read.All
Application.ReadWrite.All
Directory.Read.All
User.Read.All
Group.Read.All

Los escenarios AgentUser, AgentIdentity, Registration y All también declaran ámbitos delegados para sus operaciones interactivas seleccionadas. Los ámbitos de registro se declaran por defecto y pueden ser suprimidos. Una ejecución sin supervisión que usa Auth=Same depende de los permisos de la aplicación de la tabla anterior.

Configurar campos de autenticación

Defina una única tabla hash de autenticación y reutilícela para la validación y la ejecución.

Secreto de cliente

En Centro de administración Microsoft Entra, ve a Identity>Applications>Registros de aplicaciones y selecciona la aplicación de automatización. Seleccione Certificados y secretos>Secretos de cliente>Nuevo secreto de cliente, introduzca una descripción y vencimiento y, a continuación, seleccione Agregar. Copia el valor secreto inmediatamente y guárdalo de forma segura; no vuelve a aparecer después de salir de la página. Para más información, consulte Añadir credenciales a su aplicación.

Lee el secreto del cliente como un SecureString en lugar de colocarlo directamente en la línea de comandos:

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

Los secretos del cliente son menos seguros que los certificados y deberían limitarse a pruebas o automatizaciones de corta duración. Para la automatización de producción sin supervisión, utiliza un certificado o una identidad gestionada asignada por el sistema.

Certificate

Para la automatización de la producción, obtén un certificado de la autoridad certificadora de tu organización. Para entornos de prueba, consulte Crear un certificado público autofirmado para autenticar su aplicación. En la página Certificados y secretos de la aplicación de automatización, selecciona Certificados>Cargar certificado, carga el archivo público .cer, .pem o .crt, y luego selecciona Agregar. El runner necesita acceso a la clave privada; la aplicación de automatización almacena solo el certificado público. Para más información sobre la autenticación solo por aplicación con certificado, consulte Usar autenticación solo por aplicación con el SDK de PowerShell en Microsoft Graph.

Utiliza la huella digital del certificado que contiene la clave privada:

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

Para un lote que pueda contener filas AgentUser, instala el certificado en Cert:\CurrentUser\My. Para usar un certificado de Cert:\LocalMachine\My en todos los tipos de objetos, páselo como un objeto de certificado en lugar de usar su huella digital.

Alternativamente, proporciona el certificado como un objeto X509Certificate2:

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

O cargar la clave privada desde un PFX protegido por contraseña:

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

Proporcione solo un origen de certificado. -CertificatePassword es válida solo con -CertificatePath.

Identidad administrada asignada por el sistema

Activa una identidad gestionada asignada por el sistema en el recurso de Azure que ejecuta los scripts. Concede los permisos de aplicación de Microsoft Graph necesarios de la tabla anterior directamente al principal de servicio de la identidad gestionada. Para instrucciones, consulte Conceder y revocar permisos de API a identidades gestionadas.

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

No incluyas ClientId con UseManagedIdentity. Los scripts utilizan la identidad asignada por el sistema al host y no permiten seleccionar una identidad asignada por el usuario.

Inicio de sesión delegado interactivo

Utiliza un ID de cliente controlado por el llamador para que el mismo ejemplo también soporte archivos CSV que contengan filas AgentUser:

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

Cuando proporcionas ClientId, la autorización interactiva depende de los ámbitos delegados consentidos por esa aplicación y de los roles de directorio del usuario iniciado sesión. New-A365AutomationApp.ps1 -Scenario All declara los ámbitos delegados y habilita flujos de cliente público. Sigue la URL de consentimiento del administrador impresa en el script de configuración antes de la primera ejecución interactiva. Si un lote no contiene filas de AgentUser, puede omitir ClientId; los scripts usan a continuación el cliente de PowerShell de Microsoft Graph y sus ámbitos a los que se ha dado consentimiento. Las operaciones de AgentUser requieren un rol adecuado, como Administrador de ID de Agente. Para información de contexto, consulte los comandos de autenticación de Microsoft Graph en PowerShell.

Note

La aplicación de automatización propiedad del arrendatario puede admitir tanto autenticación de solo aplicación mediante certificado o autenticación mediante secreto como inicio de sesión delegado interactivo. La autorización solo de la app utiliza los roles de la aplicación. La autorización interactiva utiliza ámbitos con privilegios delegados y los roles de directorio del usuario que ha iniciado sesión. Una identidad gestionada utiliza en cambio el propio principal de servicio del recurso de Azure.

Preparación del archivo .csv

Empezar con sample-bulk-onboarding.csv. Mantén todos los encabezados en la muestra, incluso cuando una columna no se aplique a una fila. Deja en blanco los valores no aplicables.

La muestra contiene filas representativas para cada tipo de objeto soportado. Sustituye sus dominios de ejemplo, identidades, propietarios, patrocinadores, gestores y valores de licencia por valores de tu tenant.

Definir relaciones

Las primeras cuatro columnas definen el grafo objeto:

Columna Description
ObjectType Blueprint, AgentIdentity, AgentUser o AgentRegistration.
Key Un nombre insensible a mayúsculas y minúsculas que identifica de forma única la fila dentro del CSV. No se convierte en el ID de objeto Microsoft Entra.
ParentKey El Key de la fila primaria. Las identidades de los agentes hacen referencia a una plano técnico. Los usuarios y registros de agentes hacen referencia a la identidad de un agente. Déjelo en blanco para un plano técnico.
ExistingId Hace referencia a un ID de aplicación blueprint existente o ID de objeto de identidad de agente. Una fila con este valor es un delimitador inalterado para filas secundarias. Solo se admite para Blueprint y AgentIdentity; tanto ParentKey como cada columna de configuración de objetos deben estar en blanco en esa fila.

Para crear identidades de agentes en un blueprint existente, añade una Blueprint fila de ancla cuya ExistingId sea el ID de la aplicación blueprint. Asigne a cada nueva fila AgentIdentity una ParentKey que coincida con la Key de la fila de delimitador.

Establecer valores para cada tipo de objeto

Columnas Se aplica a Requirements
DisplayName Todos los tipos de objetos Se requiere para nuevos planos técnicos, identidades de agentes y registros.
Description Blueprint, AgentRegistration Descripción opcional.
Sponsor Blueprint, AgentIdentity Necesario para la creación. Utiliza un UPN, dirección de correo electrónico, nombre para mostrar o ID de objeto. Separa varios valores con puntos y coma.
Owner Blueprint, AgentIdentity, AgentRegistration Utiliza un UPN, dirección de correo electrónico, nombre para mostrar o ID de objeto. Separa varios valores con puntos y coma. Los propietarios de planos y los propietarios de identidades pueden ser usuarios o entidades de servicio. Los propietarios del registro deben ser usuarios y son necesarios para el registro solo de la aplicación.
RequireOwnerAssignment Blueprint, AgentIdentity Establezca en true para suspender la fila si no se puede asignar un propietario.
RequiredPermissionJson, GrantAdminConsent Blueprint, AgentIdentity Declara permisos de la API y concede consentimiento opcionalmente.
SkipInheritablePermissions, NewClientSecret, KeyVaultName, KeyVaultSecretName, ManagedIdentityPrincipalId Blueprint Configura permisos y credenciales de blueprint.
Tag, CustomSecurityAttributeJson, SkipCustomSecurityAttributeValidation AgentIdentity Separe las etiquetas con punto y coma. Los atributos de seguridad personalizados requieren los permisos de Graph apropiados y el rol de directorio.
PrincipalName, MailNickname AgentUser PrincipalName es obligatorio y debe usar un dominio de inquilino verificado.
ManagerUserId, ManagerUpn AgentUser Use un solo campo de administrador, no ambos.
AssignLicense, UsageLocation, , LicenseSkuId, LicenseSkuPartNumber AgentUser Cuando AssignLicense es true, proporciona una ubicación de uso de dos letras y un campo SKU de licencia.
OwnerId, Auth AgentRegistration OwnerId acepta un ID de objeto de usuario. Auth acepta Same o Interactive; use Same para la incorporación desasistida solo para aplicaciones.
ParameterJson Todos los tipos de objetos Objeto JSON opcional para los parámetros avanzados permitidos del script. Se requieren nombres completos de parámetros. Se rechazan los parámetros de autenticación, inquilino, acción, principal, salida y registro.

Important

Un valor en una columna que no se aplica al ObjectType de la fila es un error. El validador no ignora silenciosamente valores mal colocados.

Valida el plan de incorporación

Antes de crear cualquier objeto de inquilino, ejecute el CSV completo a través de -WhatIf:

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

El script valida todo el CSV antes de crear una solicitud a Microsoft Graph. Informa de todos los errores estructurales detectados juntos, incluyendo:

  • Encabezados faltantes o desconocidos.
  • Faltan los valores requeridos.
  • Claves duplicadas.
  • Tipos de objetos no soportados.
  • Valores GUID, UPN, booleanos o JSON inválidos.
  • Combinaciones no válidas de ParentKey o ExistingId.
  • Un objeto primario del tipo de objeto incorrecto.
  • Ciclos de dependencia.
  • Valores en columnas que no se aplican al tipo de objeto de la fila.

Si la validación tiene éxito, el comando imprime el plan de dependencia. En -WhatIf, el script no envía ninguna fila de incorporación a Microsoft Graph.

La validación exitosa confirma que el CSV supera las comprobaciones estructurales. No confirma que los objetos de tenant puedan resolverse ni que la aplicación tenga los permisos necesarios para crearlos.

Note

Para la autenticación interactiva, un CSV que contiene una AgentUser fila requiere la aplicación ClientId controlada por el llamador mostrada en el ejemplo anterior. El usuario que ha iniciado sesión también debe contar con el consentimiento delegado requerido y el rol de directorio.

Ejecutar la incorporación masiva

Cuando el plan de -WhatIf esté correcto, ejecute la incorporación y guarde los registros y el informe agregado:

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

El script procesa a los padres antes que a sus hijos mientras mantiene el orden CSV entre filas no relacionadas. Si una fila falla:

  • El script marca a sus descendientes como SkippedDependency y no los envía a Microsoft Graph.
  • Los árboles de dependencias independientes continúan.
  • El comando escribe el resumen de la consola y el informe agregado antes de finalizar.
  • El comando devuelve un código de salida distinto de cero si cualquier fila es Failed o SkippedDependency.

Revisión del resultado

Los estados de la fila final son:

Status Meaning
Existing La fila hace referencia a un blueprint existente o a la identidad del agente y no se cambió.
Succeeded El objeto fue creado con éxito.
Failed El script intentó la fila, pero no la completó correctamente.
SkippedDependency El script no intentó la fila porque su primario no produjo un id. utilizable.

El -OutputJsonPath parámetro crea una A365BulkProvisioningRunReport para toda la ejecución. Revisa el informe para:

  • El estado y el ID resuelto de cada fila.
  • Pasos fallidos y detalles de errores.
  • Acciones pendientes de consentimiento del administrador.
  • Identificadores de blueprint, identidad, usuario y registro creados.

Los logs del script bulk, orchestrator y scripts hijos comparten un ID de correlación cuando usan el mismo -LogPath.

El informe omite los secretos del cliente Blueprint a menos que uses -IncludeBlueprintSecretsInOutputexplícitamente . El informe nunca incluye entradas de autenticación, tokens de acceso ni contraseñas de certificados.

Warning

No actives la salida secreta ni el registro secreto en automatizaciones rutinarias. Si una credencial aparece en una transcripción de consola, registro, informe, vale, chat o captura de pantalla, rótela inmediatamente.

Verificar la incorporación

Después de la ejecución:

  • Revisa el estado de cada fila y el ID del objeto resultante.
  • Verifica que los registros esperados aparezcan en la administración de Agent 365.
  • Comprueba los patrocinadores y propietarios asignados.
  • Si solicitaste usuarios de agente o licencias, verifica esas asignaciones.
  • Revisa y completa las acciones pendientes de consentimiento del administrador.

Recuperación tras una ejecución parcial

Warning

Antes de volver a intentarlo, inspeccione el informe y los objetos de inquilino para determinar qué existe ya. No asumas que el trabajo terminado fue revertido o que volver a ejecutar todo el CSV evita duplicados.

Puede consultar planos técnicos existentes e identidades de agentes a través de las filas de delimitador de ExistingId. Esta opción no es compatible con filas de agente-usuario o de registro.

Corrija el error y prepare un lote revisado de reintentos basado en el estado observado del inquilino, en lugar de volver a ejecutar filas correctas a ciegas.

Troubleshooting

Utiliza la siguiente tabla para resolver problemas comunes de incorporación.

Síntoma Resolution
La configuración de la aplicación de automatización devuelve un error de autorización. Inicia sesión como Administrador Global o Administrador de Rol Privilegiado. Conceder permisos de aplicación de Microsoft Graph requiere el consentimiento del administrador.
Un registro de aprovisionamiento devuelve HTTP 403. Confirme que ha creado la aplicación de automatización con -Scenario All, ha concedido sus roles de aplicación y ha adquirido un nuevo token tras el consentimiento.
La fila de un usuario agente se rechaza antes de la ejecución. Usar autenticación solo de aplicación Confirma que el UPN usa un dominio verificado. Si asignas una licencia, proporciona UsageLocation y o bien LicenseSkuId o LicenseSkuPartNumber.
No se puede resolver un propietario, patrocinador o administrador. Utiliza un UPN, dirección de correo electrónico o ID de objeto no ambiguo. Los propietarios del registro deben corresponder a usuarios.
Una fila secundaria es SkippedDependency. Corrija la fila primaria con error o no resuelta. El elemento secundario no se envió a Microsoft Graph.
Existe una identidad en Microsoft Entra pero no es visible en la administración del Agente 365. Añade una AgentRegistration fila para la identidad. La creación de una identidad por sí sola no crea el registro de inventario del Agente 365.
El validador CSV informa de un valor en una columna no soportada. Mueve el valor a una columna admitida por ese ObjectType, o deje la celda en blanco.
La asignación personalizada de atributos de seguridad devuelve HTTP 403. La aplicación de automatización necesita CustomSecAttributeAssignment.ReadWrite.All y CustomSecAttributeDefinition.Read.All. La asignación interactiva también requiere que el usuario iniciado sesión tenga el rol de Administrador de Asignación de Atributos.

Para problemas generales de producto y CLI, consulta la guía de resolución de problemas del Agente 365. Para reportar un problema con estos scripts, utiliza Incidencias de Agent 365 DevTools.

Pasos siguientes

Después de incorporar a tus agentes:

  • Darrera actualització el