Public/Connect-EWSSession.ps1
|
function ConvertTo-EwsEndpointUri { param( [Parameter(Mandatory = $true)] [string]$Value ) $url = $Value.Trim() if ($url -notmatch '^(?i)https?://') { $url = $url.Replace('\', '/') if ($url -notmatch '/') { $url = '{0}/EWS/Exchange.asmx' -f $url } elseif ($url.EndsWith('/')) { $url = '{0}EWS/Exchange.asmx' -f $url } $url = 'https://{0}' -f $url } $uri = $null if (-not [uri]::TryCreate($url, [UriKind]::Absolute, [ref]$uri) -or $uri.Scheme -ne [Uri]::UriSchemeHttps -or [string]::IsNullOrEmpty($uri.Host) -or -not [string]::IsNullOrEmpty($uri.UserInfo)) { throw 'EwsUrl must be an HTTPS URL or a host/endpoint shorthand without embedded user information.' } $uri } function Connect-EWSSession { <# .SYNOPSIS Configures EWS connection settings for this module session. .DESCRIPTION Verifies that required Exchange Management Shell commands are available and loads ManagedStoreDiagnosticFunctions.ps1 from $exinstallpath when needed. Stores EWS connection defaults for the current PowerShell module session. By default, EWS uses the current Windows security context. A PSCredential can be supplied instead. If Identity is supplied, the function resolves the mailbox and validates EWS service setup. .PARAMETER Identity Optional mailbox SMTP address, alias, GUID, or other identity resolvable by Get-Mailbox. .PARAMETER EwsUrl Optional HTTPS EWS endpoint. A bare host defaults to /EWS/Exchange.asmx, and host/path input is prefixed with https://. If omitted, EWS Autodiscover is used. .PARAMETER EwsManagedApiPath Optional path to Microsoft.Exchange.WebServices.dll or its containing directory. .PARAMETER Credential Optional credential used with EWS WebCredentials. .PARAMETER UseDefaultCredentials Explicitly select the current Windows security context. This is the default when Credential is omitted. .PARAMETER ExchangeVersion EWS request schema version supported by the installed Managed API. .PARAMETER RequestTimeoutSeconds EWS request timeout in seconds. .PARAMETER RetryCount Default number of retries for transient EWS requests. Search and removal commands can override this per invocation. .PARAMETER TraceEnabled Enable safe connection trace logging. SOAP payloads and authorization headers are not written. .PARAMETER TraceFilePath Optional path for safe connection trace messages. .PARAMETER Impersonate Opt in to EWS mailbox impersonation for the resolved target mailbox. .PARAMETER TrustAll Opt in to bypass certificate validation for the explicit EWS URL authority only. This is insecure and intended only for controlled testing. It requires EwsUrl and remains active until Disconnect-EWSSession. .EXAMPLE Connect-EWSSession -EwsUrl mail.contoso.com .EXAMPLE Connect-EWSSession -Identity user@contoso.com -UseDefaultCredentials #> [CmdletBinding(DefaultParameterSetName = 'CurrentUser')] param( [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [string]$Identity, [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [ValidateNotNullOrEmpty()] [string]$EwsUrl, [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [ValidateNotNullOrEmpty()] [string]$EwsManagedApiPath, [Parameter(Mandatory = $true, ParameterSetName = 'Credential')] [System.Management.Automation.PSCredential]$Credential, [Parameter(ParameterSetName = 'CurrentUser')] [switch]$UseDefaultCredentials, [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [ValidateSet('Exchange2007_SP1', 'Exchange2010', 'Exchange2010_SP1', 'Exchange2010_SP2', 'Exchange2013', 'Exchange2013_SP1')] [string]$ExchangeVersion = 'Exchange2010', [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [ValidateRange(1, 600)] [int]$RequestTimeoutSeconds = 100, [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [ValidateRange(0, 10)] [int]$RetryCount = 3, [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [switch]$TraceEnabled, [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [ValidateNotNullOrEmpty()] [string]$TraceFilePath, [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [switch]$Impersonate , [Parameter(ParameterSetName = 'CurrentUser')] [Parameter(ParameterSetName = 'Credential')] [switch]$TrustAll ) if ($EwsUrl) { $configuredUri = ConvertTo-EwsEndpointUri -Value $EwsUrl $EwsUrl = $configuredUri.AbsoluteUri } if ($TrustAll -and -not $EwsUrl) { throw 'TrustAll requires an explicit HTTPS EwsUrl; it is not supported with Autodiscover.' } $exchangeShellStatus = Test-ExchangeManagementShell if ($TraceFilePath -and -not $TraceEnabled) { throw 'TraceFilePath requires TraceEnabled.' } if ($Credential -and $UseDefaultCredentials) { throw 'Specify either Credential or UseDefaultCredentials, not both.' } $authenticationMethod = if ($Credential) { 'PSCredential' } else { 'DefaultWindowsCredentials' } $authenticationIdentity = if ($Credential) { $Credential.UserName } else { [System.Security.Principal.WindowsIdentity]::GetCurrent().Name } $options = [pscustomobject]@{ EwsUrl = $EwsUrl EwsManagedApiPath = $EwsManagedApiPath Credential = $Credential UseDefaultCredentials = -not [bool]$Credential AuthenticationMethod = $authenticationMethod AuthenticationIdentity = $authenticationIdentity Identity = $Identity ExchangeVersion = $ExchangeVersion RequestTimeoutSeconds = $RequestTimeoutSeconds RetryCount = $RetryCount TraceEnabled = [bool]$TraceEnabled TraceFilePath = $TraceFilePath Impersonate = [bool]$Impersonate TrustAll = [bool]$TrustAll ExchangeManagementShellLoaded = $exchangeShellStatus.ExchangeManagementShellLoaded } Disable-EwsTrustAll Import-EwsManagedApi -Path $EwsManagedApiPath | Out-Null if ($TrustAll) { Write-Warning "TrustAll is enabled for the explicit EWS authority '$($configuredUri.Authority)'. Certificate mismatches will be accepted for that authority until Disconnect-EWSSession. Use only for controlled testing." Enable-EwsTrustAll -EwsUri $configuredUri } $script:ConnectionOptions = $options $script:EwsServiceCache = @{} if ($Identity) { $mailbox = Resolve-MailboxIdentity -Identity $Identity $service = New-EwsService -Mailbox $mailbox -Options $options $script:EwsServiceCache[$mailbox.PrimarySmtpAddress.ToLowerInvariant()] = $service } [pscustomobject]@{ PSTypeName = 'ExchangeNamedProperties.EWSSession' Connected = $true Identity = if ($Identity) { $Identity } else { $null } PrimarySmtpAddress = if ($Identity) { $mailbox.PrimarySmtpAddress } else { $null } EwsUrl = if ($Identity -and $service) { $service.Url.AbsoluteUri } else { $EwsUrl } Authentication = $authenticationMethod AuthenticationIdentity = $authenticationIdentity ImpersonationEnabled = [bool]$Impersonate TrustAll = [bool]$TrustAll } } |