Get-MgUser: Как получить пользователей Azure AD с помощью PowerShell

Начиная с декабря 2022 года, нам необходимо будет использовать командлет Get-MgUser для получения и экспорта наших пользователей Azure AD. Get-MgUser является частью Microsoft Graph SDK для PowerShell. Он позволяет нам взаимодействовать со всеми службами Microsoft через одну конечную точку.

Все учетные записи пользователей в вашем арендаторе Microsoft 365 хранятся в Azure Active Directory. Мы можем управлять ими через центр администрирования или Портал Azure, но иногда PowerShell удобнее.

В этой статье я собираюсь объяснить, как мы можем использовать командлет Get MgUser для поиска и извлечения информации о пользователях из Azure AD. Я также создал полный скрипт, который позволяет вам экспортировать всех ваших пользователей в формат CSV, который вы найдете в конце статьи.

Начало работы с Get-MgUser

Прежде чем начать, убедитесь, что вы установили модуль Microsoft Graph в PowerShell. В этой статье вы найдете полное руководство по установке модуля. Но чтобы просто установить модуль, используйте следующую команду:

Install-Module Microsoft.Graph -Force

Команда Get-MgUser позволяет находить и извлекать информацию о пользователях из Azure Active Directory. Существует несколько параметров, которые мы можем использовать для поиска или фильтрации пользователей:

UserId – Вернуть конкретного пользователя на основе UPN или ObjectID
Фильтр - Получить несколько объектов на основе запроса oDate v3
Поиск – Получить всех пользователей, соответствующих searchString
Топ – Вернуть n количество результатов
Все – Вернуть все результаты (по умолчанию возвращаются первые 100 элементов)

Хорошо знать, что по умолчанию cmdlet возвращает только первые 100 результатов. Поэтому убедитесь, что вы используете параметр -all, чтобы получить все результаты при необходимости.

Первый шаг - подключить Microsoft Graph с правильным охватом. Мы собираемся получать только данные пользователей, поэтому можем использовать охват User.Read.All.

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

Чтобы проверить, работает ли командлет, вы можете просто получить всех пользователей из вашей Azure Active Directory с помощью следующего командлета:

Get-MgUser -All

Чтобы получить одного пользователя, мы можем использовать UserId пользователя. Это может быть либо UserPrincipalName пользователя, либо фактический идентификатор пользователя:

Get the user by the UserPrincipalName
Get-MgUser -UserId adelev@lazydev.onmicrosoft.com

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

Совет
Теперь вы также можете использовать модуль Microsoft Entra PowerShell для управления вашими пользователями. Узнайте больше об этом новом модуле в этой статье.

Использование фильтров с Get-MgUser

Так же, как и с командлетом Get-AzureAduser, мы можем фильтровать пользователей. Фильтр основан на запросе oDate v3, но не все операторы поддерживаются. Мы можем использовать только следующие операторы для фильтрации пользователей:

Оператор	Описание	Пример
равно	Равно	должность eq 'Ассистент по маркетингу'
и	И	должность eq ‘Рекрутер’ и должность eq ‘hr’
или	Или	должность eq ‘Рекрутер’ или должность eq ‘hr’
начинается с	Строка начинается с	начинается с(jobtitle, 'рекр')

Получить-Filters пользователя Mg

Важно, чтобы вы обернули фильтрный запрос в двойные кавычки, а строку, по которой вы хотите фильтровать, в одинарные кавычки. Только когда вы фильтруете по булевым значениям, вам не нужно оборачивать истинное или ложное значение в кавычки.

Давайте рассмотрим несколько примеров с использованием параметра -filter. Чтобы найти пользователя по имени отображения, мы можем указать полное имя пользователя или использовать оператор startsWith. Имейте в виду, что здесь мы не можем использовать подстановочные знаки или оператор -like.

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')"

Найдите пользователя по имени

Тем же методом также можно получить всех пользователей с должностью «Ассистент по маркетингу», например:

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

Чтобы получить, например, только активные учетные записи пользователей с помощью команды Get-MgUser, мы можем использовать следующую команду:

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

Обратите внимание, что я добавил параметр -all. По умолчанию команда Get MgUser возвращает только первые 100 результатов. Добавив параметр -all, мы получаем все возвращаемые результаты.

Мы также можем фильтровать по нескольким условиям, используя and или or в запросе фильтра:

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

Еще один пример, которым я хотел бы поделиться, это возможность получить всех пользователей, созданных в прошлом году. Для этого мы можем отфильтровать свойство CreatedDateTime:

Get-MgUser -Filter "CreatedDateTime ge $((Get-Date).AddYears(-1).ToString("s"))Z"

Использование поиска для нахождения пользователей

Кроме параметра фильтра, мы также можем использовать параметр -Search для поиска пользователей. Параметр требует указания свойства, по которому вы хотите выполнять поиск, и значения. Вам также необходимо установить -consistencylevel на eventual.

Преимущество параметра -search заключается в том, что он позволяет нам искать любое значение. Например, если мы хотим искать часть имени, мы можем использовать:

Get-MgUser -Search 'DisplayName:van' -ConsistencyLevel eventual

Параметр поиска Get-MgUser

Также обратите внимание, что вам нужно обернуть поисковый запрос в одинарные кавычки. Вы можете использовать параметр поиска практически во всех полях, которые возвращает командлет Get-MgUser.

Сочетание поиска и фильтрации в получении MgUser

Мы также можем комбинировать параметры -search и -filter в одной команде. Это позволяет нам выполнять поиск по имени или должности только среди активированных учетных записей, например:

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

Выбор свойств для возврата

При использовании команды Get-MgUser вы, вероятно, заметили, что она по умолчанию не возвращает много свойств. Большинство полей пусты или содержат значение Microsoft.Graph.PowerShell.Models., за которым следует имя сущности. Итак, как мы можем получить эти данные?

Существует два параметра, которые мы можем использовать для получения необходимой информации: -property и -expandproperty.

-property параметр похож на select, который мы можем использовать в конвейере после cmdlet. Единственное отличие заключается в том, что с select все данные возвращаются Microsoft Graph и фильтруются в PowerShell.

Get-MgUser -UserId adelev@lazydev.onmicrosoft.com | Select DisplayName,BusinessPhones,Mail,JobTitle

DisplayName BusinessPhone     Mail                           JobTitle
----------- -------------     ----                           --------
Adele Vance {+1 425 555 0109} AdeleV@lazydev.onmicrosoft.com Retail Manager

Когда вы используете параметр свойства, только те данные, которые вам нужны, возвращаются Microsoft Graph. Особенно при работе с большим количеством записей это будет быстрее, чем использование select.

Get-MgUser -UserId adelev@lazydev.onmicrosoft.com -Property DisplayName,BusinessPhones,Mail,JobTitle | fl

Если вы выведете результаты в список, вы увидите, что только поля, которые вы выбрали с помощью параметра свойства, содержат данные.

Расширение Microsoft.Graph.PowerShell.Models

При просмотре свойств пользователя вы, возможно, заметили, что некоторые из них содержат значение Microsoft.Graph.PowerShell.Models, за которым следует имя ресурса. Эти модели (или ресурсы) являются отношениями типа ресурса, который вы просматриваете.

Эти отношения должны позволить нам легко просматривать связанные данные ресурса. Если взять пользователя, нам может быть интересно узнать его менеджера.

Для этого нам нужно будет развернуть свойства и выбрать правильный параметр объекта менеджера:

Get-MgUser -UserId adelev@lazydev.onmicrosoft.com -ExpandProperty manager | Select @{Name = 'Manager'; Expression = {$_.Manager.AdditionalProperties.displayName}}

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

Проблема с этими отношениями заключается в том, чтобы найти правильное поле и разрешения, которые вам нужны. Мы теперь подключены к Microsoft Graph только с областями User.Read.All. Если мы, например, хотим просмотреть рабочие часы пользователя в настройках почтового ящика, тогда нам сначала нужно найти и добавить правильную область к нашей сессии.

Чтобы найти правильные разрешения, мне нравится использовать документацию по Rest API. Если вы развернете ресурс, он покажет отношения этого ресурса. Затем вы можете нажать на тип, который перенаправит вас на связанный ресурс, где вы сможете найти необходимые разрешения.

Итак, для настроек почтового ящика нам потребуется добавить разрешения MailboxSettings.Read:

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

А затем мы можем выбрать свойство и вложенные значения:

Get-MgUser -UserId meganb@a-d.site -Property MailboxSettings | Select @{Name = 'days'; Expression = {$_.MailboxSettings.WorkingHours.DaysofWeek}}

Скрипт для получения всех пользователей Azure AD и экспорта в CSV

Я создал полный скрипт, который позволяет вам получить и экспортировать всех пользователей Azure Active Directory в файл CSV. При запуске скрипта есть несколько опций:

Получить менеджера пользователя – По умолчанию true
Получить включенные, отключенные или оба типа учетных записей пользователей – По умолчанию True
Установите путь экспорта для CSV файла – По умолчанию местоположение скрипта

Вы можете скачать последнюю версию скрипта здесь из моего репозитория на GitHub. Чтобы запустить скрипт, просто перейдите к месту его расположения и выполните:

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

Если вы хотите узнать больше о том, как запустить скрипт, или как добавить расположение вашего скрипта в профиль PowerShell, обязательно прочитайте эту статью.

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
}

Заключение

SDK Microsoft Graph для PowerShell все еще довольно новый и в данный момент плохо документирован. Поэтому может быть немного сложно найти правильный синтаксис или командлет, чтобы получить нужную информацию.

Надеюсь, эта статья помогла вам начать работу с командлетом Get-MgUser. Если у вас есть вопросы, просто дайте мне знать в комментариях ниже.