Public/Connect-PurviewDLP.ps1
|
function Connect-PurviewDLP { <# .SYNOPSIS Connects to Microsoft Security & Compliance Center PowerShell. .DESCRIPTION Establishes a connection to the Security & Compliance Center PowerShell endpoint for managing DLP policies. Handles authentication, verifies connection status, and ensures the ExchangeOnlineManagement module is installed and imported. Supports both interactive and credential-based authentication. .PARAMETER Credential Optional PSCredential object for authentication. If not provided, interactive authentication will be used (recommended for MFA). .PARAMETER ShowBanner Display connection banner and status information. Default: $true .PARAMETER Force Force a new connection even if already connected. Default: $false .OUTPUTS System.Collections.Hashtable Returns hashtable with connection status: - Success (bool): Whether connection succeeded - Message (string): Status message - AlreadyConnected (bool): Whether was already connected - PolicyCount (int): Number of DLP policies found (if successful) .EXAMPLE Connect-PurviewDLP Connects using interactive authentication with modern authentication (MFA supported). .EXAMPLE Connect-PurviewDLP -ShowBanner $false Connects silently without displaying banner. .EXAMPLE $cred = Get-Credential Connect-PurviewDLP -Credential $cred Connects using provided credentials (legacy auth). .EXAMPLE Connect-PurviewDLP -Force Forces a new connection even if already connected. .NOTES Requires: ExchangeOnlineManagement module (auto-installed if missing) Author: PurviewDLP Module For MFA-enabled accounts, use interactive authentication (no -Credential parameter). The cmdlet will automatically verify the connection by querying DLP policies. .LINK https://github.com/uniQuk/PurviewDLP #> [CmdletBinding()] [OutputType([hashtable])] param( [Parameter(Mandatory = $false)] [PSCredential]$Credential, [Parameter(Mandatory = $false)] [bool]$ShowBanner = $true, [Parameter(Mandatory = $false)] [switch]$Force ) begin { Write-Verbose "Starting Connect-PurviewDLP" } process { try { # Display connection banner if ($ShowBanner) { Write-Banner -Message "Security & Compliance Center Connection" -Type "Info" } # Check if ExchangeOnlineManagement module is installed Write-ColorOutput "Checking for required modules..." -Type Info if (-not (Test-ModuleInstalled -ModuleName "ExchangeOnlineManagement")) { Write-ColorOutput "ExchangeOnlineManagement module is required." -Type Warning $install = Read-Host "Would you like to install it now? (Y/N)" if ($install -eq "Y" -or $install -eq "y") { if (-not (Install-RequiredModule -ModuleName "ExchangeOnlineManagement")) { throw "Cannot proceed without ExchangeOnlineManagement module." } } else { throw "ExchangeOnlineManagement module is required. Please install it manually: Install-Module -Name ExchangeOnlineManagement" } } else { Write-ColorOutput "✓ ExchangeOnlineManagement module found." -Type Success } # Import the module Write-ColorOutput "Importing ExchangeOnlineManagement module..." -Type Info Import-Module ExchangeOnlineManagement -ErrorAction Stop Write-ColorOutput "✓ Module imported successfully." -Type Success # Check if already connected (unless Force specified) if (-not $Force) { Write-ColorOutput "Checking existing connection..." -Type Info if (Test-SecurityComplianceConnection) { Write-ColorOutput "✓ Already connected to Security & Compliance Center." -Type Success # Get connection info $policies = Get-DlpCompliancePolicy -ErrorAction SilentlyContinue $policyCount = ($policies | Measure-Object).Count Write-Host "" Write-ColorOutput "Connection Details:" -Type Info Write-Host " - DLP Policies found: $policyCount" -ForegroundColor White Write-Host " - Connection time: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')" -ForegroundColor White if ($ShowBanner) { Write-Banner -Message "Connection Status: CONNECTED" -Type "Success" } return @{ Success = $true Message = "Already connected to Security & Compliance Center" AlreadyConnected = $true PolicyCount = $policyCount } } } else { Write-ColorOutput "Force flag specified - establishing new connection..." -Type Info } # Establish new connection Write-ColorOutput "Connecting to Security & Compliance Center..." -Type Info $connectParams = @{ ErrorAction = 'Stop' } if ($Credential) { $connectParams['Credential'] = $Credential Write-ColorOutput "Using provided credentials..." -Type Info } else { Write-ColorOutput "Using interactive authentication (MFA supported)..." -Type Info } # Connect to Security & Compliance Center Connect-IPPSSession @connectParams # Verify connection Write-ColorOutput "Verifying connection..." -Type Info if (Test-SecurityComplianceConnection) { Write-ColorOutput "✓ Successfully connected to Security & Compliance Center." -Type Success # Get connection info $policies = Get-DlpCompliancePolicy -ErrorAction SilentlyContinue $policyCount = ($policies | Measure-Object).Count Write-Host "" Write-ColorOutput "Connection Details:" -Type Info Write-Host " - DLP Policies found: $policyCount" -ForegroundColor White Write-Host " - Connection time: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')" -ForegroundColor White if ($ShowBanner) { Write-Banner -Message "Connection Status: CONNECTED" -Type "Success" } return @{ Success = $true Message = "Successfully connected to Security & Compliance Center" PolicyCount = $policyCount AlreadyConnected = $false } } else { throw "Connection established but verification failed." } } catch { $errorMessage = $_.Exception.Message Write-Host "" Write-ColorOutput "✗ Connection failed." -Type Error Write-ColorOutput "Error: $errorMessage" -Type Error Write-Host "" Write-ColorOutput "Troubleshooting tips:" -Type Warning Write-Host " 1. Ensure you have appropriate permissions for Security & Compliance Center" -ForegroundColor White Write-Host " 2. Check your network connectivity" -ForegroundColor White Write-Host " 3. Verify Multi-Factor Authentication is configured if required" -ForegroundColor White Write-Host " 4. Try: Install-Module ExchangeOnlineManagement -Force" -ForegroundColor White Write-Host " 5. Ensure you have one of these roles:" -ForegroundColor White Write-Host " - Compliance Administrator" -ForegroundColor Gray Write-Host " - Security Administrator" -ForegroundColor Gray Write-Host " - Global Administrator" -ForegroundColor Gray if ($ShowBanner) { Write-Banner -Message "Connection Status: FAILED" -Type "Error" } # Return error result (don't throw, let caller decide) return @{ Success = $false Message = $errorMessage AlreadyConnected = $false PolicyCount = 0 } } } end { Write-Verbose "Connect-PurviewDLP completed" } } |