<# .SYNOPSIS Connects Exchange Online to Innovarro Signatures: two connectors and one transport rule. .DESCRIPTION Creates (or updates, when run again) everything Exchange Online needs to route mail through the Innovarro Signatures relay and accept it back: * Outbound connector "Innovarro Signatures" - only used by the transport rule below * Inbound connector "Innovarro Signatures - return" - accepts signed mail back, identified by the relay's certificate * Transport rule "Innovarro Signatures" - sends your users' mail to the relay once The script is safe to run again: it updates existing objects instead of creating duplicates. Use -PilotUsers / -PilotGroup first, then run it again with -AllUsers to roll out. Without any of these switches the rule is created DISABLED, so no mail changes route. Requires the ExchangeOnlineManagement module (Install-Module ExchangeOnlineManagement) and an account with the Exchange Administrator or Global Administrator role. .PARAMETER PilotUsers Only mail from these senders goes through the relay (e-mail addresses). .PARAMETER PilotGroup Only mail from members of this distribution group or mail-enabled security group goes through the relay. .PARAMETER AllUsers Mail from everyone in the organisation goes through the relay. .PARAMETER ExcludeSenders Mailboxes that must never be signed (e.g. scanners, shared mailboxes, payment or no-reply addresses). .PARAMETER ExternalOnly Only route mail that leaves the organisation. Internal mail is not signed by the relay (the Outlook add-in still signs it). Use this if your signatures are set to "External only" and you want fewer hops for internal mail. .PARAMETER TestRecipient An external address (e.g. a personal mailbox). When given, the outbound connector is validated by sending a test message through the relay. .EXAMPLE .\Install-InnovarroSignatures.ps1 -PilotUsers alex@contoso.com,sam@contoso.com -TestRecipient me@gmail.com .EXAMPLE .\Install-InnovarroSignatures.ps1 -AllUsers -ExcludeSenders scanner@contoso.com,noreply@contoso.com .NOTES Innovarro Signatures - https://signatures.innovarro.cloud/support #> [CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'Disabled')] param( [Parameter(ParameterSetName = 'Pilot', Mandatory)][string[]]$PilotUsers, [Parameter(ParameterSetName = 'Group', Mandatory)][string]$PilotGroup, [Parameter(ParameterSetName = 'All', Mandatory)][switch]$AllUsers, [string[]]$ExcludeSenders, [switch]$ExternalOnly, [string]$TestRecipient, [string]$RelayHost = 'relay.signatures.innovarro.cloud' ) $ErrorActionPreference = 'Stop' $OutboundName = 'Innovarro Signatures' $InboundName = 'Innovarro Signatures - return' $RuleName = 'Innovarro Signatures' $StampHeader = 'X-Innovarro-Signature' function Write-Step($text) { Write-Host "`n==> $text" -ForegroundColor Cyan } function Write-Ok($text) { Write-Host " $text" -ForegroundColor Green } # --- Connect ------------------------------------------------------------------------------------------------- if (-not (Get-Command Get-ConnectionInformation -ErrorAction SilentlyContinue)) { throw 'The ExchangeOnlineManagement module is not installed. Run: Install-Module ExchangeOnlineManagement -Scope CurrentUser' } if (-not (Get-ConnectionInformation | Where-Object State -eq 'Connected')) { Write-Step 'Connecting to Exchange Online (sign in as an Exchange or Global Administrator)' Connect-ExchangeOnline -ShowBanner:$false } $org = Get-OrganizationConfig Write-Ok "Connected to $($org.DisplayName)" # --- Outbound connector (to the relay) --------------------------------------------------------------------------- Write-Step "Outbound connector '$OutboundName' -> $RelayHost" $outParams = @{ ConnectorType = 'Partner' IsTransportRuleScoped = $true UseMXRecord = $false SmartHosts = $RelayHost TlsSettings = 'DomainValidation' TlsDomain = $RelayHost Enabled = $true Comment = 'Innovarro Signatures: used only by the transport rule of the same name.' } if (Get-OutboundConnector -Identity $OutboundName -ErrorAction SilentlyContinue) { if ($PSCmdlet.ShouldProcess($OutboundName, 'Update outbound connector')) { Set-OutboundConnector -Identity $OutboundName @outParams; Write-Ok 'Updated' } } elseif ($PSCmdlet.ShouldProcess($OutboundName, 'Create outbound connector')) { New-OutboundConnector -Name $OutboundName @outParams | Out-Null; Write-Ok 'Created' } # --- Inbound connector (signed mail coming back) ----------------------------------------------------------------- Write-Step "Inbound connector '$InboundName' (certificate $RelayHost)" $inParams = @{ ConnectorType = 'OnPremises' SenderDomains = '*' RequireTls = $true TlsSenderCertificateName = $RelayHost CloudServicesMailEnabled = $true # keeps the organisation's internal headers on mail coming back Enabled = $true Comment = 'Innovarro Signatures: accepts signed mail back from the relay, identified by its TLS certificate.' } if (Get-InboundConnector -Identity $InboundName -ErrorAction SilentlyContinue) { if ($PSCmdlet.ShouldProcess($InboundName, 'Update inbound connector')) { Set-InboundConnector -Identity $InboundName @inParams; Write-Ok 'Updated' } } elseif ($PSCmdlet.ShouldProcess($InboundName, 'Create inbound connector')) { New-InboundConnector -Name $InboundName @inParams | Out-Null; Write-Ok 'Created' } # --- Transport rule ---------------------------------------------------------------------------------------------- $scope = switch ($PSCmdlet.ParameterSetName) { 'Pilot' { "pilot: $($PilotUsers -join ', ')" } 'Group' { "pilot group: $PilotGroup" } 'All' { 'all users' } default { 'none yet (rule disabled)' } } Write-Step "Transport rule '$RuleName' - scope: $scope$(if ($ExternalOnly) { ', external recipients only' })" $ruleParams = @{ FromScope = 'InOrganization' RouteMessageOutboundConnector = $OutboundName # Loop prevention: mail that already went through the relay carries this header. ExceptIfHeaderMatchesMessageHeader = $StampHeader ExceptIfHeaderMatchesPatterns = '.' ExceptIfMessageTypeMatches = 'Calendaring' StopRuleProcessing = $false Mode = 'Enforce' SentToScope = $(if ($ExternalOnly) { 'NotInOrganization' } else { $null }) From = $(if ($PSCmdlet.ParameterSetName -eq 'Pilot') { $PilotUsers } else { $null }) FromMemberOf = $(if ($PSCmdlet.ParameterSetName -eq 'Group') { $PilotGroup } else { $null }) ExceptIfFrom = $(if ($ExcludeSenders) { $ExcludeSenders } else { $null }) Comment = "Innovarro Signatures. Roll back: Disable-TransportRule '$RuleName' (mail flows directly again at once). Support: https://signatures.innovarro.cloud/support" } $existing = Get-TransportRule -Identity $RuleName -ErrorAction SilentlyContinue if ($existing) { if ($PSCmdlet.ShouldProcess($RuleName, 'Update transport rule')) { Set-TransportRule -Identity $RuleName @ruleParams; Write-Ok 'Updated' } } else { # New rules go last, so existing rules (disclaimers, journaling, blocks) keep running first. $ruleParams.Priority = @(Get-TransportRule).Count $newParams = @{}; $ruleParams.GetEnumerator() | Where-Object { $null -ne $_.Value } | ForEach-Object { $newParams[$_.Key] = $_.Value } if ($PSCmdlet.ShouldProcess($RuleName, 'Create transport rule')) { New-TransportRule -Name $RuleName @newParams -Enabled ($PSCmdlet.ParameterSetName -ne 'Disabled') | Out-Null; Write-Ok 'Created' } } if ($existing -and $PSCmdlet.ShouldProcess($RuleName, 'Set rule state')) { if ($PSCmdlet.ParameterSetName -eq 'Disabled') { Disable-TransportRule -Identity $RuleName -Confirm:$false; Write-Ok 'Disabled (no scope given)' } else { Enable-TransportRule -Identity $RuleName -Confirm:$false; Write-Ok 'Enabled' } } $rules = Get-TransportRule | Sort-Object Priority $ours = $rules | Where-Object Name -eq $RuleName $blocking = $rules | Where-Object { $_.Priority -lt $ours.Priority -and $_.StopRuleProcessing -and $_.State -eq 'Enabled' } if ($blocking) { Write-Warning "These rules run before '$RuleName' and stop rule processing, so mail they match is not signed: $($blocking.Name -join ', ')" } # --- Validate ---------------------------------------------------------------------------------------------------- if ($TestRecipient) { Write-Step "Validating the outbound connector with a test message to $TestRecipient" $v = Validate-OutboundConnector -Identity $OutboundName -Recipients $TestRecipient $v | Format-List | Out-String | Write-Host } Write-Host "`nDone." -ForegroundColor Green Write-Host 'Next: send a test message from a pilot user to an external mailbox and check the signature and headers.' Write-Host 'Check everything with .\Test-InnovarroSignatures.ps1 Roll back with .\Disable-InnovarroSignatures.ps1'