Connect-MS365.psm1
|
#.ExternalHelp Connect-MS365-help.xml <# .SYNOPSIS Connects to a given online service of Microsoft. .DESCRIPTION Connects to a given online service of Microsoft. One or multiple service names can be chosen. Supports connection handling for - Microsoft Online (MSOL) - Exchange Online (EOL) - Teams .PARAMETER Service Specifies the service to connect to. May be a list of multiple services to use. .PARAMETER MFA Toggles MFA usage. Not requesting PSCredential object. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE Connect-MS365 -Service MSOL .EXAMPLE Connect-MS365 -Service MSOL -MFA .EXAMPLE Connect-MS365 -Service MSOL,EOL -MFA .LINK https://github.com/blindzero/Connect-MS365 #> function Connect-MS365 { [OutputType()] [CmdletBinding(DefaultParameterSetName)] param ( #service parameter to define to which services to connect to #are validated against available / implemented services [Parameter(Mandatory=$True, Position = 1)] [ValidateSet('MSOL','EOL','Teams')] [string[]] $Service, #mfa parameter if mfa authentication is necessary #used later to determine different connection commands and is not using PScredential object [Parameter(Mandatory=$False, Position = 2, ParameterSetName = 'MFA')] [Switch] $MFA, #Credential parameter to receive previously created PSCredential object. #Primarily needed for testing calls [Parameter(Mandatory = $False, Position = 3, ParameterSetName = 'Credential')] [PSCredential] $Credential ) # dont gather PSCredential object if MFA is set If (($MFA -ne $True) -and (!($Credential))) { Write-Verbose "Gathering PSCredentials object for non MFA sign on" $Credential = Get-Credential -Message "Please enter your Office 365 credentials" } # iterating through each service listed in service parameter # each service is passing PSCredential object if MFA not set or leaves it out if set ForEach ($ServiceItem in $Service) { Write-Verbose "Create session to Service $ServiceItem" Switch($ServiceItem) { # Microsoft Online service MSOL { if ($MFA) { Connect-MSOL } else { Connect-MSOL -Credential $Credential } continue } # Exchange Online service EOL { if ($MFA) { Connect-EOL } else { Connect-EOL -Credential $Credential } continue } # Exchange Online service Teams { if ($MFA) { Connect-Teams } else { Connect-Teams -Credential $Credential } continue } } Write-Verbose "Create session to Service $ServiceItem done." } Write-Verbose "Connect-MS365 terminated." } # Export only the functions using PowerShell standard verb-noun naming. # Be sure to list each exported functions in the FunctionsToExport field of the module manifest file. # This improves performance of command discovery in PowerShell. Export-ModuleMember -Function Connect-MS365 function Install-MS365Module { [CmdletBinding()] param ( # service module to be installed, must be known service [Parameter(Mandatory=$True,Position=1)] [ValidateSet('MSOL','EOL','Teams')] [String] $Service ) <# .SYNOPSIS Installs modules to connect for a given service. .DESCRIPTION Installs modules to connect for a given service. Service name needs to be passed. .PARAMETER Service Name of service to check installed modules for. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE Install-MS365Module -Service MSOL .LINK http://github.com/blindzero/Connect-MS365 #> switch($Service) { MSOL { $ModuleName = "MSOnline" } EOL { $ModuleName = "ExchangeOnlineManagement" } Teams { $ModuleName = "MicrosoftTeams" } } $InstallCommand = "-Command &{ Install-Module -Name $ModuleName -Scope AllUsers }" $InstallChoice = Read-Host -Prompt "$ModuleName Module is not present! Install it (Y/n)" If (($InstallChoice -eq "") -or ($InstallChoice -eq "y") -or ($InstallChoice -eq "Y")) { try { Start-Process -Filepath powershell -ArgumentList $InstallCommand -Verb RunAs -Wait } catch { $ErrorMessage = $_.Exception.Message Write-Error -Message "Could not install Module $ModuleName.`n$ErrorMessage" -Category ConnectionError Break } continue } } function Set-WindowTitle { [CmdletBinding()] param ( [Parameter(Mandatory=$True,Position=1)] [String] $Service ) <# .SYNOPSIS Sets Window Title if connection was successful. .DESCRIPTION Sets Window Title if connection was successful. Adds prefix if not already set. .PARAMETER Service Name of service to put in Window title. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE Set-WindowTitle -Service MSOL .LINK http://github.com/blindzero/Connect-MS365 #> If (($host.ui.RawUI.WindowTitle) -notlike "*$ServiceItem*" ) { If (($host.ui.RawUI.WindowTitle) -notlike "*Connected To:*") { $host.ui.RawUI.WindowTitle += " -- Connected To: $ServiceItem" } Else { $host.ui.RawUI.WindowTitle += " || $ServiceItem" } } } function Test-MS365Module { [CmdletBinding()] param ( # service module to be tested, must be known service [Parameter(Mandatory=$True,Position=1)] [ValidateSet('MSOL','EOL','Teams')] [String] $Service ) <# .SYNOPSIS Checks if a module of a given service to connect is installed. .DESCRIPTION Checks if a module of a given service to connect is installed. Service name needs to be passed. .PARAMETER Service Name of service to check installed modules for. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE Test-MS365Module -Service MSOL .LINK http://github.com/blindzero/Connect-MS365 #> # Set Splatting argument list for Get-Module used to determine if module is existing $GetModulesSplat = @{ ListAvailable = $True Verbose = $False } # TODO #10: changing to settings array containing module names making switch unnecessary Switch($Service) { # Microsoft Online Service MSOL { If ($null -eq (Get-Module @GetModulesSplat -Name "MSOnline")) { $False } Else { $True } } # Exchange Online Service EOL { If ($null -eq (Get-Module @GetModulesSplat -Name "ExchangeOnlineManagement")) { $False } Else { $True } } # Teams Teams { If ($null -eq (Get-Module @GetModulesSplat -Name "MicrosoftTeams")) { $False } Else { $True } } } } function Connect-EOL { [CmdletBinding()] param ( [Parameter(Mandatory=$False,Position=1)] [PSCredential] $Credential ) <# .SYNOPSIS Connects to Microsoft Exchange Online service. .DESCRIPTION Connects to Microsoft Exchange Online service. .PARAMETER Credential PSCredential object containing user credentials. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE PS> Connect-EOL -Credential $Credential .LINK http://github.com/blindzero/Connect-MS365 #> # testing if module is available while (!(Test-MS365Module -Service $ServiceItem)) { # and install if not available Install-MS365Module -Service $ServiceItem } try { # if MFA is set connect without PScredential object as modern authentication will be used if ($MFA) { Connect-ExchangeOnline -ShowProgress $true } # or pass PSCredential object it will asked if not created earlier else { Connect-ExchangeOnline -Credential $Credential -ShowProgress $true } } catch { $ErrorMessage = $_.Exception.Message Write-Error -Message "Could not connect to $ServiceItem.`n$ErrorMessage" -Category ConnectionError Break } # set service name into window title if successfully connected Set-WindowTitle -Service $ServiceItem } function Connect-MSOL { [CmdletBinding()] param ( [Parameter(Mandatory=$False,Position=1)] [PSCredential] $Credential ) <# .SYNOPSIS Connects to Microsoft Online service. .DESCRIPTION Connects to Microsoft Online service. .PARAMETER Credential PSCredential object containing user credentials. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE PS> Connect-MSOL -Credential $Credential .LINK http://github.com/blindzero/Connect-MS365 #> # testing if module is available while (!(Test-MS365Module -Service $ServiceItem)) { # and install if not available Install-MS365Module -Service $ServiceItem } try { # if MFA is set connect without PScredential object as modern authentication will be used if ($MFA) { Connect-MsolService -ErrorAction Stop } # or pass PSCredential object it will asked if not created earlier else { Connect-MsolService -Credential $Credential -ErrorAction Stop } } catch { $ErrorMessage = $_.Exception.Message Write-Error -Message "Could not connect to $ServiceItem.`n$ErrorMessage" -Category ConnectionError Break } # set service name into window title if successfully connected Set-WindowTitle -Service $ServiceItem } function Connect-Teams { [CmdletBinding()] param ( [Parameter(Mandatory=$False,Position=1)] [PSCredential] $Credential ) <# .SYNOPSIS Connects to Microsoft Teams service. .DESCRIPTION Connects to Microsoft Teams service. .PARAMETER Credential PSCredential object containing user credentials. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE PS> Connect-Teams -Credential $Credential .LINK http://github.com/blindzero/Connect-MS365 #> # testing if module is available while (!(Test-MS365Module -Service $ServiceItem)) { # and install if not available Install-MS365Module -Service $ServiceItem } try { # if MFA is set connect without PScredential object as modern authentication will be used if ($MFA) { Connect-MicrosoftTeams -ErrorAction Stop | Out-Null } # or pass PSCredential object it will asked if not created earlier else { Connect-MicrosoftTeams -Credential $Credential -ErrorAction Stop | Out-Null } } catch { $ErrorMessage = $_.Exception.Message Write-Error -Message "Could not connect to $ServiceItem.`n$ErrorMessage" -Category ConnectionError Break } # set service name into window title if successfully connected Set-WindowTitle -Service $ServiceItem } |