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 .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 Description: Connect to Microsoft Online without using MFA Connect-MS365 -Service MSOL .EXAMPLE Description: Connect to Microsoft Online by using MFA Connect-MS365 -Service MSOL -MFA .EXAMPLE Description: Connect to Microsoft Online and Exchange Online by using MFA Connect-MS365 -Service MSOL,EOL -MFA .EXAMPLE Description: Connect to SharePoint Online without MFA to connect to MyName-admin.sharepoint.com Connect-MS365 -Service SPO -SPOOrgName MyName .EXAMPLE Description: Connect to SharePoint Online with MFA to connect to MyName-admin.sharepoint.com Connect-MS365 -Service SPO -SPOOrgName MyName -MFA .EXAMPLE Description: Connect to Security and Compliance Center with MFA Connect-MS365 -Service SCC -MFA .EXAMPLE Description: Connect to Azure ActiveDirectory with MFA Connect-MS365 -Service AAD -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','SPO','SCC','AAD')] [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, #mfa parameter if mfa authentication is necessary #used later to determine different connection commands and is not using PScredential object [Parameter(Mandatory=$False, Position = 3, 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 } # Teams service Teams { if ($MFA) { Connect-Teams } else { Connect-Teams -Credential $Credential } continue } # Security and Compliance Center SCC { if ($MFA) { Connect-SCC } else { Connect-SCC -Credential $Credential } continue } # AzureAD AAD { if ($MFA) { Connect-AAD } else { Connect-AAD -Credential $Credential } continue } # SPO service SPO { 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" } if ($MFA) { Write-Verbose "Connecting to SharePoint Online at $SPOOrgUrl without Credential" Connect-SPO -SPOOrgUrl $SPOOrgUrl } else { Write-Verbose "Connecting to SharePoint Online at $SPOOrgUrl with $Credential" Connect-SPO -SPOOrgUrl $SPOOrgUrl -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','SPO','SCC','AAD')] [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" } {($_ -eq "EOL") -or ($_ -eq "SCC")} { $ModuleName = "ExchangeOnlineManagement" } Teams { $ModuleName = "MicrosoftTeams" } SPO { $ModuleName = "Microsoft.Online.SharePoint.PowerShell" } AAD { $ModuleName = "AzureAD" } } $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','SPO','SCC','AAD')] [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 or Security Compliance Center {($_ -eq "EOL") -or ($_ -eq "SCC")} { If ($null -eq (Get-Module @GetModulesSplat -Name "ExchangeOnlineManagement")) { $False } Else { $True } } # Teams Teams { If ($null -eq (Get-Module @GetModulesSplat -Name "MicrosoftTeams")) { $False } Else { $True } } # SPO SPO { If ($null -eq (Get-Module @GetModulesSplat -Name "Microsoft.Online.SharePoint.PowerShell")) { $False } Else { $True } } # AzureAD AAD { If ($null -eq (Get-Module @GetModulesSplat -Name "AzureAD")) { $False } Else { $True } } } } 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 -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-AzureAD | Out-Null } # or pass PSCredential object it will asked if not created earlier else { Connect-AzureAD -Credential $Credential | 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 -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-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 -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-IPPSSession } # or pass PSCredential object it will asked if not created earlier else { Connect-IPPSSession -Credential $Credential } } 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 with PSCredential object passed (no MFA) PS> Connect-SPO -SPOOrgUrl https://myname-admin.sharepoint.com -Credential $Credential .EXAMPLE Description: Connect to SharePoint Online organisation MyName without PSCredential object passed (MFA) PS> Connect-SPO -SPOOrgName https://myname-admin.sharepoint.com .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-SPOService -Url $SPOOrgUrl -ErrorAction Stop | Out-Null } # or pass PSCredential object it will asked if not created earlier else { Connect-SPOService -Url $SPOOrgUrl -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 } 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 } |