Microsoft 365 mail

# Stable Baseline: give the Stable Baseline Connectors app access to the shared mailboxes below, and to no others.
# Paste all of it into Azure Cloud Shell (PowerShell) or PowerShell 7, signed in as an Exchange admin.
# It checks everything before it changes anything, and skips what is already done: safe to run again.
# It grants Application Mail.ReadWrite (read mail and write drafts) over these mailboxes only.
# It never grants Mail.Send, and it changes nothing in Microsoft Entra.
& {
  # The Stable Baseline Connectors app, the same in every organisation.
  $AppId = '<app id shown in Stable Baseline>'
  # The app's Object ID in your organisation. Left empty, Azure Cloud Shell reads it for you.
  $AppObjectId = ''
  # Read mail and write drafts. Never send.
  $Role = 'Application Mail.ReadWrite'
  # The shared mailboxes, by their main address.
  $Mailboxes = @(
    'support@contoso.com'
    'orders@contoso.com'
  )

  $ErrorActionPreference = 'Stop'
  # Each access has its own mark and its own scope, so each mailbox is in the scope of the highest access asked for
  # it, and in no other:
  #   Draft: CustomAttribute12 = sb-agent-mail-draft, scope 'Stable Baseline draft mailboxes', role Application Mail.ReadWrite.
  #   Read: CustomAttribute12 = sb-agent-mail-read, scope 'Stable Baseline read mailboxes', role Application Mail.Read.
  $Drafts = $Role -eq 'Application Mail.ReadWrite'
  $Mark = if ($Drafts) { 'sb-agent-mail-draft' } else { 'sb-agent-mail-read' }
  $Scope = if ($Drafts) { 'Stable Baseline draft mailboxes' } else { 'Stable Baseline read mailboxes' }
  $Rule = "CustomAttribute12 -eq '$Mark' -and RecipientTypeDetails -eq 'SharedMailbox'"

  # 1. Only the two mail roles are allowed here: never Application Mail.Send, and no full access role.
  if ($Role -notin 'Application Mail.Read', 'Application Mail.ReadWrite') {
    throw 'These commands grant only Application Mail.Read or Application Mail.ReadWrite.'
  }
  if (@($Mailboxes).Count -lt 1) { throw 'List at least one shared mailbox.' }

  # 2. Sign in to Exchange Online, unless this window already is. Azure Cloud Shell signs you in by itself.
  if (-not (Get-Command Get-ConnectionInformation -ErrorAction SilentlyContinue)) {
    throw 'First install Exchange Online PowerShell: Install-Module ExchangeOnlineManagement -Scope CurrentUser'
  }
  # This window's Exchange Online sign-in, if it has one (not a Security & Compliance one).
  $ExchangeSignIn = { Get-ConnectionInformation | Where-Object { $_.State -eq 'Connected' -and "$($_.IsEopSession)" -ne 'True' } }
  if (-not (& $ExchangeSignIn)) {
    # If this fails in Azure Cloud Shell, run Connect-ExchangeOnline -Device first, then paste these commands again.
    Connect-ExchangeOnline -ShowBanner:$false
  }

  # 3. Check each mailbox before anything changes: exactly one shared mailbox has that main address,
  #    and its CustomAttribute12 is empty or one of the two marks.
  $Boxes = foreach ($Address in $Mailboxes) {
    $Found = @(Get-EXOMailbox -PrimarySmtpAddress $Address -Properties CustomAttribute12 -ErrorAction SilentlyContinue)
    if ($Found.Count -ne 1 -or "$($Found[0].PrimarySmtpAddress)" -ne $Address) {
      throw "No mailbox has the main address $Address. Nothing was changed."
    }
    if ($Found[0].RecipientTypeDetails -ne 'SharedMailbox') {
      throw "$Address is not a shared mailbox. A person connects their own mailbox in Stable Baseline. Nothing was changed."
    }
    if ($Found[0].CustomAttribute12 -and $Found[0].CustomAttribute12 -notin 'sb-agent-mail-read', 'sb-agent-mail-draft') {
      throw "$Address already uses CustomAttribute12 for something else. Nothing was changed."
    }
    $Found[0]
  }

  # 4. This access's scope, if it is there already, must be ours: the same rule, and not exclusive.
  $Existing = @(Get-ManagementScope | Where-Object { $_.Name -eq $Scope })
  if ($Existing.Count -gt 0) {
    $Same = ("$($Existing[0].RecipientFilter)" -replace '[\s()]', '') -eq ($Rule -replace '[\s()]', '')
    if (-not $Same -or "$($Existing[0].Exclusive)" -eq 'True') {
      throw "A scope called '$Scope' already exists with another rule: $($Existing[0].RecipientFilter). Nothing was changed."
    }
  }

  # 5. Exchange's pointer to the app your Microsoft admin approved. It names the app and grants nothing.
  $App = Get-ServicePrincipal | Where-Object { $_.AppId -eq $AppId }
  if (-not $App) {
    if (-not $AppObjectId) {
      # Azure Cloud Shell is signed in to Azure already, so it can read the app's Object ID. Elsewhere this reads nothing.
      try { $AppObjectId = (Get-AzADServicePrincipal -ApplicationId $AppId).Id } catch { $AppObjectId = '' }
    }
    if (-not $AppObjectId) {
      throw "Exchange needs the app's Object ID. Paste it into Stable Baseline, then copy these commands again. Nothing was changed."
    }
    $App = New-ServicePrincipal -AppId $AppId -ObjectId $AppObjectId -DisplayName 'Stable Baseline Connectors'
  }

  # 6. Mark each listed mailbox with this access's mark, so this access's scope finds it and the other does not.
  #    A mailbox keeps the highest access any run asked for: Draft raises a mailbox marked for Read, and Read never
  #    lowers one marked for Draft (it says so, and nothing changes for that mailbox). Skipped when marked.
  foreach ($Box in $Boxes) {
    if (-not $Drafts -and $Box.CustomAttribute12 -eq 'sb-agent-mail-draft') {
      Write-Host "$($Box.PrimarySmtpAddress) keeps Draft access from an earlier run: these commands never lower access. Nothing changed for it."
    } elseif ($Box.CustomAttribute12 -ne $Mark) {
      Set-Mailbox -Identity $Box.PrimarySmtpAddress -CustomAttribute12 $Mark
    }
  }

  # 7. The lock: this access's scope matches shared mailboxes carrying its mark, and nothing else. Made once.
  if ($Existing.Count -eq 0) {
    $null = New-ManagementScope -Name $Scope -RecipientRestrictionFilter $Rule
  }

  # 8. The one grant: this access's role, over this access's scope only. Skipped when the app has it already.
  $Held = Test-ServicePrincipalAuthorization -Identity $AppId |
    Where-Object { $_.RoleName -eq $Role -and "$($_.AllowedResourceScope)" -eq $Scope }
  if (-not $Held) {
    $null = New-ManagementRoleAssignment -Name "Stable Baseline $Role" -App $App.ObjectId -Role $Role -CustomResourceScope $Scope
  }

  # 9. What the app may do in each listed mailbox, as Exchange sees it now.
  Write-Host ''
  Write-Host 'What the app may do in each listed mailbox:'
  foreach ($Box in $Boxes) {
    $Roles = @(Test-ServicePrincipalAuthorization -Identity $AppId -Resource $Box.Guid |
      Where-Object { "$($_.InScope)" -eq 'True' } | ForEach-Object { $_.RoleName })
    Write-Host "  $($Box.PrimarySmtpAddress): $(if ($Roles) { $Roles -join ', ' } else { 'nothing yet' })"
  }
  $Marked = "CustomAttribute12 -eq 'sb-agent-mail-read' -or CustomAttribute12 -eq 'sb-agent-mail-draft'"
  $All = @(Get-EXOMailbox -RecipientTypeDetails SharedMailbox -Filter $Marked -ResultSize Unlimited)
  Write-Host "Every mailbox the app can reach: $(($All | ForEach-Object { $_.PrimarySmtpAddress }) -join ', ')"
  Write-Host 'Microsoft takes 30 minutes to 2 hours to apply a new grant. Then press Check access in Stable Baseline.'

  # 10. The line Stable Baseline needs: your tenant ID, then each mailbox's object ID.
  $Tenant = (& $ExchangeSignIn | Select-Object -First 1).TenantID
  $Pairs = foreach ($Box in $Boxes) { "$($Box.PrimarySmtpAddress)".ToLower() + '=' + $Box.ExternalDirectoryObjectId }
  Write-Host ''
  Write-Host 'Copy this line into Stable Baseline:'
  Write-Host ((@("tenant=$Tenant") + $Pairs) -join ', ')
  Write-Host ''
  Write-Host 'When you have finished: Disconnect-ExchangeOnline -Confirm:$false'
}

# Take the Stable Baseline Connectors app's access away again (Exchange Online PowerShell, as an Exchange admin).
# 1. Remove the grants. Run the line for each one you made.
Remove-ManagementRoleAssignment -Identity 'Stable Baseline Application Mail.ReadWrite' -Confirm:$false
Remove-ManagementRoleAssignment -Identity 'Stable Baseline Application Mail.Read' -Confirm:$false
# 2. Remove the scopes, likewise.
Remove-ManagementScope -Identity 'Stable Baseline draft mailboxes' -Confirm:$false
Remove-ManagementScope -Identity 'Stable Baseline read mailboxes' -Confirm:$false
# 3. Remove Exchange's pointer to the app.
Remove-ServicePrincipal -Identity '<app id shown in Stable Baseline>' -Confirm:$false
# 4. Clear the mark on each mailbox. On its own, this takes one mailbox out of reach.
Set-Mailbox -Identity 'support@contoso.com' -CustomAttribute12 $null