BitTitan.Runbooks.Office365SecurityAndCompliance.Beta.psm1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
<#
.SYNOPSIS
    PowerShell module for common Office 365 Security and Compliance Center functions and resources used in BitTitan Runbooks.
.NOTES
    Version: 0.2
    Last updated: 14 October 2018
 
    Copyright (c) BitTitan, Inc. All rights reserved.
    Licensed under the MIT License.
#>


# Install/import BitTitan.Runbooks.Modules to bootstrap the install/import of the other modules
Install-Module BitTitan.Runbooks.Modules -Scope CurrentUser -AllowClobber
Import-Module BitTitan.Runbooks.Modules -Force

# Install/import the other BitTitan.Runbooks modules
Import-BT_Module BitTitan.Runbooks.MSPComplete 1>$null

<#
.SYNOPSIS
    This function connects to Office 365 Security and Compliance Center using admin account credentials or a MSPComplete Endpoint.
.DESCRIPTION
    This function connects to Office 365 Security and Compliance Center using admin account credentials or a MSPComplete Endpoint.
    It returns whether the connection and logon was successful.
.EXAMPLE
    Connect-Office365SecurityAndComplianceAdminAccount -Endpoint $Endpoint
.EXAMPLE
    $Endpoint | Connect-Office365SecurityAndComplianceAdminAccount
.EXAMPLE
    Connect-Office365SecurityAndComplianceAdminAccount -Username $username -Password $password
#>

function Connect-Office365SecurityAndComplianceAdminAccount {
    param (
        # The username of the Office 365 Security and Compliance Center admin account.
        [Parameter(Mandatory=$true, ParameterSetName="credential")]
        [string]$username,

        # The password of the Office 365 Security and Compliance Center admin account.
        [Parameter(Mandatory=$true, ParameterSetName="credential")]
        [SecureString]$password,

        # The MSPComplete Endpoint for the Office 365 Security and Compliance Center admin credentials.
        [Parameter(Mandatory=$true, ParameterSetName="endpoint", ValueFromPipeline=$true)]
        $endpoint
    )

    # If given endpoint, retrieve username and password
    if ($PSCmdlet.ParameterSetName -eq "endpoint") {
        $office365Credential = $endpoint | Get-CredentialFromMSPCompleteEndpoint
        $username = $office365Credential.Username
    }
    # Create the Office 365 Security and Compliance Center credential from the given username and password
    else {
        $office365Credential = New-Object System.Management.Automation.PSCredential($username, $password)
    }

    # Logon to Office 365 Security and Compliance Center
    try {
        $office365Session = New-PSSession -ConfigurationName Microsoft.Exchange `
            -ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid/ `
            -Credential $office365Credential -Authentication Basic -AllowRedirection -Name "Office365SecurityAndCompliance"

        # Additional Import-Module ensures that imported cmdlets are visible globally
        Import-Module (Import-PSSession $office365Session -DisableNameChecking -AllowClobber -Prefix "SC_") -Global

        # Logon was successful
        Write-Information "Logon to Office 365 Security and Compliance Center successful with username '$($username)'."
        return $true
    }
    catch {
        # Logon was unsuccessful
        Write-Error "Failed Office 365 Security and Compliance Center logon with username '$($username)'. $($_.Exception.Message)"
        return $false
    }
}

<#
.SYNOPSIS
    This function disconnects from the current Office 365 Security and Compliance Center session.
.DESCRIPTION
    This function disconnects from the current Office 365 Security and Compliance Center session
    It returns whether the disconnect was successful.
#>

function Disconnect-Office365SecurityAndCompliance {
    # Retrieve sessions
    $office365Session = Get-PSSession | Where-Object { $_.Name -eq "Office365SecurityAndCompliance" }

    # There is at least one existing session
    if ($office365Session) {
        # There is more than one existing session
        if ($office365Session.length -and $office365Session.length -gt 1) {
            foreach ($session in $office365Session) {
                $session | Remove-PSSession
            }
        }

        # There is only one existing session
        else {
            $office365Session | Remove-PSSession
        }
        return $true
    }

    # There are no existing sessions
    else {
        Write-Warning "Attempting to disconnect Office 365 Security and Compliance Center session when there isn't one running."
        return $false
    }
}