Как получить права на почтовый ящик с помощью PowerShell - включая полный отчет

Как вы отслеживаете права доступа к почтовым ящикам в Exchange Online? Добавить новые права запросто и быстро, но часто забывается удалить устаревшие права. Чтобы отслеживать это, мы хотим получить отчет о всех правах доступа к папкам почтовых ящиков.

Права доступа к почтовым ящикам могут быть установлены администратором Exchange или самими пользователями. Это делает управление и отслеживание прав доступа настоящей проблемой. Нам необходимо будет собирать права доступа из различных источников и объединять их в один ясный обзор.

С помощью PowerShell мы можем легко получить права доступа к папкам почтового ящика для каждого пользователя и создать красивый отчет в формате CSV.

Ниже приведен скрипт PowerShell, который экспортирует следующие данные из пользовательских и совместных почтовых ящиков в файл CSV:

Отображаемое имя
Основной адрес электронной почты
Тип почтового ящика
Читать и управлять правами доступа
Отправить как разрешения
Отправить от имени
Разрешения папки Входящие (имя отображения и уровень разрешений)
Разрешения на календарь (имя для отображения и уровень доступа)

Пример отчета о разрешениях на почтовые ящики

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

Разрешения почтового ящика

Прежде чем начать с сценария отчета, я сначала хочу объяснить вам, откуда берутся все различные разрешения. Потому что, чтобы получить полное представление обо всех разрешениях почтовых ящиков, нам нужно получить разрешения из 4 разных мест.

У нас есть следующие разрешения, которые мы хотим перечислить:

Читать и управлять правами доступа
Отправить как разрешения
Отправить от имени разрешений
Разрешения для папки «Входящие»
Разрешения для папки календаря

Первые 3 разрешения можно легко установить и просмотреть через Центр администрирования Microsoft 365, но для разрешений папок вам нужно будет использовать командлет get mailbox folder permissions в PowerShell.

Читать и управлять правами доступа

Чтение и управление — это, по сути, полные права доступа. Чтобы просмотреть всех пользователей, имеющих доступ к почтовому ящику, нам нужно использовать командлет Get-EXOMailboxPermissions. Мы хотим убедиться, что не перечисляем системные права по умолчанию, поэтому мы их фильтруем.

Get-EXOMailboxPermission -Identity <userprincipalname>| where { -not ($_.User -match "NT AUTHORITY") -and ($_.IsInherited -eq $false)} | ft

Отправить как разрешения

Чтобы просмотреть разрешения на отправку от имени в PowerShell, нам нужно использовать командлет Get-EXORecipientPermissions. Также здесь мы хотим отфильтровать стандартные разрешения.

Get-EXORecipientPermission -Identity <userprincipalname> | where { -not ($_.Trustee -match "NT AUTHORITY") -and ($_.IsInherited -eq $false)} | ft

Разрешения на отправку от имени

Разрешения на отправку от имени являются частью команды Get-EXOMailbox. Вам необходимо указать свойство GrantSendOnBehalfTo, чтобы просмотреть разрешения.

Get-EXOMailbox -Identity <userprincipalname> -Properties GrantSendOnBehalfTo | select UserPrincipalName, DisplayName, PrimarySMTPAddress, GrantSendOnBehalfTo, ForwardingSMTPAddress | ft

Получить разрешения на папки почтового ящика

Последние разрешения, которые мы хотим перечислить в нашем отчете, - это разрешения на папки. С ними немного сложно, потому что нам нужно будет указать правильные названия папок. Для большинства из вас это будут стандартные английские названия папок, такие как "входящие" и "календарь".

Но на голландском это, например, «Postvak in» и «Agenda». Если вы не уверены, какие имена папок правильные в вашем арендаторе, то перечислите все папки одной почтового ящика:

Get-EXOMailboxFolderStatistics -identity <userprincipalname> | ft

Получить папки почтового ящика

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

$identity = <userprincipalname>
$folder = Inbox  # Or Calendar for example

Get-EXOMailboxFolderPermission -Identity "$($identity):\$($folder)" | where { -not ($_.User -match "Default") -and -not ($_.AccessRights -match "None")}

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

Как использовать скрипт разрешений почтового ящика

Получение всех разрешений почтового ящика в большом арендаторе может занять некоторое время, потому что нам нужно получить разрешения из 4 разных мест. Поэтому я добавил несколько параметров в сценарий, чтобы вы могли настроить отчет под свои нужды.

Для запуска скрипта вам всегда нужно будет ввести свой адрес электронной почты для аутентификации с параметром
-adminUPN. Без каких-либо других параметров скрипт сгенерирует отчет с:

Все почтовые ящики (общие и пользовательские)
Включите разрешения для папок входящих сообщений и календаря.
Получите отображаемые имена для разрешений
Сохраните отчет в корневом каталоге скрипта ( .\mailboxsizereport-nov-30-2021.csv)

.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com

Получите разрешения на почтовый ящик с помощью PowerShell

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

Получить разрешения на общую почтовую коробку

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

Get only the shared mailboxes
.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -sharedMailboxes only

Get only the user mailboxes
.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -sharedMailboxes no

(Default) Get user and shared mailboxes
.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -sharedMailboxes include

Разрешения для папки почтового ящика

По умолчанию скрипт будет перечислять все разрешения для папок почтового ящика. Это разрешения, которые применяются только к папке календаря или входящих сообщениях, например. Особенно календарь является папкой почтового ящика, к которой применяется много разрешений.

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

.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -folderPermissions:$false

Столбцы все еще указаны в Excel, однако они все пустые.

Получить разрешения для одного или нескольких пользователей

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

.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -UserPrincipalName jane@contoso.com,alex@contoso.com,adele@contoso.com

Вы можете использовать любой из следующих вариантов для параметра UserPrincipalName, при условии что значение уникально идентифицирует почтовый ящик:

Идентификатор пользователя или основное имя пользователя (UPN)
Имя
Псевдоним
Доступное имя (DN)
Домен\ИмяПользователя
Адрес электронной почты

Используйте CSV файл с пользователями

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

.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -csvFile "c:\temp\csvfile.csv"

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

UserPrincipalName,Display Name
AdeleV@lazydev.onmicrosoft.com,Adele Vance
GradyA@lazydev.onmicrosoft.com,Grady Archie
JoniS@lazydev.onmicrosoft.com,Joni Sherman

Показать имена отображения или нет

Различные командлеты разрешений почтового ящика, которые мы используем в скрипте, возвращают имена пользователей (userprincipal names) пользователей, имеющих разрешения. Например, если мы посмотрим на разрешения "Отправить от имени", пользователи, имеющие разрешение "Отправить от имени", перечислены в столбце Доверитель.

Перечисление всех пользователей как GradyA@lazydev.onmicrosoft.com в вашем отчете действительно делает его трудночитаемым. Поэтому по умолчанию мы будем искать отображаемое имя каждого пользователя. Но это занимает немного дополнительного времени.

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

.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -displayNames:$false

Путь экспорта CSV

Вы также можете указать расположение и имя файла выходного файла с помощью параметра -CSVpath. По умолчанию скрипт будет экспортировать результат в консоль. Но если вы укажете путь к CSV, скрипт создаст экспорт в формате CSV.

.\MailboxPermissionReport.ps1 -adminUPN john@contoso.com -CSVpath c:\temp\permission.csv

Скрипт PowerShell для получения разрешений на почтовый ящик

Чтобы получить разрешения на почтовый ящик с помощью PowerShell, нам нужно будет использовать модуль Exchange Online. Мы будем использовать модуль Exchange Online v2, потому что он поддерживает MFA и SSON. Таким образом, вам нужно будет ввести только свой адрес электронной почты для подключения к Exchange Online.

Скрипт проверит, установлен ли модуль, и предложит вам установить его, если он недоступен на вашем компьютере. Мы также проверяем наличие любых существующих подключений, чтобы предотвратить множественные подключения с одного компьютера.

Получите почтовые ящики

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

Check which mailboxes to get
    if ($UserPrincipalName) {
      
      Write-Host "Collecting mailboxes" -ForegroundColor Cyan
      $mailboxes = @()

      # Get the requested mailboxes
      foreach ($user in $UserPrincipalName) {
        Write-Host "- Get mailbox $user" -ForegroundColor Cyan
        $mailboxes += Get-SingleUser -identity $user
      }
      
    }else{
      Write-Host "Collecting mailboxes" -ForegroundColor Cyan
      $mailboxes = Get-Mailboxes
    }

Function Get-SingleUser gets mailbox based on identity
Get-EXOMailbox -Identity $identity -Properties GrantSendOnBehalfTo, ForwardingSMTPAddress | 
      select UserPrincipalName, DisplayName, PrimarySMTPAddress, RecipientType, RecipientTypeDetails, GrantSendOnBehalfTo, ForwardingSMTPAddress

Function Get-Mailboxes gets all mailboxes based on shared mailbox parameter
    switch ($sharedMailboxes)
    {
      "include" {$mailboxTypes = "UserMailbox,SharedMailbox"}
      "only" {$mailboxTypes = "SharedMailbox"}
      "no" {$mailboxTypes = "UserMailbox"}
    }

    Get-EXOMailbox -ResultSize unlimited -RecipientTypeDetails $mailboxTypes -Properties GrantSendOnBehalfTo, ForwardingSMTPAddress| 
      select UserPrincipalName, DisplayName, PrimarySMTPAddress, RecipientType, RecipientTypeDetails, GrantSendOnBehalfTo, ForwardingSMTPAddress

Сбор разрешений

Следующий шаг - получить разрешения для каждого почтового ящика. Каждая функция будет проверять разрешения, используя функции, описанные в начале, и возвращать массив с пользователями.

Collect permissions for each mailbox
$mailboxes | ForEach {
     
   # Get Send on Behalf Permissions
   $sendOnbehalfUsers = Get-SendOnBehalf -mailbox $_
      
   # Get Fullaccess Permissions
   $fullAccessUsers = Get-FullAccessPermissions -identity $_.UserPrincipalName

   # Get Send as Permissions
   $sendAsUsers = Get-SendAsPermissions -identity $_.UserPrincipalName
}

В зависимости от параметра folderPermissions мы также получим разрешения на папку почтового ящика:

if ($folderPermissions.IsPresent) {
        
    # Get Inbox folder permission
    $inboxFolder = Get-FolderPermissions -identity $_.UserPrincipalName -folder $inboxFolderName
    $ib = $inboxFolder.users.Count

    # Get Calendar permissions
    $calendarFolder = Get-FolderPermissions -identity $_.UserPrincipalName -folder $calendarFolderName
    $ca = $calendarFolder.users.Count
}

Для разрешений на папку нам нужно знать правильные имена папок. В начале скрипта мы устанавливаем 2 переменные с правильными именами:

$inboxFolderName = "inbox"  # Default "inbox"
$calendarFolderName = "calendar"  # Default "calendar"

Создание экспорта CSV

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

Итак, мы считаем каждый массив, а затем используем простую функцию if-else, чтобы выяснить, какие больше.

Count number or records
$sob = $sendOnbehalfUsers.Count
$fa = $fullAccessUsers.Count
$sa = $sendAsUsers.Count

$ib and $ca are set in the folder permissions
$mostRecords = Find-LargestValue -sob $sob -fa $fa -sa $sa -ib $ib -ca $ca

Find Largest Values function:
Function Find-LargestValue {
  <#
    .SYNOPSIS
        Find the value with the most records
  #>
  param(
    [Parameter(Mandatory = $true)]$sob,
    [Parameter(Mandatory = $true)]$fa,
    [Parameter(Mandatory = $true)]$sa,
    [Parameter(Mandatory = $true)]$ib,
    [Parameter(Mandatory = $true)]$ca
  )

  if ($sob -gt $fa -and $sob -gt $sa -and $sob -gt $ib -and $sob -gt $ca) {return $sob}
  elseif ($fa -gt $sa -and $fa -gt $ib -and $fa -gt $ca) {return $fa}
  elseif ($sa -gt $ib -and $sa -gt $ca) {return $sa}
  elseif ($ib -gt $ca) {return $ib}
  else {return $ca}
}

Если мы знаем, сколько подзаписей нам нужно создать, мы можем пройтись по ним с помощью цикла do-while и создать объект PSCustomObject с данными.

Do{
  if ($x -eq 0) {
      [pscustomobject]@{
        "Display Name" = $_.DisplayName
        "Emailaddress" = $_.PrimarySMTPAddress
        "Mailbox type" = $_.RecipientTypeDetails
        "Read and manage" = @($fullAccessUsers)[$x]
        "Send as" = @($sendAsUsers)[$x]
        "Send on behalf" = @($sendOnbehalfUsers)[$x]
        "Inbox folder" = @($inboxFolder.users)[$x]
        "Inbox folder Permission" = @($inboxFolder.permission)[$x]
        "Inbox folder Delegated" = @($inboxFolder.delegated)[$x]
        "Calendar" = @($calendarFolder.users)[$x]
        "Calendar Permission" = @($calendarFolder.permission)[$x]
        "Calendar Delegated" = @($calendarFolder.delegated)[$x]
      }
      $x++;
  }else{
      [pscustomobject]@{
        "Display Name" = ''
        "Emailaddress" = ''
        "Mailbox type" = ''
        "Read and manage" = @($fullAccessUsers)[$x]
        "Send as" = @($sendAsUsers)[$x]
        "Send on behalf" = @($sendOnbehalfUsers)[$x]
        "Inbox folder" = @($inboxFolder.users)[$x]
        "Inbox folder Permission" = @($inboxFolder.permission)[$x]
        "Inbox folder Delegated" = @($inboxFolder.delegated)[$x]
        "Calendar" = @($calendarFolder.users)[$x]
        "Calendar Permission" = @($calendarFolder.permission)[$x]
        "Calendar Delegated" = @($calendarFolder.delegated)[$x]
      }
      $x++;
  }

  $currentUser = $_.DisplayName
  if ($mailboxes.Count -gt 1) {
    Write-Progress -Activity "Collecting mailbox permissions" -Status "Current Count: $i" -PercentComplete (($i / $mailboxes.Count) * 100) -CurrentOperation "Processing mailbox: $currentUser"
  }
}
while($x -ne $mostRecords)

Скачайте полный скрипт прав на почтовый ящик

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

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

Завершение

Чтобы легко запустить скрипт из командной строки, вы также можете добавить скрипт (или папку) в свой профиль PowerShell. Читайте об этом в этой статье.

Надеюсь, вы нашли этот скрипт полезным. Если у вас есть вопросы, просто оставьте комментарий ниже.

Вам также могут понравиться один из следующих скриптов отчетов PowerShell:

Отчет о размере OneDrive
Отчет о размере почтового ящика
Отчет о состоянии МФА