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) - aka AzureAD v1 - Exchange Online (EOL) - Teams - SharePoint Online (SPO) - Security and Compliance Center (SCC) - Azure ActiveDirectory (AAD) v2 - Azure Platform (AZ) .PARAMETER Service Specifies the service to connect to. May be a list of multiple services to use. .INPUTS None. You cannot pipe objects to Connect-MS365. .EXAMPLE Description: Connect to Microsoft Online Connect-MS365 -Service MSOL .EXAMPLE Description: Connect to Microsoft Online and Exchange Online Connect-MS365 -Service MSOL,EOL .EXAMPLE Description: Connect to SharePoint Online to connect to MyName-admin.sharepoint.com Connect-MS365 -Service SPO -SPOOrgName MyName .EXAMPLE Description: Connect to Security and Compliance Center Connect-MS365 -Service SCC .EXAMPLE Description: Connect to Azure ActiveDirectory Connect-MS365 -Service AAD .EXAMPLE Description: Connect to Microsoft Azure platform Connect-MS365 -Service AZ .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','SPO','SCC','AAD','AZ')] [string[]] $Service, #spoorg parameter for connection to SPO service #needed by connect cmdlet to assemble admin Url [Parameter(Mandatory=$False, Position = 2)] [string] [Alias('SPOOrg')] $SPOOrgName, #Credential parameter to receive previously created PSCredential object. #Primarily needed for testing calls [Parameter(Mandatory=$False, Position = 3, ParameterSetName = 'Credential')] [PSCredential] $Credential ) # TODO #10: changing to settings array containing module names making switch unnecessary # iterating through each service listed in service parameter ForEach ($ServiceItem in $Service) { Write-Verbose "Create session to Service $ServiceItem" Switch($ServiceItem) { # Microsoft Online service MSOL { $ServiceName = "Microsoft Online / AzureAD v1" $ModuleName = "MSOnline" $ModuleFindString = $ModuleName Connect-MSOL continue } # Exchange Online service EOL { $ServiceName = "Exchange Online" $ModuleName = "ExchangeOnlineManagement" $ModuleFindString = $ModuleName Connect-EOL continue } # Teams service Teams { $ServiceName = "Microsoft Teams" $ModuleName = "MicrosoftTeams" $ModuleFindString = $ModuleName Connect-Teams continue } # Security and Compliance Center SCC { $ServiceName = "Security & Compliance Center" $ModuleName = "ExchangeOnlineManagement" $ModuleFindString = $ModuleName Connect-SCC continue } # AzureAD AAD { $ServiceName = "AzureAD v2" $ModuleName = "AzureAD" $ModuleFindString = $ModuleName Connect-AAD continue } # Azure AZ { $ServiceName = "Azure" $ModuleName = "Az" $ModuleFindString = "Az.*" Connect-AZ continue } # SPO service SPO { $ServiceName = "SharePoint Online" $ModuleName = "Microsoft.Online.SharePoint.PowerShell" $ModuleFindString = $ModuleName If (!($SPOOrgName)) { Write-Error 'To connect to SharePoint Online you have to provide the -SPOOrgName parameter.' continue } Else { Write-Verbose "Assembling SPOOrgUrl from $SPOOrgName" $SPOOrgUrl = "https://$($SPOOrgName)-admin.sharepoint.com" Write-Verbose "Created $SPOOrgUrl" } Write-Verbose "Connecting to SharePoint Online at $SPOOrgUrl" Connect-SPO -SPOOrgUrl $SPOOrgUrl continue } } Write-Verbose "Create session to Service $ServiceItem done." } Write-Verbose "Connect-MS365 done." } # 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)] [String] $Module ) <# .SYNOPSIS Installs modules to connect for a given service. .DESCRIPTION Installs modules to connect for a given service. ModuleName name needs to be passed. .PARAMETER Module Name of powershell module to install. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE Install-MS365Module -Module MSOnline .LINK http://github.com/blindzero/Connect-MS365 #> $InstallCommand = "-Command &{ Install-Module -Name $Module -Scope AllUsers -Force}" $InstallChoice = Read-Host -Prompt "Module $Module is not present or update was triggered. Perform Install? (Y/n)" If (($InstallChoice.Length -eq 0) -or ($InstallChoice.ToLower() -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)] [String] $Module ) <# .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 Module Name of module to check installation. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE Test-MS365Module -Module MSOnline .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 } # Finding installed module, will be $null if not available on system $ModuleInstalled = (Get-Module @GetModulesSplat -Name $ModuleFindString) # Extracting Version of installed module if ($ModuleInstalled) { $ModuleInstalledVer = $ModuleInstalled.Version.ToString() } # Finding available module online $ModuleAvailable = (Find-Module -Name $ModuleFindString) # Extracting Version of available module online if ($ModuleAvailable) { $ModuleAvailableVer = $ModuleAvailable.Version.ToString() } # initialize $TestResult $TestResult = $Null # return $false if module is not installed If ($null -eq $ModuleInstalled) { Write-Verbose "$ModuleName was not found." $TestResult = $False } Else { # otherwise compare installed and available version If ($ModuleInstalledVer -lt $ModuleAvailableVer) { # if newer version is available online prompt for update do { $confirm = Read-Host -Prompt "New $ModuleName version $ModuleAvailableVer is available (installed: $ModuleInstalledVer). Update? [Y/n]" if ($confirm.Length -eq 0) { $confirm = "y" } } while (($confirm.ToLower() -ne "n") -and ($confirm.ToLower() -ne "y")) # if confirmed ... If (($confirm.Length -eq 0) -or ($confirm.toLower() -eq "y")) { Write-Verbose "Updating Module $ModuleName from $ModuleInstalledVer to $ModuleAvailableVer" # return $False to be catched and update triggered $TestResult = $False } # if not confimed only do verbose logging and return true as update is optional Else { Write-Verbose "Skipping update of $ModuleName" $TestResult = $True } } Else { Write-Verbose "$ModuleName is latest available version $ModuleAvailableVer" $TestResult = $True } } return [Bool]$TestResult } function Connect-AAD { [CmdletBinding()] param ( [Parameter(Mandatory=$False,Position=1)] [PSCredential] $Credential ) <# .SYNOPSIS Connects to Microsoft Azure ActiveDirectory (AzureAD / AAD) service. .DESCRIPTION Connects to Microsoft Azure ActiveDirectory (AzureAD / AAD) service. .PARAMETER Credential PSCredential object containing user credentials. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE PS> Connect-AAD -Credential $Credential .LINK http://github.com/blindzero/Connect-MS365 #> # testing if module is available while (!(Test-MS365Module -Module $ModuleName)) { # and install if not available Install-MS365Module -Service $ServiceItem } try { Connect-AzureAD | 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 } function Connect-AZ { [CmdletBinding()] param ( ) <# .SYNOPSIS Connects to Microsoft Azure platform. .DESCRIPTION Connects to Microsoft Azure platform. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE PS> Connect-AZ -Credential $Credential .LINK http://github.com/blindzero/Connect-MS365 #> # testing if module is available while (!(Test-MS365Module -Module $ModuleName)) { # and install if not available Install-MS365Module -Module $ModuleName } try { Connect-AzAccount | 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 } 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 -Module $ModuleName)) { # and install if not available Install-MS365Module -Module $ModuleName } try { Connect-ExchangeOnline -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 / Azure ActiveDirectory v1 .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 -Module $ModuleName)) { # and install if not available Install-MS365Module -Module $ModuleName } try { Connect-MsolService -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-SCC { [CmdletBinding()] param ( [Parameter(Mandatory=$False,Position=1)] [PSCredential] $Credential ) <# .SYNOPSIS Connects to Microsoft Security and Comliance Center. .DESCRIPTION Connects to Microsoft Security and Comliance Center. .PARAMETER Credential PSCredential object containing user credentials. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE PS> Connect-SCC -Credential $Credential .LINK http://github.com/blindzero/Connect-MS365 #> # testing if module is available while (!(Test-MS365Module -Module $ModuleName)) { # and install if not available Install-MS365Module -Module $ModuleName } try { Connect-IPPSSession } 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-SPO { [CmdletBinding()] param ( [Parameter(Mandatory=$True,Position = 1)] [String] $SPOOrgUrl, [Parameter(Mandatory=$False,Position = 2)] [PSCredential] $Credential ) <# .SYNOPSIS Connects to Microsoft SharePoint Online service. .DESCRIPTION Connects to Microsoft SharePoint Online service. .PARAMETER SPOOrgUrl String object containing the SharePoint Online organization admin Url. .PARAMETER Credential PSCredential object containing user credentials. .INPUTS None. You cannot pipe objects to Add-Extension. .OUTPUTS // <OBJECTTYPE>. TBD. .EXAMPLE Description: Connect to SharePoint Online organisation MyName PS> Connect-SPO -SPOOrgName https://myname-admin.sharepoint.com .LINK http://github.com/blindzero/Connect-MS365 #> # testing if module is available while (!(Test-MS365Module -Module $ModuleName)) { # and install if not available Install-MS365Module -Module $ModuleName } try { Connect-SPOService -Url $SPOOrgUrl -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 } 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 -Module $ModuleName)) { # and install if not available Install-MS365Module -Module $ModuleName } try { Connect-MicrosoftTeams -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 } |