Endpoints.psm1

<#
.SYNOPSIS
    This function retrieves the credential (username + password) from a MSPComplete Endpoint.
.DESCRIPTION
    This function retrieves the credential (username + password) from a MSPComplete Endpoint.
    There is no pre-processing required on the Endpoint, whether it is passed in using
    the MSPComplete platform or retrieved using Get-BT_Endpoint.
.PARAMETER endpointID
    The ID of the MSPComplete Endpoint.
.PARAMETER endpoint
    The MSPComplete Endpoint.
.PARAMETER ticket
    The MSPComplete Customer Ticket.
.PARAMETER environment
    The Environment where the Endpoint is stored.
.EXAMPLE
    $unmaskedEndpoint = Get-CredentialFromMSPCompleteEndpoint -EndpointID $Endpoint.Id
.EXAMPLE
    $unmaskedEndpoint = Get-CredentialFromMSPCompleteEndpoint -Endpoint $Endpoint
.EXAMPLE
    $unmaskedEndpoint = $Endpoint | Get-CredentialFromMSPCompleteEndpoint
#>

function Get-CredentialFromMSPCompleteEndpoint {
    param (
        # The ID of the MSPComplete Endpoint
        [Parameter(Mandatory=$true, ParameterSetName="endpointID")]
        [String]$endpointID,

        # The MSPComplete Endpoint
        [Parameter(Mandatory=$true, ParameterSetName="endpoint", ValueFromPipeline=$true)]
        $endpoint,

        # The MSPComplete Ticket
        [Parameter(Mandatory=$false)]
        $ticket = $mspc.Ticket,

        # The environment where the endpoint is stored.
        [Parameter(Mandatory=$false)]
        [ValidateSet("BT", "Beta", "Develop", "Release")]
        [String]$environment = "Beta"
    )

    # Endpoint is provided and it already has a "Credential" property
    # This case applies when the endpoint is passed in on the MSPC platform
    if ($null -ne $endpoint.Credential -and ![String]::IsNullOrWhiteSpace($endpoint.Credential.UserName) -and $null -ne $endpoint.Credential.Password) {
        Write-Information "Using the 'Credential' property from the Endpoint '$($endpoint.Name)'."
        return $endpoint.Credential
    }

    # Retrieve the endpoint ID from the endpoint
    if ($PSCmdlet.ParameterSetName -eq "endpoint") {
        $endpointID = $endpoint.Id
    }

    # Retrieve the endpoint with a credential property, and return the credential
    Write-Information "Retrieving the Endpoint with a 'Credential' property."
    return (Get-MSPCompleteEndpointWithCredential -EndpointID $endpointID -Ticket $ticket -Environment $environment).Credential
}

<#
.SYNOPSIS
    This function retrieves a copy of the given MSPComplete Endpoint with a "Credential" property.
.DESCRIPTION
    This function retrieves a copy of the given MSPComplete Endpoint with a "Credential" property.
    The property is a PSCredential object storing the username and password.
.PARAMETER endpointID
    The ID of the MSPComplete Endpoint.
.PARAMETER endpoint
    The MSPComplete Endpoint.
.PARAMETER ticket
    The MSPComplete Ticket.
.PARAMETER environment
    The Environment where the Endpoint is stored.
.EXAMPLE
    Get-MSPCompleteEndpointWithCredential -EndpointID $Endpoint.Id
.EXAMPLE
    Get-MSPCompleteEndpointWithCredential -Endpoint $Endpoint
.EXAMPLE
    $Endpoint | Get-MSPCompleteEndpointWithCredential
#>

function Get-MSPCompleteEndpointWithCredential {
    param (
        # The ID of the MSPComplete Endpoint.
        [Parameter(Mandatory=$true, ParameterSetName="endpointID")]
        [String]$endpointID,

        # The MSPComplete Endpoint.
        [Parameter(Mandatory=$true, ParameterSetName="endpoint", ValueFromPipeline=$true)]
        $endpoint,

        # The MSPComplete Ticket.
        [Parameter(Mandatory=$false)]
        $ticket = $mspc.Ticket,

        # The environment where the endpoint is stored.
        [Parameter(Mandatory=$false)]
        [ValidateSet("BT", "Beta", "Develop", "Release")]
        [String]$environment = "Beta"
    )

    # Retrieve the endpoint ID from the endpoint
    if ($PSCmdlet.ParameterSetName -eq "endpoint") {
        $endpointID = $endpoint.Id
    }

    # Retrieve the masked endpoint to return later
    else {
        try {
            $endpoint = Get-BT_Endpoint -Ticket $ticket -Id $endpointID -Environment $environment
        }
        catch {
            Write-Error "Error while retrieving masked endpoint with ID '$($endpointID)'. `r`n$($_.Exception.Message)"
            return $null
        }
        if ($null -eq $endpoint) {
            Write-Error "Failed to retrieve masked endpoint with ID '$($endpointID)'."
            return $null
        }
    }

    # Try to retrieve the unmasked endpoint using the endpoint ID
    try {
        # Create hash table to store params
        $getBTEndpointParams = @{
            Ticket                  = $ticket
            Id                      = $endpointID
            ShouldUnmaskProperties  = $true
            Environment             = $environment
        }

        # Get the unmasked endpoint using the endpoint ID
        $unmaskedEndpoint = Get-BT_Endpoint @getBTEndpointParams
    }

    # Error while retrieving unmasked endpoint
    catch {
        Write-Error "Error while retrieving the unmasked Endpoint with ID '$($endpointID)'. `r`n$($_.Exception.Message)"
        return $null
    }

    # Verify endpoint
    if ($null -eq $unmaskedEndpoint) {
        Write-Error "Failed to retrieve the unmasked Endpoint with ID '$($endpointID)'."
        return $null
    }

    # Create the credential object
    # Endpoint contains exchange configuration
    if ($unmaskedEndpoint.Configuration.GetType() -eq [ManagementProxy.ManagementService.ExchangeConfiguration]) {
        $credential = New-Object System.Management.Automation.PSCredential(
            $unmaskedEndpoint.Configuration.AdministrativeUserName,
            ($unmaskedEndpoint.Configuration.AdministrativePassword | ConvertTo-SecureString -AsPlainText -Force)
        )
    }

    # Endpoint contains generic configuration
    elseif ($unmaskedEndpoint.Configuration.GetType() -eq [ManagementProxy.ManagementService.GenericConfiguration]) {
        $credential = New-Object System.Management.Automation.PSCredential(
            $unmaskedEndpoint.Configuration.Username,
            ($unmaskedEndpoint.Configuration.Password | ConvertTo-SecureString -AsPlainText -Force)
        )
    }

    # Currently unsupported configuration type
    else {
        Write-Error "Endpoint '$($unmaskedEndpoint.Name)' has unsupported configuration type '$($endpoint.Configuration.GetType().Name)'."
    }

    # Add credential to masked endpoint
    $endpoint | Add-Member -NotePropertyName "Credential" -NotePropertyValue $credential -Force

    # Return masked endpoint with credential property
    return $endpoint
}