Functions/Connect-PartnerCenterAdminAccount.ps1

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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
<#
.SYNOPSIS
    This function connects to Partner Center using credentials or a MSPComplete Endpoint.
.DESCRIPTION
    This function connects to Partner Center using credentials or a MSPComplete Endpoint.
    It returns whether the connection and logon was successful.
    It currently supports either app + user authentication, or app-only authentication.
    App + user authentication will be disabled by Microsoft as of 4 February 2019.
    After that, only app-only authentication will be allowed.
    TODO: RUN-1225 - KB for step-by-step to retrieve web app application ID, application secret, and tenant ID
#>

function Connect-PartnerCenterAdminAccount {
    [CmdletBinding(PositionalBinding=$false)]
    [OutputType([Bool])]
    param (
        # The username of the Partner Center admin account.
        [Parameter(Mandatory=$true, ParameterSetName="credential")]
        [ValidateNotNullOrEmpty()]
        [String]$username,

        # The password of the Partner Center admin account.
        [Parameter(Mandatory=$true, ParameterSetName="credential")]
        [ValidateNotNull()]
        [SecureString]$password,

        # The Partner Center Native App application Id, or the Web App application Id.
        # The Native App application Id is used when connecting using user credentials,
        # and the Web App application Id is used when connecting using an application secret.
        [Parameter(Mandatory=$true, ParameterSetName="credential")]
        [Parameter(Mandatory=$true, ParameterSetName="servicePrincipal")]
        [ValidateNotNull()]
        [GUID]$applicationId,

        # The Partner Center Web App application secret
        [Parameter(Mandatory=$true, ParameterSetName="servicePrincipal")]
        [ValidateNotNull()]
        [SecureString]$applicationSecret,

        # The Office 365 tenant Id
        [Parameter(Mandatory=$true, ParameterSetName="servicePrincipal")]
        [ValidateNotNull()]
        [GUID]$tenantId,

        # The MSPComplete Endpoint for the Partner Center admin credentials.
        [Parameter(Mandatory=$true, ParameterSetName="endpoint", ValueFromPipeline=$true)]
        [ValidateNotNull()]
        $endpoint,

        # Select the stream where the failure messages will be directed.
        [Parameter(Mandatory=$false)]
        [ValidateSet("Information", "Warning", "Error")]
        [String]$outputStream = "Error"
    )

    # Track the authentication method used
    $authentication = ""

    # Extract the values from the endpoint
    if ($PSCmdlet.ParameterSetName -eq "endpoint") {
        $credential = $endpoint.Credential
        $username = $credential.Username
        $password = $credential.Password

        # Using app + user authentication
        if (Test-EmailAddressValidity -EmailAddress $username) {
            $authentication = "appUser"

            # Retrieve the application ID from the endpoint's extended properties
            if ([String]::IsNullOrWhiteSpace($endpoint.ExtendedProperties.ApplicationId)) {
                Write-OutputMessage "The endpoint provided does not have an 'ApplicationId' extended property." `
                    -OutputStream $outputStream | Out-Null
                return $false
            }
            $applicationId = $endpoint.ExtendedProperties.ApplicationId
        }

        # Using app-only authentication
        else {
            $authentication = "appOnly"
            $applicationId = $username
            $applicationSecret = $password
            $credential = [PSCredential]::new($applicationId, $applicationSecret)

            # Retrieve the tenant ID from the endpoint's extended properties
            if ([String]::IsNullOrWhiteSpace($endpoint.ExtendedProperties.TenantId)) {
                Write-OutputMessage "The endpoint provided does not have an 'TenantId' extended property." `
                    -OutputStream $outputStream | Out-Null
                return $false
            }
            $tenantId = $endpoint.ExtendedProperties.TenantId
        }
    }

    # Retrieve the authentication method to use based on the parameter set name
    elseif ($PSCmdlet.ParameterSetName -eq "credential") {
        $authentication = "appUser"
        $credential = [PSCredential]::new($username, $password)
    }
    else {
        $authentication = "appOnly"
        $credential = [PSCredential]::new($applicationId, $applicationSecret)
    }

    # Connect to Partner Center
    # Connect using app + user authentication
    if ($authentication -eq "appUser") {
        try {
            Write-Warning ("Using app + user authentication to connect to Partner Center." + $CRLF `
                + "This authentication method will no longer be supported by Microsoft as of 4 February 2019." + $CRLF `
                + "Switch to app-only authentication to continue to connect to Partner Center.")
            Write-Information "Connecting to Partner Center with username '$($username)' and application ID '$($applicationId)'."
            Connect-PartnerCenter -ApplicationId $applicationId -Credential $credential -ErrorAction Stop
        }
        catch {
            Write-OutputMessage "Exception occurred while connecting to Partner Center.`r`n$($_.Exception.Message)" `
                -OutputStream $outputStream | Out-Null
            return $false
        }
    }

    # Connect using app-only authentication
    else {
        try {
            Write-Information "Connecting to Partner Center with application Id $($applicationId)."
            Connect-PartnerCenter -Credential $credential -ServicePrincipal -TenantId $tenantId
        }
        catch {
            Write-OutputMessage "Exception occurred while connecting to Partner Center.`r`n$($_.Exception.Message)" `
                -OutputStream $outputStream | Out-Null
            return $false
        }
    }

    # Successfully connected
    return $true
}