Cómo conseguir usuarios de Azure AD con PowerShell

A partir de diciembre de 2022, necesitaremos usar el cmdlet Get MgUser para obtener y exportar nuestros usuarios de Azure AD.

Get-MgUser es parte del SDK de Microsoft Graph para PowerShell. Nos permite interactuar con todos los Servicios de Microsoft a través de un único punto final.

Todas las cuentas de usuario de su inquilino de Microsoft 365 se almacenan en Azure Active Directory.

Podemos administrarlos a través del centro de administración o Azure Portal, pero a veces es más conveniente PowerShell.

En este artículo, voy a explicar cómo podemos usar el cmdlet Get MgUser para buscar y recuperar información de usuario de Azure AD.

También he creado un script completo que te permite exportar todos tus usuarios a CSV, que encontrarás al final del artículo.

Primeros pasos con Get-MgUser

Antes de que podamos comenzar, asegúrese de haber instalado Microsoft Graph Module en PowerShell.

En este artículo, puede encontrar una guía completa sobre cómo instalar el módulo.

El cmdlet Get MgUser le permite buscar y extraer información de usuario de Azure Active Directory.

Hay un par de parámetros que podemos usar para encontrar o filtrar a los usuarios:

  • ID de usuario – Devolver usuario específico basado en UPN u ObjectID
  • Filtrar – Recuperar múltiples objetos basados ​​en una consulta oDate v3
  • Búsqueda – Obtener todos los usuarios que coincidan con la cadena de búsqueda
  • Parte superior – Devolver n número de resultados
  • Todos – Devolver todos los resultados (por defecto se devuelven los primeros 100 elementos)

Es bueno saber que el cmdlet devuelve solo los primeros 100 resultados de forma predeterminada.

Así que asegúrese de usar el -all parámetro para obtener todos los resultados cuando sea necesario.

Entonces, el primer paso es conectar Microsoft Graph con el alcance correcto. Solo vamos a recuperar datos de usuario, por lo que podemos usar el User.Read.All alcance.

Connect-MgGraph -Scopes 'User.Read.All'

Para probar si el cmdlet funciona, simplemente puede obtener todos los usuarios de su Azure Active Directory con el siguiente cmdlet:

Get-MgUser -All

Para obtener un solo usuario, podemos usar el ID de usuario del usuario. Puede ser el UserPrincipalName del usuario o la identificación del usuario real:

# Get the user by the UserPrincipalName
Get-MgUser -UserId [email protected]

# Get the user by the actual id:
Get-MgUser -UserId 7a3b301d-0462-41b6-8468-19a3837b8ad1

Uso de filtros con Get-MgUser

Al igual que con el cmdlet Get-AzureAduser, podemos filtrar los usuarios. El filtro se basa en la consulta oDate v3, pero no se admiten todos los operadores.

Solo podemos usar los siguientes operadores para filtrar a los usuarios:

Operador Descripción Ejemplo
equivalente Igual a jobtitle eq ‘Asistente de marketing’
y Y puesto de trabajo eq ‘Reclutador’ y puesto de trabajo eq ‘hr’
o O puesto de trabajo eq ‘Reclutador’ o puesto de trabajo eq ‘hr’
comienza con La cadena comienza con comienza con (título del trabajo, ‘recr’)
Filtros Get-MgUser

Es importante que envuelva la consulta de filtro entre comillas dobles y la cadena que desea filtrar entre comillas simples. S

olo cuando filtra en un booleano, no necesita poner comillas alrededor de la declaración verdadera o falsa.

Así que echemos un vistazo a un par de ejemplos usando el -filter parámetro.

Para encontrar un usuario por el nombre para mostrar, podemos especificar el nombre completo del usuario o usar el operador beginWith.

Tenga en cuenta que no podemos usar comodines o el -like operador aquí.

# Find the user based on the full name
Get-MgUser -Filter "DisplayName eq 'Adele Vance'"

# Find the user by the first part of the name
Get-MgUser -Filter "startsWith(DisplayName, 'A')"
Filtro Get-MgUser
Buscar usuario por nombre

El mismo método también se puede usar para obtener todos los usuarios con el título de trabajo «Asistente de marketing», por ejemplo:

Get-MgUser -Filter "jobtitle eq 'Marketing Assistant'"

Para obtener por ejemplo solo las cuentas de usuario habilitadas con el cmdlet Get-MgUser podemos usar el siguiente comando:

Get-MgUser -Filter 'accountEnabled eq true' -All

Tenga en cuenta que he agregado el parámetro -all. De forma predeterminada, el cmdlet Get MgUser solo devuelve los primeros 100 resultados.

Al agregar el -all parámetro obtenemos todos los resultados devueltos.

También podemos filtrar en múltiples condiciones, usando and o or en la consulta de filtro:

Get-MgUser -Filter "department eq 'Marketing' and jobtitle eq 'Manager'"

Además del parámetro de filtro, también podemos usar el -Search parámetro para encontrar usuarios.

El parámetro requiere una propiedad en la que desea buscar y un valor. También tendrá que configurar el -consistencylevel a eventual.

La ventaja del parámetro -search es que nos permite buscar en cualquier parte del valor.

Entonces, por ejemplo, si queremos buscar en una parte del nombre, podemos usar:

Get-MgUser -Search 'DisplayName:van' -ConsistencyLevel eventual
Parámetro de búsqueda Get-MgUser

Además, tenga en cuenta que deberá envolver la consulta de búsqueda entre comillas simples.

Puede usar el parámetro de búsqueda en prácticamente todos los campos que devuelve el cmdlet Get-MgUser.

Combinar búsqueda y filtro en Get MgUser

También podemos combinar los parámetros -search y -filter en un solo comando. Esto nos permite buscar un nombre o cargo entre las cuentas habilitadas solo por ejemplo:

Get-MgUser -Filter 'accountEnabled eq true' -Search 'DisplayName:van' -ConsistencyLevel eventual

Selección de propiedades para devolver

Al usar el cmdlet Get-MgUser, probablemente haya notado que no devuelve muchas propiedades de manera predeterminada.

La mayoría de los campos están vacíos o contienen el valor Microsoft.Graph.PowerShell.Modelos. seguido de un nombre de entidad. Entonces, ¿cómo recuperamos estos datos?

Hay dos parámetros que podemos usar para obtener la información que necesitamos, -property y -expandproperty.

los -property El parámetro es como el select que podemos canalizar detrás del cmdlet.

La única diferencia es que con select, Microsoft Graph devuelve todos los datos y los filtra en PowerShell.

Get-MgUser -UserId [email protected] | Select DisplayName,BusinessPhones,Mail,JobTitle

DisplayName BusinessPhone     Mail                           JobTitle
----------- -------------     ----                           --------
Adele Vance {+1 425 555 0109} [email protected] Retail Manager

Cuando usa el parámetro de propiedad, Microsoft Graph solo devuelve los datos que necesita.

Especialmente cuando se trabaja con muchos registros, esto será más rápido que usar select.

Get-MgUser -UserId [email protected] -Property DisplayName,BusinessPhones,Mail,JobTitle | fl

Si envía los resultados a una lista, verá que solo los campos que ha seleccionado con el parámetro de propiedad contienen datos.

Expansión de Microsoft.Graph.PowerShell.Models

Al ver las propiedades de un usuario, es posible que haya notado que algunas de ellas contienen el valor Microsoft.Graph.PowerShell.Models seguido de un nombre de recurso. Estos modelos (o recursos) son relaciones del tipo de recurso que está viendo.

Estas relaciones deberían permitirnos ver fácilmente los datos relacionados del recurso.

Si tomamos el usuario, es posible que queramos saber quién es el administrador del mismo.

Para hacer esto necesitaremos expandir las propiedades y seleccionar el parámetro correcto del objeto administrador:

Get-MgUser -UserId [email protected] -ExpandProperty manager | Select @{Name="Manager"; Expression = {$_.Manager.AdditionalProperties.displayName}}

# Result:
Manager
-------
Miriam Graham

El desafío con esas relaciones es encontrar el campo correcto y los permisos que necesita. Ahora estamos conectados a Microsoft Graph con solo el User.Read.All alcance.

Si, por ejemplo, queremos ver las horas de trabajo de un usuario en la configuración del buzón, primero debemos encontrar y agregar el alcance correcto a nuestra sesión.

Para encontrar el permiso correcto, me gusta usar el Resto de la documentación de la API.

Si expande un recurso, mostrará las relaciones del recurso. Luego puede hacer clic en el tipo que lo llevará al recurso relacionado donde puede encontrar los permisos necesarios.

Entonces, para la configuración del buzón, necesitaremos agregar el MailboxSettings.Read permisos:

Connect-MgGraph -Scopes "User.Read.All","MailboxSettings.Read"

Y luego podemos seleccionar la propiedad y los valores anidados:

Get-MgUser -UserId [email protected] -Property MailboxSettings | Select @{Name="days"; Expression = {$_.MailboxSettings.WorkingHours.DaysofWeek}}

Script para obtener todos los usuarios de Azure AD y exportar a CSV

Creé un script completo que le permite obtener y exportar todos los usuarios de Azure Active Directory a un archivo CSV. Hay un par de opciones cuando ejecuta el script:

  • Obtener el administrador del usuario – Verdadero por defecto
  • Activar, desactivar o ambas cuentas de usuario – Verdadero por defecto
  • Establecer la ruta de exportación para el archivo CSV – Por defecto la ubicación del script

Puede descargar la última versión del script. . Para ejecutar el script, simplemente navegue hasta la ubicación del script y ejecute:

.\Get-MgUsers.ps1 -path c:\temp\users.csv

Si desea obtener más información sobre cómo ejecutar un script o cómo agregar la ubicación de su script a su perfil de PowerShell, asegúrese de leer este artículo.

<#
.SYNOPSIS
  Get all Azure AD Users using Microsoft Graph with properties and export to CSV

.DESCRIPTION
  This script collects all Azure Active Directory users with the most important properties. By default it will only
  get the enabled users, manager of the user and searches the whole domain.

.OUTPUTS
  CSV with Azure Active Directory Users

.NOTES
  Version:        1.0
  Author:         R. Mens - LazyAdmin.nl
  Creation Date:  15 feb 2022
  Purpose/Change: Initial script development

.EXAMPLE
  Get all AzureAD users from the whole Domain

   .\Get-MgUsers.ps1 -path c:\temp\users.csv

.EXAMPLE
  Get enabled and disabled users

   .\Get-MgUsers.ps1 -enabled both -path c:\temp\users.csv

   Other options are : true or false

.EXAMPLE
  Don't lookup the managers display name
  .\Get-MgUsers -getManager:$false -path c:\temp\users.csv
#>


param(
  [Parameter(
    Mandatory = $false,
    HelpMessage = "Get the users manager"
  )]
  [switch]$getManager = $true,

  [Parameter(
    Mandatory = $false,
    HelpMessage = "Get accounts that are enabled, disabled or both"
  )]
    [ValidateSet("true", "false", "both")]
  [string]$enabled = "true",

  [Parameter(
    Mandatory = $false,
    HelpMessage = "Enter path to save the CSV file"
  )]
  [string]$path = ".\ADUsers-$((Get-Date -format "MMM-dd-yyyy").ToString()).csv"
)


Function Get-Users {
    <#
    .SYNOPSIS
      Get users from the requested DN
    #>
    process{
      # Set the properties to retrieve
      $properties = @(
        'id',
        'DisplayName',
        'userprincipalname',
        'mail',
        'jobtitle',
        'department',
        'OfficeLocation',
        'MobilePhone',
        'BusinessPhones',
        'streetAddress',
        'city',
        'postalcode',
        'state',
        'country',
        'AccountEnabled',
        'CreatedDateTime'
      )

      If (($getManager.IsPresent)) {
        # Adding additional properties for the manager
        $select = $properties += @{Name="Manager"; Expression = {$_.Manager.AdditionalProperties.displayName}}
        $select += @{Name ="Phone"; Expression = {$_.BusinessPhones}} 
      }else{
        $select = $properties
      }

      # Get enabled, disabled or both users
      switch ($enabled)
      {
        "true" {$filter="AccountEnabled eq true"}
        "false" {$filter="AccountEnabled eq false"}
        "both" {$filter=""}
      }

      # Get the users
      Get-MgUser -Filter $filter -Property $properties -ExpandProperty Manager | select $select
    }
}


Function Get-AllMgUsers {
  <#
    .SYNOPSIS
      Get all AD users
  #>
  process {
    Write-Host "Collecting users" -ForegroundColor Cyan

    # Collect and loop through all users
    Get-Users | ForEach {

      [pscustomobject]@{
        "Name" = $_.DisplayName
        "UserPrincipalName" = $_.UserPrincipalName
        "Emailaddress" = $_.mail
        "Job title" = $_.JobTitle
        "Manager" = $_.Manager
        "Department" = $_.Department
        "Office" = $_.OfficeLocation
        "Phone" = $_.Phone
        "Mobile" = $_.MobilePhone
        "Enabled" = if ($_.AccountEnabled) {"enabled"} else {"disabled"}
        "Street" = $_.StreetAddress
        "City" = $_.City
        "Postal code" = $_.PostalCode
        "State" = $_.State
        "Country" = $_.Country
        "Account Created on" = $_.CreatedDateTime
      }
    }
  }
}

# Check if MS Graph module is installed
if (Get-InstalledModule Microsoft.Graph) {
  # Connect to MS Graph
  Connect-MgGraph -Scopes "User.Read.All"
}else{
  Write-Host "Microsoft Graph module not found - please install it" -ForegroundColor Black -BackgroundColor Yellow
  exit
}

Get-AllMgUsers | Sort-Object Name | Export-CSV -Path $path -NoTypeInformation

if ((Get-Item $path).Length -gt 0) {
  Write-Host "Report finished and saved in $path" -ForegroundColor Green

  # Open the CSV file
  Invoke-Item $path

}else{
  Write-Host "Failed to create report" -ForegroundColor Red
}

Terminando

El SDK de Microsoft Graph para PowerShell todavía es bastante nuevo y no está bien documentado en el momento de escribir este artículo.

Por lo tanto, puede ser un desafío encontrar la sintaxis o el cmdlet correctos para obtener la información que necesita.

Espero que este artículo le haya ayudado a comenzar con el cmdlet Get MgUser. Si tiene alguna pregunta, hágamelo saber en los comentarios a continuación.

Otros artículos relacionados

Cómo instalar el módulo Microsoft Graph en PowerShell

Cómo instalar el módulo Microsoft Graph en PowerShell

La API de Microsoft Graph nos permite interactuar con todos los servicios de Microsoft a través de una única fuente ...
Leer Más
Cómo usar Start-Transcript en PowerShell

Cómo usar Start-Transcript en PowerShell

Cuando ejecute scripts de PowerShell automáticamente, necesitará una forma de registrar cualquier error o advertencia que ocurra. Una opción es ...
Leer Más
GUI de PowerShell - Cómo empezar

GUI de PowerShell – Cómo empezar

He creado muchos scripts de PowerShell durante los últimos años. Todo con un solo propósito para automatizar mi trabajo de ...
Leer Más
Cómo instalar el módulo Azure AD en PowerShell

Cómo instalar el módulo Azure AD en PowerShell

Cuando desee utilizar PowerShell para interactuar con su entorno de Azure AD, deberá instalar el módulo de Azure AD. Este ...
Leer Más
Cómo verificar su versión de PowerShell

Cómo verificar su versión de PowerShell

¿Está usando la versión 5.1 o ya cambió a la versión 7 de PowerShell? La versión de PowerShell que haya ...
Leer Más
La solución a las Plantillas de Microsoft Planner que faltan

La solución a las Plantillas de Microsoft Planner que faltan

Una de las funciones más solicitadas en el foro de UserVoice para Microsoft Planner es la capacidad de crear plantillas ...
Leer Más

Deja un comentario