Powershell

Get-MsolUser: alternativa con Get-MgUser en Microsoft 365

Llave de acceso dibujada en línea crema sobre un fondo violeta con un círculo tonal

Si has llegado a un tutorial que utiliza Get-MsolUser, no conviene reconstruir el procedimiento instalando herramientas antiguas sin revisar su situación. Microsoft recomienda migrar los módulos Azure AD y MSOnline a Microsoft Graph PowerShell. Para consultar usuarios, el punto de partida habitual es Get-MgUser, pero la migración también exige revisar los permisos, las propiedades y la forma de autenticarse.

Esta guía transforma una consulta de usuarios de Microsoft 365 en un procedimiento de lectura con Microsoft Graph. Los ejemplos no crean cuentas, no cambian licencias y no deshabilitan usuarios. Debes ejecutarlos en un tenant donde tengas autorización y sustituir los identificadores de ejemplo por los correspondientes a tu organización.

Qué cambia al pasar de Get-MsolUser a Get-MgUser

El cambio de nombre del comando es solo una parte del trabajo. Un script antiguo puede dar por hecho que recibe ciertas propiedades, que recupera todos los usuarios o que una conexión previa autoriza cualquier operación. Con Graph debes comprobar cada una de esas suposiciones y ajustar la consulta a los datos que necesitas.

Microsoft publica una guía de migración desde los módulos antiguos. Úsala para identificar equivalencias y limitaciones, no como una invitación a sustituir automáticamente palabras en todos tus scripts. Guarda una lista de los informes que utilizas y empieza por una consulta pequeña que puedas comparar con un usuario conocido.

Necesidad del scriptEnfoque con GraphComprobación necesaria
Consultar un usuarioGet-MgUser -UserIdIdentificador y tenant correctos
Listar una muestraGet-MgUser -Top 10No confundir la muestra con el directorio completo
Solicitar más campos-PropertyPermisos y disponibilidad de cada propiedad
Preparar un informeSeleccionar columnas y exportar el resultadoAlcance, datos personales y destino del archivo

1. Comprueba la versión de PowerShell y el módulo

Abre PowerShell y comprueba qué edición estás utilizando. Conviene hacer esta revisión en la misma consola desde la que ejecutarás el script, porque un equipo puede tener Windows PowerShell y PowerShell 7 instalados al mismo tiempo. Que un módulo aparezca en una consola no demuestra que esté disponible en la otra.

$PSVersionTable.PSVersion
$PSVersionTable.PSEdition
Get-Module Microsoft.Graph.Users -ListAvailable

Microsoft recomienda PowerShell 7 o posterior en su documentación de instalación del SDK. Además, en septiembre de 2026 anunció una transición de mantenimiento de los módulos Graph hacia PowerShell 7. Esa transición no significa que todas las instalaciones antiguas dejen de funcionar de inmediato; sí es un motivo para preparar un entorno actualizado y revisar la versión del módulo antes de migrar una automatización.

Para estos ejemplos basta el módulo de usuarios y sus dependencias. Si no está instalado y tu organización permite instalarlo desde PowerShell Gallery, utiliza el siguiente comando. CurrentUser limita la instalación a tu perfil; sigue las políticas de software de tu organización y revisa cualquier confirmación del repositorio.

Install-Module Microsoft.Graph.Users -Scope CurrentUser
Import-Module Microsoft.Graph.Users
Get-Command Get-MgUser

2. Conecta con permisos de lectura

Los ejemplos utilizan autenticación delegada: una persona inicia sesión y la consulta se realiza con los permisos efectivos de esa sesión. El consentimiento de un permiso y el acceso de la cuenta son cuestiones que debes revisar con quien administre el tenant. No elijas permisos de escritura solo para evitar un error de lectura.

Connect-MgGraph -Scopes 'User.Read.All' -ContextScope Process
Get-MgContext | Select-Object TenantId, Account, AuthType, Scopes

La referencia de autenticación de Microsoft Graph PowerShell describe las modalidades de conexión. En este procedimiento se solicita un permiso de lectura de usuarios y se comprueba el contexto antes de consultar. Si ves un tenant o una cuenta distintos de los esperados, detente y corrige la sesión.

No copies tokens de acceso en el artículo, en un ticket público o en un archivo compartido. Para una tarea programada tendrás que diseñar una autenticación de aplicación y su gestión de credenciales; no conviertas una sesión interactiva en una automatización guardando la contraseña de una persona dentro del script.

3. Consulta primero un usuario conocido

Sustituye la dirección de ejemplo por el nombre principal de usuario de una cuenta que puedas revisar. Seleccionar una cuenta conocida facilita detectar que estás consultando el tenant equivocado, que has escrito mal el identificador o que estás interpretando una propiedad de forma incorrecta.

$identificador = 'usuario@contoso.onmicrosoft.com'
Get-MgUser -UserId $identificador -Property Id,DisplayName,UserPrincipalName,Mail |
    Select-Object Id,DisplayName,UserPrincipalName,Mail

La dirección contoso.onmicrosoft.com es un ejemplo. No esperes que el comando devuelva una cuenta real de tu organización sin cambiarla. Un campo Mail vacío tampoco demuestra que el usuario no exista: primero identifica la cuenta por su Id o por su nombre principal y después interpreta cada campo según su función.

La referencia de Get-MgUser explica que la respuesta predeterminada contiene un subconjunto de propiedades. Por eso, si tu informe necesita un campo adicional, debes solicitarlo y comprobar sus requisitos. Usar Select-Object por sí solo no obliga al servidor a entregar una propiedad que no se pidió.

4. Diferencia una muestra de un listado completo

Durante la migración, trabaja con una muestra pequeña y columnas concretas. Es más fácil revisar diez filas que comparar una exportación completa desde el primer intento. La consulta siguiente pide diez usuarios para comprobar la forma de los resultados; no pretende contar todas las cuentas del tenant.

Get-MgUser -Top 10 -Property Id,DisplayName,UserPrincipalName |
    Select-Object Id,DisplayName,UserPrincipalName

Cuando el objetivo sea recuperar todas las páginas, revisa la opción -All y el tamaño esperado del directorio. No la añadas por costumbre a una consulta que solo necesita un usuario. Define también qué significa «todos» para tu informe: usuarios habilitados, cuentas invitadas, un departamento o un conjunto de identificadores pueden ser alcances distintos.

Documenta el criterio junto al informe. Un CSV llamado «usuarios» sin fecha, filtro ni tenant resulta ambiguo aunque los comandos sean correctos. La calidad del resultado depende tanto de la definición del conjunto como de que la conexión a la API haya funcionado.

5. Exporta solo los campos que necesitas

Para comprobar la exportación puedes reutilizar la muestra anterior. El siguiente ejemplo escribe un archivo en la carpeta temporal de tu perfil y utiliza un nombre con fecha y hora para distinguir las ejecuciones. Es un CSV de prueba con diez resultados como máximo, no una copia completa del directorio.

$muestra = Get-MgUser -Top 10 -Property Id,DisplayName,UserPrincipalName
$rutaInforme = Join-Path $env:TEMP ('usuarios-muestra-{0}.csv' -f (Get-Date -Format 'yyyyMMdd-HHmmss'))
$muestra |
    Select-Object Id,DisplayName,UserPrincipalName |
    Export-Csv -LiteralPath $rutaInforme -NoTypeInformation -Encoding utf8
$rutaInforme

Antes de compartir el archivo, comprueba que sus columnas responden a la finalidad prevista y que el destinatario necesita esos datos. No exportes propiedades adicionales solo porque estén disponibles. Si el informe debe guardarse en una carpeta compartida, revisa los permisos de archivos y carpetas en Windows antes de cambiar la ruta.

Cómo separar los errores de módulo, conexión y autorización

Si Get-MgUser no se reconoce, comprueba el módulo y la consola antes de investigar la cuenta del usuario. Si el comando existe pero pide conexión, revisa el contexto de Graph. Si la respuesta indica falta de autorización, comprueba los permisos y el consentimiento; reinstalar el módulo no concede derechos sobre el tenant.

Cuando aparezca un error de red, conserva su texto, la hora y el destino solicitado. Comprueba la conectividad desde el mismo equipo y contexto que ejecuta la consulta. La guía de Test-NetConnection en PowerShell ayuda a distinguir una conexión TCP de la respuesta de una aplicación: alcanzar el puerto 443 no demuestra que la autenticación de Graph sea correcta.

Tampoco mezcles herramientas de directorios distintos. Get-ADUser consulta Active Directory con su módulo correspondiente; Get-MgUser trabaja con Microsoft Graph. Si tu problema es que Get-ADUser no se reconoce, resuélvelo en ese entorno en lugar de asumir que los dos cmdlets son intercambiables.

Qué comprobar cuando el informe antiguo y el nuevo no coinciden

Antes de atribuir una diferencia al cambio de módulo, compara el alcance de las dos ejecuciones. Un informe generado ayer puede contener cuentas que hoy se han modificado, y una consulta filtrada no es equivalente a un listado sin filtro. Anota la hora de cada ejecución y comprueba que ambas corresponden al mismo tenant.

Después revisa una cuenta concreta por su identificador. Compara el significado de las columnas, no solo su etiqueta: una dirección de correo y un nombre principal de usuario no deben tratarse como si siempre fueran iguales. Si el sistema que recibe el informe utiliza una columna como clave, documenta esa decisión antes de sustituirla por otra.

Finalmente, conserva la distinción entre «valor vacío», «propiedad no solicitada» y «consulta fallida». Convertir las tres situaciones en una celda en blanco puede ocultar problemas. Un procedimiento de migración debe explicar qué caso ha ocurrido y qué dato permite comprobarlo.

Lista de revisión antes de sustituir el script antiguo

Compara una muestra del resultado nuevo con las necesidades del proceso que utilizaba Get-MsolUser. Comprueba identificadores, nombres de columnas, filtros, páginas recuperadas y tratamiento de campos vacíos. Revisa también qué hará el sistema que consume el CSV si cambias el orden de las columnas o la codificación.

  • La versión de PowerShell y del módulo están identificadas.
  • La cuenta y el tenant se han comprobado antes de consultar.
  • Los permisos solicitados corresponden a operaciones de lectura.
  • Se distingue una muestra de una consulta completa.
  • Las propiedades necesarias se solicitan y se interpretan explícitamente.
  • El archivo de salida contiene solo los datos requeridos y tiene un destino apropiado.

Al terminar la sesión interactiva de prueba, puedes cerrarla con Disconnect-MgGraph. Conserva el procedimiento validado y sus supuestos para que otra persona pueda repetir la consulta sin depender de una consola que quedó abierta.

La referencia de esta revisión es la documentación de Microsoft consultada en octubre de 2026, incluido el anuncio de transición hacia PowerShell 7. Los ejemplos se presentan para revisión y adaptación; no se han ejecutado contra un tenant del lector ni garantizan que su organización haya concedido los permisos necesarios.