Microsoft 365 / Microsoft Graph PowerShell: exportar usuarios a CSV y administrar licencias

Microsoft Graph PowerShell le permite consultar usuarios de Microsoft 365 y automatizar la administración de cuentas y licencias. Comience por instalar los módulos requeridos → conectarse con permisos de lectura → confirmar la organización objetivo → exportar usuarios a un archivo CSV (valores separados por comas). El ejercicio de solo lectura y los ejemplos de cambio de cuenta o licencia a continuación requieren permisos diferentes y tienen efectos distintos, por lo que se deben ejecutar por separado.

¿Qué es Microsoft Graph PowerShell?

Microsoft Graph es una API (Interfaz de Programación de Aplicaciones, una interfaz para la comunicación entre programas) que maneja datos de Microsoft Entra ID, Teams, SharePoint y más. El SDK de Graph para PowerShell (Kit de Desarrollo de Software) le permite usar esta API mediante comandos de PowerShell. El nombre actual del servicio de directorio, previamente referido como Azure Active Directory o Azure AD en documentos antiguos, es Microsoft Entra ID.

Instalar Graph no significa que pueda usar todos los comandos de administración de Microsoft 365. Algunas tareas, como los comandos de administración específicos de Exchange Online, requieren módulos y conexiones separados. Este artículo cubre Autenticación Delegada Interactiva utilizando el módulo Microsoft Graph v1.0. La autenticación solo para aplicaciones en tareas programadas sin supervisión requiere consideraciones de diseño separadas, como permisos de aplicación y certificados, y es diferente de ejecutar tareas programadas usando los mismos ejemplos de inicio de sesión de usuario.

Requisitos e Instalación del Módulo

Microsoft recomienda PowerShell 7 o posterior. Realice los siguientes ejercicios en un entorno de PowerShell 7 compatible. Windows PowerShell 5.1 requiere .NET Framework, PowerShellGet y otros prerrequisitos separados, y los módulos instalados en una versión no se instalan automáticamente en otra versión. Primero, verifique los requisitos de instalación del SDK.

  1. Abra PowerShell en un PC de administración aprobado por la organización. Verifique su versión con $PSVersionTable.PSVersion.
  2. En el centro de administración de Microsoft Entra, verifique el ID del inquilino objetivo en Entra ID → Overview. Esto es especialmente importante si su cuenta tiene acceso a múltiples organizaciones.
  3. Confirme el consentimiento del administrador para los permisos de Graph y su propio rol administrativo. Utilice la cuenta de empresa o escuela de su organización en lugar de una cuenta personal de Microsoft regular.
  4. Cree una carpeta restringida para almacenar los archivos de resultados. Dado que la lista de usuarios contiene nombres y direcciones de cuenta, no use almacenamiento público ni carpetas web públicas.

Para instalar solo los módulos necesarios para el alcance del usuario actual, ejecute de la siguiente manera. Si aparece un mensaje de confirmación de instalación, verifique el repositorio y los paquetes. También es posible instalar el módulo completo Microsoft.Graph, pero para este ejercicio, los submódulos a continuación son suficientes.

Install-Module -Name Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions -Scope CurrentUser -Repository PSGallery

Después de la instalación, verifique las versiones disponibles y los nombres de los comandos utilizando el siguiente comando. En este paso, no se conecta a los datos de la organización.

Get-Module -ListAvailable Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions | Select-Object Name,Version
Get-Command Connect-MgGraph,Get-MgUser,Get-MgSubscribedSku,Set-MgUserLicense

Si los módulos o scripts están bloqueados debido a la política de ejecución, primero verifique la sección de política de ejecución. No trate un error de política como un problema como un error de permiso 403.

Distinguiendo permisos de conexión y roles de administrador

La autenticación delegada es un método que funciona en nombre del usuario que ha iniciado sesión. -Scopes es el alcance de permisos de Graph solicitado por la aplicación, y también debe cumplir con el rol/alcance del objetivo del administrador que ha iniciado sesión y con el consentimiento del administrador. Simplemente escribir un nombre en -Scopes no aprueba automáticamente ese permiso ni crea un rol de administrador.

Tareas Permisos de Graph solicitados en el ejemplo Comprobaciones adicionales
Ver la lista de usuarios y los atributos especificados User.Read.All Consentimiento del administrador y limitación de atributos a consultar
Consultar SKUs de suscripción y licencias de usuario LicenseAssignment.Read.All Roles compatibles con la API, como Lectores del Directorio
Crear usuarios en la nube User.Create Consentimiento del administrador, rol de gestión de usuarios y ámbito objetivo
Asignar y revocar licencias LicenseAssignment.ReadWrite.All Roles compatibles, como Administrador de Licencias

Para la práctica de lectura, no es necesario solicitar permisos de modificación de grupos o permisos completos de escritura en el directorio juntos. Se pueden verificar los permisos delegados frente a los permisos de aplicación y los requisitos de consentimiento de administrador en Referencia de permisos de Microsoft Graph.

Para probar comandos de consulta individuales, conéctese como se muestra a continuación. El ID de inquilino que ingrese debe ser el valor real confirmado en su organización, y después de iniciar sesión, verifique Account·TenantId·Scopes. El método de inicio de sesión puede usar un navegador o la ventana de autenticación de Windows según la versión instalada y el entorno.

$tenantId = Read-Host 'ID del inquilino de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,AuthType,Scopes

-ContextScope Process limita el contexto de autenticación al proceso actual de PowerShell. Cuando se llama a Connect-MgGraph sin ámbitos explícitos, inspeccione el contexto real en lugar de asumir que su permiso siempre es User.Read. Para cambiar cuentas o ámbitos, ejecute Disconnect-MgGraph y reconéctese con los ámbitos requeridos. Consulte la Guía de autenticación de Graph PowerShell.

Ejemplo completo de búsqueda de usuario y guardado en CSV

Get-MgUser -All recupera continuamente listas de usuarios devueltas en páginas. Sin embargo, esto no significa que reciba automáticamente todas las propiedades. Select-Object * solo expande las propiedades de los objetos ya recibidos, y los valores no incluidos en la devolución predeterminada deben solicitarse al servidor con -Property. Esta diferencia se explica en Descripción de Get-MgUser.

Guarde el siguiente código completo como UTF-8 con m365-users-report.ps1. El script lee información de usuarios, crea un CSV con marcas de tiempo en la misma carpeta y desconecta la sesión. No cambia cuentas ni licencias. Si ha realizado prácticas de conexión previas, primero termínelas con Disconnect-MgGraph y luego ejecute esto.

param(
    [Parameter(Mandatory)]
    [Guid]$TenantId
)

$ErrorActionPreference = 'Stop'
$connected = $false
$file = Join-Path $PSScriptRoot ("m365-users-{0}.csv" -f (Get-Date -Format 'yyyyMMdd-HHmmss'))

try {
    Connect-MgGraph -TenantId $TenantId.ToString() -Scopes 'User.Read.All' -ContextScope Process -NoWelcome
    $connected = $true
    $context = Get-MgContext
    if ($context.TenantId -ne $TenantId.ToString()) {
        throw 'El inquilino conectado no coincide con el solicitado.'
    }

    $properties = 'Id','DisplayName','UserPrincipalName','Mail','AccountEnabled','UsageLocation','AssignedLicenses'
    $users = @(Get-MgUser -All -Property $properties)
    if ($users.Count -eq 0) {
        throw 'No se devolvieron usuarios. Compruebe la conexión y los permisos.'
    }
    $report = @($users | Select-Object Id,DisplayName,UserPrincipalName,Mail,AccountEnabled,UsageLocation,
        @{Name='AssignedSkuCount';Expression={ @($_.AssignedLicenses | Where-Object { $null -ne $_ }).Count }})

    $report | Export-Csv -Path $file -NoTypeInformation -Encoding utf8BOM -NoClobber
    Write-Host ("Guardado: {0} / Número de usuarios: {1}" -f $file, $report.Count)
    $report | Select-Object -First 5 | Format-Table DisplayName,UserPrincipalName,AssignedSkuCount -AutoSize
}
finally {
    if ($connected) {
        Disconnect-MgGraph -ErrorAction SilentlyContinue | Out-Null
    }
}

Después de moverse a la carpeta donde se encuentra el archivo en PowerShell, ejecute de la siguiente manera. Ajuste la ruta del archivo a la ubicación real donde se guardó y pegue el ID de inquilino de su organización en el campo de entrada.

$targetTenant = Read-Host 'ID del inquilino de destino'
.\m365-users-report.ps1 -TenantId $targetTenant

Si tiene éxito, se mostrarán en pantalla la ruta del CSV y el número de usuarios, y se mostrarán los primeros cinco usuarios en la pantalla. Compare el número de filas en el archivo con el número de usuarios en la pantalla, y verifique el nombre para mostrar, la dirección de inicio de sesión, la ubicación de uso y la licencia de una cuenta de prueba conocida con el centro de administración. AssignedSkuCount representa el número de SKU de productos asignados, no el número de servicios individuales o plazas de licencia adquiridas.

Incluso si hay usuarios con un Mail vacío, no asuma inmediatamente un fallo de consulta. El nombre de inicio de sesión, UserPrincipalName, y la dirección de correo electrónico son atributos diferentes. Incluso si AccountEnabled es verdadero, el inicio de sesión real o el uso del servicio pueden estar restringidos debido a licencias, políticas o evaluaciones de riesgo. No concluya a partir de este informe únicamente que un usuario ha iniciado sesión recientemente o está realizando trabajo normalmente.

Si no se devuelven resultados o falla la generación de CSV, no lo marque como completado. Verifique los permisos de la ruta de salida, archivos con el mismo nombre, bloqueos de archivos y mensajes de error. Dado que el informe refleja los resultados de la consulta en el momento de la ejecución, si las cuentas han cambiado, ejecútelo nuevamente para comparar, y gestione los archivos anteriores de acuerdo con la política de retención de su organización.

Consultando productos con licencia y asignaciones de usuarios

SKU (Stock Keeping Unit, identificador de producto) es la unidad utilizada aquí para distinguir productos con licencia. SkuPartNumber es la cadena de identificación del producto, y SkuId es el identificador único global del producto (GUID) usado en comandos de Graph. Al cambiar la asignación de un usuario, distíngalo para que no ingrese el ID del objeto de suscripción o el ID del plan de servicio en lugar del ID de SKU.

Todo el script CSV se desconecta al final, por lo que al ejecutar los comandos individuales a continuación, reconéctese cada vez. Además de los permisos de lectura, se requiere el rol compatible con esa operación para consultar SKUs de suscripción. Consulte Roles y Permisos para la API de Consulta de SKU de Suscripción.

$tenantId = Read-Host 'ID del inquilino de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All','LicenseAssignment.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
Get-MgSubscribedSku -All | Select-Object SkuPartNumber,SkuId,CapabilityStatus,ConsumedUnits,@{Name='EnabledUnits';Expression={$_.PrepaidUnits.Enabled}}

$userId = Read-Host 'Nombre principal de usuario (UPN) o ID de objeto que desea consultar'
Get-MgUserLicenseDetail -UserId $userId -All | Select-Object SkuPartNumber,SkuId,ServicePlans

ConsumedUnits es el número de licencias consumidas, y PrepaidUnits.Enabled es la cantidad de unidades disponibles. Dado que puede haber estados suspendidos, de advertencia y condiciones del producto, no interprete inmediatamente la diferencia simple como la cantidad facturada o los plazas de licencia restantes para todos los productos. Los detalles reales de compra y facturación deben confirmarse por separado a través del Procedimiento de Suscripción, Facturación y Reconciliación de Cantidad de Licencias.

Get-MgUserLicenseDetail incluye licencias asignadas directamente y heredadas de grupos. No se puede distinguir la causa de la asignación solo con este resultado. Para asignaciones basadas en grupos, verifique además el centro de administración o la información del estado de asignación. En Detalles de Licencias de Usuario API, también puede verificar permisos delegados y roles compatibles.

Ejecute las operaciones de cambio de usuario y licencia por separado.

El siguiente ejemplo muestra una operación que modifica datos organizacionales. No lo ejecute en lote inmediatamente después del informe de lectura; vuelva a conectarse con los permisos necesarios después de preparar un usuario de prueba aprobado y los registros antes de los cambios. La opción -WhatIf a continuación le permite previsualizar la operación que desea ejecutar y no es una prueba simulada que verifica todas las validaciones del servidor, permisos y condiciones de la licencia.

Cree un usuario de prueba en la nube.

Utilice este método solo para usuarios gestionados en la nube. En una organización sincronizada, compruebe primero si las cuentas deben crearse en el directorio de origen. Elija un nombre principal de usuario (UPN, el nombre de inicio de sesión) único dentro de un dominio verificado en el inquilino y una contraseña temporal que cumpla la política. Crear un usuario miembro es diferente de invitar a un usuario externo. Consulte los requisitos y permisos de la API de creación de usuarios, incluido el permiso mínimo User.Create, y confirme el rol administrativo y su ámbito.

Disconnect-MgGraph
$tenantId = Read-Host 'ID del inquilino de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Create','User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes

$upn = Read-Host 'UPN del usuario de prueba que desea crear (dominio verificado)'
$nickname = Read-Host 'Alias de correo (por ejemplo, graph-test01)'
$securePassword = Read-Host 'Contraseña temporal que cumpla la política' -AsSecureString
$params = @{
    AccountEnabled = $true
    DisplayName = 'Usuario de prueba de Graph'
    UserPrincipalName = $upn
    MailNickname = $nickname
    PasswordProfile = @{
        Password = [System.Net.NetworkCredential]::new('', $securePassword).Password
        ForceChangePasswordNextSignIn = $true
    }
}
try {
    New-MgUser -BodyParameter $params -WhatIf
}
finally {
    $params.PasswordProfile.Password = $null
    Remove-Variable securePassword
}

Después de verificar las entradas y los objetivos, para realmente crear el usuario, elimine -WhatIf del código y ejecútelo nuevamente. No codifique contraseñas en cadenas de línea de comando o archivos de script. Dado que las solicitudes del SDK requieren valores de contraseña en texto plano, no use la salida de depuración ni el registro del cuerpo de la solicitud para esta tarea, y entregue contraseñas temporales a través de los canales aprobados por la organización.

Después de la creación, verifique la cuenta nuevamente usando Get-MgUser -UserId $upn -Property Id,DisplayName,UserPrincipalName,AccountEnabled. Simplemente crear un usuario no completa automáticamente las licencias de la aplicación, los buzones de correo o la membresía en grupos. Eliminar una cuenta de prueba también requiere revisión de datos similar a la de eliminar una cuenta empresarial. Consulte procedimientos de baja y entrega de datos, luego revise y organice el alcance objetivo y recuperable en el centro de administración.

Recuperar licencias asignadas directamente

Antes de recuperar, verifique el usuario, el producto, si fue asignado directamente o en grupo, y los requisitos de retención de datos. En este ejemplo, -RemoveLicenses pasa a un arreglo de cadenas de ID de SKU, pero no incluye una tabla hash en formato @{SkuId=...}. Use -AddLicenses @() junto cuando no haya productos adicionales para agregar. Verifique la sintaxis Set-MgUserLicense.

Disconnect-MgGraph
$tenantId = Read-Host 'ID del inquilino de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'LicenseAssignment.ReadWrite.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes

$userId = Read-Host 'UPN o ID del usuario de prueba al que retirará la licencia'
$skuId = [Guid](Read-Host 'SkuId verificado de la licencia que desea retirar')
Set-MgUserLicense -UserId $userId -AddLicenses @() -RemoveLicenses @($skuId.ToString()) -WhatIf

Realice los cambios únicamente después de aprobar y comprobar el destino, quitando -WhatIf. Necesita tanto el consentimiento para LicenseAssignment.ReadWrite.All como un rol admitido, por ejemplo, Administrador de licencias. Una licencia heredada de un grupo requiere revisar la asignación del grupo; no intente resolverla solo con la retirada directa del usuario. Consulte los permisos, roles y formato de solicitud de la API de asignación de licencias.

Después del cambio, reconéctese con los permisos de lectura necesarios y compare los detalles de la licencia con el centro de administración. Durante la reversión, necesita verificar los plazas de licencia restantes, las ubicaciones de uso y los planes de servicio previamente deshabilitados para reasignarlos a la configuración original. No asuma que volver a adjuntar la licencia deshará todas las eliminaciones de datos ejecutadas previamente. Es importante completar la conservación y la entrega de datos antes de recuperar.

Compruebe la política de ejecución de Windows y la reversión

Las políticas de ejecución son condiciones para ejecutar scripts y módulos. Si ocurre un error de bloqueo en Windows, compruebe la política efectiva y los valores por alcance.

Get-ExecutionPolicy
Get-ExecutionPolicy -List

Cambie la política del usuario actual solo si la organización lo permite y el cambio resulta necesario. Registre antes su valor y evalúe RemoteSigned. Si la configuración actual ya permite el trabajo, consérvela. Si las directivas de grupo MachinePolicy o UserPolicy tienen prioridad, consulte al responsable y no las eluda.

$previousUserPolicy = Get-ExecutionPolicy -Scope CurrentUser
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Get-ExecutionPolicy -List

Para restaurar el valor original al terminar, ejecute el siguiente comando en la misma sesión. En una ventana nueva, use el valor real registrado anteriormente. RemoteSigned no implica que todo código descargado sea fiable. Consulte el ámbito y la prioridad de las políticas de ejecución.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy $previousUserPolicy

Errores comunes y terminación de tareas

Síntomas Secuencia de Verificación
Comando No Reconocido Verifique la versión de PowerShell en ejecución y la ubicación de instalación del módulo. Get-MgUser está en Microsoft.Graph.Users. Use Get-Command para localizar el comando y distinguir entre errores de instalación e importación.
403 o Privilegios Insuficientes Verifique la cuenta conectada, inquilino, permisos, consentimiento de administrador y roles compatibles con la API. No agregue permisos de escritura completos por defecto.
No se Puede Encontrar el Usuario u Objeto Verifique la organización y el UPN/ID del objeto, y el estado de eliminación/sincronización. Asegúrese de que el nombre de la cuenta no sea de un inquilino diferente.
La propiedad está vacía Distinguir si la propiedad fue solicitada con -Property, si la cuenta realmente tiene un valor y si la propiedad requiere permisos separados.
Inicio de sesión bloqueado Registrar códigos de error y marcas de tiempo, y verificar el acceso condicional, la autenticación multifactor (MFA), los métodos de autenticación permitidos y los registros de inicio de sesión. No deshabilite las políticas de seguridad para un inicio de sesión exitoso.

Registrar la versión de instalación, los errores detallados de los comandos, el ID de solicitud y la hora de ocurrencia juntos puede ayudar con la reproducción y las solicitudes de soporte. Incluso al usar el método en diagnóstico de errores de Graph PowerShell, no comparta registros que contengan tokens, contraseñas o información personal tal cual.

Después de terminar los ejercicios de comandos individuales, desconéctese y revise la ubicación de almacenamiento de los archivos de resultados. Cerrar sesión es diferente de deshacer los cambios de cuenta o licencia que ya se hayan realizado.

Disconnect-MgGraph