Azure Runbook – enable Exchange Online Litigation Hold!!

This script will connect to Exchange Online and enable litigation hold for all ‘enabled’ users (if it is currently disabled). Errors due to not having the appropriate license are ignored.

Litigation hold can be enabled for users licensed with Business Premium, EOL Plan 2 or the Mailbox Archive add-on.

You can schedule to run nightly to pick up new users as they are added. If you like the script, made it cooler or need some help, please add a comment below! 🙂

Prerequisites...

  • Enable a system-assigned managed identity for the Automation Account.
  • Your managed identity will need to be in the Discovery Management role group OR assigned the Legal Hold and Mailbox Search management roles (or Exchange Administrator will do it).
  • Import the ExchangeOnlineManagement module to your Automation Account.
  • Don’t forget to update yourtenant.onmicrosoft.com in the script!

Update 08/08/2023 – well Microsoft just made it REALLY hard to configure a managed identity for Exchange Online. I’ve lost a few hours (more than once as I didn’t take notes!) getting it to work. There are multiple hoops to jump through, and I needed good error checking to find out what the issues were. In short, follow this guidance to the letter: Use Azure managed identities to connect to Exchange Online PowerShell | Microsoft Learn. Then get depressed when it still doesn’t work! Hopefully it’s only because you don’t have these modules in your automation account:

  1. PackageManagement
  2. PowerShellGet

Yaaaaaay! Now it works…! =]

# use TLS 1.2
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# connect eol
Try {
Connect-ExchangeOnline -ManagedIdentity -Organization yourtenant.onmicrosoft.com
}
        Catch {    
            Write-Error "Failed to connect to MSOnline!"
            Exit
        }
Write-Output "Connect to EOL - Success"

# get user mailboxes
Try {
    $mailboxes = Get-Mailbox -ResultSize Unlimited -Filter { ( RecipientTypeDetails -eq 'UserMailbox' ) -and ( ExchangeUserAccountControl -ne 'AccountDisabled') } | Where-Object {$_.LitigationHoldEnabled -ne $true}
}
        Catch {    
            Write-Output "Failed to get user mailboxes!"
            Exit
        }
Write-Output "Get user mailboxes - Success"

# enable litigation hold
foreach ( $mailbox in $mailboxes ){
     if ( $mailbox | Set-Mailbox -LitigationHoldEnabled $true -ErrorAction Ignore ){
          Write-Output "Hold enabled for $mailbox.DisplayName"
} 
}

Loading

4 thoughts on “Azure Runbook – enable Exchange Online Litigation Hold!!”

  1. Hi,

    i have 2 question for you:

    which kind of module we need to import on azure automation?
    which kind of permission need the service user?

    REgards

    1. Hi Ema, from the Automaton Account => Modules blade, make sure to import ExchangeOnlineManagement. The account can have either be in Discovery Management role group or assigned the Legal Hold and Mailbox Search management roles.

      Cheers,
      Admin Dude

        1. Hi Ema, this was a while ago, so I used a ‘Run As’ credential (user/pswd added to Automation account). Nowadays I would always use a system-assigned managed identity, seeing as this requires zero maintenance. There is guidance for connecting to Exchange Online here:
          https://learn.microsoft.com/en-us/powershell/exchange/connect-exo-powershell-managed-identity?view=exchange-ps#connect-to-exchange-online-powershell-using-azure-automation-accounts-with-system-assigned-managed-identity

          Thanks for your comment! Admin Dude.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top