BitTitan.Runbooks.ExchangeOnline.psm1
|
<#
.SYNOPSIS Powershell module for common Exchange Online functions and resources used in BitTitan Runbooks. .NOTES Version: 0.1.3 Last updated: 1 October 2018 Copyright (c) BitTitan, Inc. All rights reserved. Licensed under the MIT License. #> <# .SYNOPSIS This function connects to Exchange Online using admin account credentials or a MSPComplete Endpoint. .DESCRIPTION This function connects to Exchange Online using admin account credentials or a MSPComplete Endpoint. It returns whether the connection and logon was successful. .PARAMETER username The username of the Exchange Online admin account. .PARAMETER password The password of the Exchange Online admin account. .PARAMETER endpoint The MSPComplete Endpoint for the Exchange Online admin credentials. This endpoint can be masked or unmasked. .EXAMPLE Connect-ExchangeOnlineAdminAccount -Endpoint $Endpoint .EXAMPLE $Endpoint | Connect-ExchangeOnlineAdminAccount .EXAMPLE Connect-ExchangeOnlineAdminAccount -Username $username -Password $password #> function Connect-ExchangeOnlineAdminAccount { param ( # The username of the Exchange Online admin account. [Parameter(Mandatory=$true, ParameterSetName="credential")] [string]$username, # The password of the Exchange Online admin account. [Parameter(Mandatory=$true, ParameterSetName="credential")] [SecureString]$password, # The MSPComplete Endpoint for the Exchange Online admin credentials. [Parameter(Mandatory=$true, ParameterSetName="endpoint", ValueFromPipeline=$true)] $endpoint ) # If given endpoint, retrieve username and password if ($PSCmdlet.ParameterSetName -eq "endpoint") { $exchangeCredential = $endpoint | Get-CredentialFromMSPCompleteEndpoint $username = $exchangeCredential.Username } # Create the Exchange Online credential from the given username and password else { $exchangeCredential = New-Object System.Management.Automation.PSCredential($username, $password) } # Logon to Exchange Online try { $exchangeSession = New-PSSession -ConfigurationName Microsoft.Exchange ` -ConnectionUri https://outlook.office365.com/powershell-liveid/ ` -Credential $exchangeCredential -Authentication Basic -AllowRedirection -Name "ExchangeOnline" # Additional Import-Module ensures that imported cmdlets are visible globally Import-Module (Import-PSSession $exchangeSession -DisableNameChecking -AllowClobber) -Global # Logon was successful Write-Information "Logon to Exchange Online successful with username '$($username)'." return $true } catch { # Logon was unsuccessful Write-Error "Failed Exchange Online logon with username '$($username)'. $($_.Exception.Message)" return $false } } <# .SYNOPSIS This function disconnects from the current Exchange Online session. .DESCRIPTION This function disconnects from the current Exchange Online session It returns whether the disconnect was successful. #> function Disconnect-ExchangeOnline { # Retrieve sessions $exchangeOnlineSession = Get-PSSession | Where-Object { $_.Name -eq "ExchangeOnline" } # There is at least one existing session if ($null -ne $exchangeOnlineSession) { # There is more than one existing session if ($null -ne $exchangeOnlineSession.length -and $exchangeOnlineSession.length -gt 1) { foreach ($session in $exchangeOnlineSession) { $session | Remove-PSSession } } # There is only one existing session else { $exchangeOnlineSession | Remove-PSSession } return $true } # There are no existing sessions else { Write-Warning "Attempting to disconnect Exchange Online session when there isn't one running." return $false } } |