MSIdentityTools.psm1

#Requires -Version 5.1
#Requires -PSEdition Core,Desktop
#Requires -Module @{'ModuleVersion'='1.9.2';'ModuleName'='Microsoft.Graph.Authentication';'GUID'='883916f2-9184-46ee-b1f8-b6a2fb784cee'}

<#
.SYNOPSIS
    MSIdentityTools
.DESCRIPTION
    Tools for managing, troubleshooting, and reporting on various aspects of Microsoft Identity products and services, primarily Azure AD.
.NOTES
    ModuleVersion: 2.0.52
    GUID: 69790621-e75d-4303-b06e-02704b7ca42f
    Author: Microsoft Identity
    CompanyName: Microsoft Corporation
    Copyright: (c) 2023 Microsoft Corporation. All rights reserved.
.FUNCTIONALITY
    Add-MsIdServicePrincipal, Confirm-MsIdJwtTokenSignature, ConvertFrom-MsIdAadcAadConnectorSpaceDn, ConvertFrom-MsIdAadcSourceAnchor, ConvertFrom-MsIdUniqueTokenIdentifier, ConvertFrom-MsIdJwtToken, ConvertFrom-MsIdSamlMessage, Expand-MsIdJwtTokenPayload, Export-MsIdAppConsentGrantReport, Find-MsIdUnprotectedUsersWithAdminRoles, Get-MsIdProvisioningLogStatistics, Get-MsIdAdfsSamlToken, Get-MsIdAdfsWsFedToken, Get-MsIdAdfsWsTrustToken, Get-MsIdApplicationIdByAppId, Get-MsIdAuthorityUri, Get-MsIdAzureIpRange, Get-MsIdCrossTenantAccessActivity, Get-MsIdGroupWithExpiration, Get-MsIdMsftIdentityAssociation, Get-MsIdO365Endpoints, Get-MsIdOpenIdProviderConfiguration, Get-MsIdSamlFederationMetadata, Get-MsIdServicePrincipalIdByAppId, Get-MsIdUnmanagedExternalUser, Invoke-MsIdAzureAdSamlRequest, New-MsIdWsTrustRequest, New-MsIdClientSecret, New-MsIdSamlRequest, New-MsIdTemporaryUserPassword, Reset-MsIdExternalUser, Resolve-MsIdTenant, Revoke-MsIdServicePrincipalConsent, Set-MsIdWindowsTlsSettings, Resolve-MsIdAzureIpAddress, Show-MsIdJwtToken, Show-MsIdSamlToken, Test-MsIdAzureAdDeviceRegConnectivity, Test-MsIdCBATrustStoreConfiguration, Get-MsIdSigningKeyThumbprint, Update-MsIdApplicationSigningKeyThumbprint, Get-MsIdIsViralUser, Get-MsIdHasMicrosoftAccount, Get-MsIdGroupWritebackConfiguration, Update-MsIdGroupWritebackConfiguration, Get-MsIdUnredeemedInvitedUser, Get-MsIdAdfsSampleApp, Import-MsIdAdfsSampleApp, Import-MsIdAdfsSamplePolicy, Get-MsIdInactiveSignInUser, Set-MsIdServicePrincipalVisibleInMyApps, Split-MsIdEntitlementManagementConnectedOrganization
.LINK
    https://github.com/AzureAD/MSIdentityTools
#>


#region NestedModules Script(s)

#region Compress-Data.ps1

<#
.SYNOPSIS
    Compress data using DEFLATE (RFC 1951) and optionally GZIP file format (RFC 1952).
.DESCRIPTION

.EXAMPLE
    PS C:\>Compress-Data 'A string for compression'
    Compress string using Deflate.
.INPUTS
    System.String
.LINK
    https://github.com/jasoth/Utility.PS
#>

function Compress-Data {
    [CmdletBinding()]
    [Alias('Deflate-Data')]
    [OutputType([byte[]])]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [object] $InputObjects,
        # Output gzip format
        [Parameter(Mandatory = $false)]
        [switch] $GZip,
        # Level of compression
        [Parameter(Mandatory = $false)]
        [System.IO.Compression.CompressionLevel] $CompressionLevel = ([System.IO.Compression.CompressionLevel]::Optimal),
        # Input encoding to use for text strings
        [Parameter (Mandatory = $false)]
        [ValidateSet('Ascii', 'UTF32', 'UTF7', 'UTF8', 'BigEndianUnicode', 'Unicode')]
        [string] $Encoding = 'Default',
        # Set gzip OS header byte to unknown
        [Parameter(Mandatory = $false)]
        [switch] $GZipUnknownOS
    )

    begin {
        function Compress ([byte[]]$InputBytes, [bool]$GZip) {
            try {
                $streamInput = New-Object System.IO.MemoryStream -ArgumentList @($InputBytes, $false)
                try {
                    $streamOutput = New-Object System.IO.MemoryStream
                    try {
                        if ($GZip) {
                            $streamCompression = New-Object System.IO.Compression.GZipStream -ArgumentList $streamOutput, $CompressionLevel, $true
                        }
                        else {
                            $streamCompression = New-Object System.IO.Compression.DeflateStream -ArgumentList $streamOutput, $CompressionLevel, $true
                        }
                        $streamInput.CopyTo($streamCompression)
                    }
                    finally { $streamCompression.Dispose() }
                    if ($GZip) {
                        [void] $streamOutput.Seek(8, [System.IO.SeekOrigin]::Begin)
                        switch ($CompressionLevel) {
                            'Optimal' { $streamOutput.WriteByte(2) }
                            'Fastest' { $streamOutput.WriteByte(4) }
                            Default { $streamOutput.WriteByte(0) }
                        }
                        if ($GZipUnknownOS) { $streamOutput.WriteByte(255) }
                        elseif ($PSVersionTable.PSEdition -eq 'Desktop' -or $IsWindows) { $streamOutput.WriteByte(11) }
                        elseif ($IsLinux) { $streamOutput.WriteByte(3) }
                        elseif ($IsMacOS) { $streamOutput.WriteByte(7) }
                        else { $streamOutput.WriteByte(255) }
                    }
                    [byte[]] $OutputBytes = $streamOutput.ToArray()
                }
                finally { $streamOutput.Dispose() }
            }
            finally { $streamInput.Dispose() }

            Write-Output $OutputBytes -NoEnumerate
        }

        ## Create list to capture byte stream from piped input.
        [System.Collections.Generic.List[byte]] $listBytes = New-Object System.Collections.Generic.List[byte]
    }

    process {
        if ($InputObjects -is [byte[]]) {
            Write-Output (Compress $InputObjects -GZip:$GZip) -NoEnumerate
        }
        else {
            foreach ($InputObject in $InputObjects) {
                [byte[]] $InputBytes = $null
                if ($InputObject -is [byte]) {
                    ## Populate list with byte stream from piped input.
                    if ($listBytes.Count -eq 0) {
                        Write-Verbose 'Creating byte array from byte stream.'
                        Write-Warning ('For better performance when piping a single byte array, use "Write-Output $byteArray -NoEnumerate | {0}".' -f $MyInvocation.MyCommand)
                    }
                    $listBytes.Add($InputObject)
                }
                elseif ($InputObject -is [byte[]]) {
                    $InputBytes = $InputObject
                }
                elseif ($InputObject -is [string]) {
                    $InputBytes = [Text.Encoding]::$Encoding.GetBytes($InputObject)
                }
                elseif ($InputObject -is [bool] -or $InputObject -is [char] -or $InputObject -is [single] -or $InputObject -is [double] -or $InputObject -is [int16] -or $InputObject -is [int32] -or $InputObject -is [int64] -or $InputObject -is [uint16] -or $InputObject -is [uint32] -or $InputObject -is [uint64]) {
                    $InputBytes = [System.BitConverter]::GetBytes($InputObject)
                }
                elseif ($InputObject -is [guid]) {
                    $InputBytes = $InputObject.ToByteArray()
                }
                elseif ($InputObject -is [System.IO.FileSystemInfo]) {
                    if ($PSVersionTable.PSVersion -ge [version]'6.0') {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -AsByteStream
                    }
                    else {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -Encoding Byte
                    }
                }
                else {
                    ## Non-Terminating Error
                    $Exception = New-Object ArgumentException -ArgumentList ('Cannot compress input of type {0}.' -f $InputObject.GetType())
                    Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ParserError) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'CompressDataFailureTypeNotSupported' -TargetObject $InputObject
                }

                if ($null -ne $InputBytes -and $InputBytes.Count -gt 0) {
                    Write-Output (Compress $InputBytes -GZip:$GZip) -NoEnumerate
                }
            }
        }
    }

    end {
        ## Output captured byte stream from piped input.
        if ($listBytes.Count -gt 0) {
            Write-Output (Compress $listBytes.ToArray() -GZip:$GZip) -NoEnumerate
        }
    }
}

#endregion

#region Confirm-JsonWebSignature.ps1

<#
.SYNOPSIS
    Validate the digital signature for JSON Web Signature.
.EXAMPLE
    PS C:\>Confirm-JsonWebSignature $Base64JwsString -SigningCertificate $SigningCertificate
    Validate the JWS string was signed by provided certificate.
.INPUTS
    System.String
#>

function Confirm-JsonWebSignature {
    [CmdletBinding()]
    [Alias('Confirm-Jws')]
    [OutputType([bool])]
    param (
        # JSON Web Signature (JWS)
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $InputObjects,
        # Certificate used to sign the data
        [Parameter(Mandatory = $true)]
        [System.Security.Cryptography.X509Certificates.X509Certificate2] $SigningCertificate
    )

    process {
        foreach ($InputObject in $InputObjects) {
            $Jws = ConvertFrom-JsonWebSignature $InputObject
            $JwsData = $InputObject.Substring(0, $InputObject.LastIndexOf('.'))
            [Security.Cryptography.HashAlgorithmName] $HashAlgorithm = [Security.Cryptography.HashAlgorithmName]::"SHA$($Jws.Header.alg.Substring(2,3))"
            switch ($Jws.Header.alg.Substring(0, 2)) {
                'RS' {
                    $RSAKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPublicKey($SigningCertificate)
                    [bool] $Result = $RSAKey.VerifyData([System.Text.Encoding]::UTF8.GetBytes($JwsData), $Jws.Signature, $HashAlgorithm, [Security.Cryptography.RSASignaturePadding]::Pkcs1)
                }
                'PS' {
                    $RSAKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPublicKey($SigningCertificate)
                    [bool] $Result = $RSAKey.VerifyData([System.Text.Encoding]::UTF8.GetBytes($JwsData), $Jws.Signature, $HashAlgorithm, [Security.Cryptography.RSASignaturePadding]::Pss)
                }
                'ES' {
                    $ECDsaKey = [System.Security.Cryptography.X509Certificates.ECDsaCertificateExtensions]::GetECDsaPublicKey($SigningCertificate)
                    [bool] $Result = $ECDsaKey.VerifyData([System.Text.Encoding]::UTF8.GetBytes($JwsData), $Jws.Signature, $HashAlgorithm)
                }
            }
            Write-Output $Result
        }
    }
}

#endregion

#region ConvertFrom-Base64String.ps1

<#
.SYNOPSIS
    Convert Base64 String to Byte Array or Plain Text String.
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertFrom-Base64String "QSBzdHJpbmcgd2l0aCBiYXNlNjQgZW5jb2Rpbmc="
    Convert Base64 String to String with Default Encoding.
.EXAMPLE
    PS C:\>"QVNDSUkgc3RyaW5nIHdpdGggYmFzZTY0dXJsIGVuY29kaW5n" | ConvertFrom-Base64String -Base64Url -Encoding Ascii
    Convert Base64Url String to String with Ascii Encoding.
.EXAMPLE
    PS C:\>[guid](ConvertFrom-Base64String "5oIhNbCaFUGAe8NsiAKfpA==" -RawBytes)
    Convert Base64 String to GUID.
.INPUTS
    System.String
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertFrom-Base64String {
    [CmdletBinding()]
    [OutputType([byte[]], [string])]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $InputObjects,
        # Use base64url variant
        [Parameter (Mandatory = $false)]
        [switch] $Base64Url,
        # Output raw byte array
        [Parameter (Mandatory = $false)]
        [switch] $RawBytes,
        # Encoding to use for text strings
        [Parameter (Mandatory = $false)]
        [ValidateSet('Ascii', 'UTF32', 'UTF7', 'UTF8', 'BigEndianUnicode', 'Unicode')]
        [string] $Encoding = 'Default'
    )

    process {
        foreach ($InputObject in $InputObjects) {
            [string] $strBase64 = $InputObject
            if (!$PSBoundParameters.ContainsValue('Base64Url') -and ($strBase64.Contains('-') -or $strBase64.Contains('_'))) { $Base64Url = $true }
            if ($Base64Url) { $strBase64 = $strBase64.Replace('-', '+').Replace('_', '/').PadRight($strBase64.Length + (4 - $strBase64.Length % 4) % 4, '=') }
            [byte[]] $outBytes = [System.Convert]::FromBase64String($strBase64)
            if ($RawBytes) {
                Write-Output $outBytes -NoEnumerate
            }
            else {
                [string] $outString = ([Text.Encoding]::$Encoding.GetString($outBytes))
                Write-Output $outString
            }
        }
    }
}

#endregion

#region ConvertFrom-HexString.ps1

<#
.SYNOPSIS
   Convert from Hex String
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertFrom-HexString "57 68 61 74 20 69 73 20 61 20 68 65 78 20 73 74 72 69 6E 67 3F"
    Convert hex byte string seperated by spaces to string.
.EXAMPLE
    PS C:\>"415343494920737472696E6720746F2068657820737472696E67" | ConvertFrom-HexString -Delimiter "" -Encoding Ascii
    Convert hex byte string with no seperation to ASCII string.
.INPUTS
    System.String
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertFrom-HexString {
    [CmdletBinding()]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $InputObject,
        # Delimiter between Hex pairs
        [Parameter (Mandatory = $false)]
        [string] $Delimiter = ' ',
        # Output raw byte array
        [Parameter (Mandatory = $false)]
        [switch] $RawBytes,
        # Encoding to use for text strings
        [Parameter (Mandatory = $false)]
        [ValidateSet('Ascii', 'UTF32', 'UTF7', 'UTF8', 'BigEndianUnicode', 'Unicode')]
        [string] $Encoding = 'Default'
    )

    process {
        $listBytes = New-Object object[] $InputObject.Count
        for ($iString = 0; $iString -lt $InputObject.Count; $iString++) {
            [string] $strHex = $InputObject[$iString]
            if ($strHex.Substring(2, 1) -eq $Delimiter) {
                [string[]] $listHex = $strHex -split $Delimiter
            }
            else {
                [string[]] $listHex = New-Object string[] ($strHex.Length / 2)
                for ($iByte = 0; $iByte -lt $strHex.Length; $iByte += 2) {
                    $listHex[[System.Math]::Truncate($iByte / 2)] = $strHex.Substring($iByte, 2)
                }
            }

            [byte[]] $outBytes = New-Object byte[] $listHex.Count
            for ($iByte = 0; $iByte -lt $listHex.Count; $iByte++) {
                $outBytes[$iByte] = [byte]::Parse($listHex[$iByte], [System.Globalization.NumberStyles]::HexNumber)
            }

            if ($RawBytes) { $listBytes[$iString] = $outBytes }
            else {
                $outString = ([Text.Encoding]::$Encoding.GetString($outBytes))
                Write-Output $outString
            }
        }
        if ($RawBytes) {
            return $listBytes
        }
    }
}

#endregion

#region ConvertFrom-JsonWebSignature.ps1

<#
.SYNOPSIS
   Convert Json Web Signature (JWS) structure to PowerShell object.
.EXAMPLE
    PS C:\>$MsalToken.IdToken | ConvertFrom-JsonWebSignature
    Convert OAuth IdToken JWS to PowerShell object.
.INPUTS
    System.String
#>

function ConvertFrom-JsonWebSignature {
    [CmdletBinding()]
    [Alias('ConvertFrom-Jws')]
    [Alias('ConvertFrom-JsonWebToken')]
    [Alias('ConvertFrom-Jwt')]
    [OutputType([PSCustomObject])]
    param (
        # JSON Web Signature (JWS)
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $InputObjects,
        # Content Type of the Payload
        [Parameter(Mandatory = $false)]
        [ValidateSet('text/plain', 'application/json', 'application/octet-stream')]
        [string] $ContentType = 'application/json'
    )

    process {
        foreach ($InputObject in $InputObjects) {
            [string[]] $JwsComponents = $InputObject.Split('.')
            switch ($ContentType) {
                'application/octet-stream' { [byte[]] $JwsPayload = $JwsComponents[1] | ConvertFrom-Base64String -Base64Url -RawBytes }
                'text/plain' { [string] $JwsPayload = $JwsComponents[1] | ConvertFrom-Base64String -Base64Url }
                'application/json' { [PSCustomObject] $JwsPayload = $JwsComponents[1] | ConvertFrom-Base64String -Base64Url | ConvertFrom-Json }
                Default { [string] $JwsPayload = $JwsComponents[1] | ConvertFrom-Base64String -Base64Url }
            }
            [PSCustomObject] $JwsDecoded = New-Object PSCustomObject -Property @{
                Header    = $JwsComponents[0] | ConvertFrom-Base64String -Base64Url | ConvertFrom-Json
                Payload   = $JwsPayload
                Signature = $JwsComponents[2] | ConvertFrom-Base64String -Base64Url -RawBytes
            }
            Write-Output ($JwsDecoded | Select-Object -Property Header, Payload, Signature)
        }
    }
}

#endregion

#region ConvertFrom-QueryString.ps1

<#
.SYNOPSIS
    Convert Query String to object.
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertFrom-QueryString '?name=path/file.json&index=10'
    Convert query string to object.
.EXAMPLE
    PS C:\>'name=path/file.json&index=10' | ConvertFrom-QueryString -AsHashtable
    Convert query string to hashtable.
.INPUTS
    System.String
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertFrom-QueryString {
    [CmdletBinding()]
    [OutputType([psobject])]
    [OutputType([hashtable])]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [AllowEmptyString()]
        [string[]] $InputStrings,
        # URL decode parameter names
        [Parameter(Mandatory = $false)]
        [switch] $DecodeParameterNames,
        # Converts to hash table object
        [Parameter(Mandatory = $false)]
        [switch] $AsHashtable
    )

    process {
        foreach ($InputString in $InputStrings) {
            if ($AsHashtable) { [hashtable] $OutputObject = @{ } }
            else { [psobject] $OutputObject = New-Object psobject }

            if ($InputString) {
                if ($InputString[0] -eq '?') { $InputString = $InputString.Substring(1) }
                [string[]] $QueryParameters = $InputString.Split('&')
                foreach ($QueryParameter in $QueryParameters) {
                    [string[]] $QueryParameterPair = $QueryParameter.Split('=')
                    if ($DecodeParameterNames) { $QueryParameterPair[0] = [System.Net.WebUtility]::UrlDecode($QueryParameterPair[0]) }
                    if ($OutputObject -is [hashtable]) {
                        $OutputObject.Add($QueryParameterPair[0], [System.Net.WebUtility]::UrlDecode($QueryParameterPair[1]))
                    }
                    else {
                        $OutputObject | Add-Member $QueryParameterPair[0] -MemberType NoteProperty -Value ([System.Net.WebUtility]::UrlDecode($QueryParameterPair[1]))
                    }
                }
            }
            Write-Output $OutputObject
        }
    }

}

#endregion

#region ConvertFrom-SamlMessage.ps1

<#
.SYNOPSIS
   Convert Saml Message to XML object.
.EXAMPLE
    PS C:\>ConvertFrom-SamlMessage 'Base64String'
    Convert Saml Message to XML object.
.INPUTS
    System.String
.OUTPUTS
    SamlMessage : System.Xml.XmlDocument
#>

function ConvertFrom-SamlMessage {
    [CmdletBinding()]
    [Alias('ConvertFrom-SamlRequest')]
    [Alias('ConvertFrom-SamlResponse')]
    #[OutputType([xml])]
    param (
        # SAML Message
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $InputObject
    )

    process {
        foreach ($_InputObject in $InputObject) {
            [byte[]] $bytesInput = $null
            $xmlOutput = New-Object SamlMessage
            try {
                $xmlOutput.LoadXml($_InputObject)
            }
            catch {
                try {
                    $bytesInput = [System.Convert]::FromBase64String($_InputObject)
                }
                catch {
                    $bytesInput = [System.Convert]::FromBase64String([System.Net.WebUtility]::UrlDecode($_InputObject))
                }
            }
            if ($bytesInput) {
                try {
                    $streamInput = New-Object System.IO.MemoryStream -ArgumentList @($bytesInput, $false)
                    try {
                        $xmlOutput.Load($streamInput)
                    }
                    catch {
                        $streamInput = New-Object System.IO.MemoryStream -ArgumentList @($bytesInput, $false)
                        try {
                            $streamOutput = New-Object System.IO.MemoryStream
                            try {
                                [System.IO.Compression.DeflateStream] $streamCompression = New-Object System.IO.Compression.DeflateStream -ArgumentList $streamInput, ([System.IO.Compression.CompressionMode]::Decompress), $true
                                $streamCompression.CopyTo($streamOutput)
                            }
                            finally { $streamCompression.Dispose() }
                            $streamOutput.Position = 0
                            $xmlOutput.Load($streamOutput)
                            #[string] $strOutput = ([Text.Encoding]::$Encoding.GetString($streamOutput.ToArray()))
                            #$xmlOutput.LoadXml($strOutput)
                        }
                        finally { $streamOutput.Dispose() }
                    }
                }
                finally { $streamInput.Dispose() }
            }

            Write-Output $xmlOutput
        }
    }
}

#endregion

#region ConvertFrom-SecureStringAsPlainText.ps1

<#
.SYNOPSIS
    Convert/Decrypt SecureString to Plain Text String.
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertFrom-SecureStringAsPlainText (ConvertTo-SecureString 'SuperSecretString' -AsPlainText -Force) -Force
    Convert plain text to SecureString and then convert it back.
.INPUTS
    System.Security.SecureString
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertFrom-SecureStringAsPlainText {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        # Secure String Value
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [securestring] $SecureString,
        # Confirms that you understand the implications of using the AsPlainText parameter and still want to use it.
        [Parameter(Mandatory = $false)]
        [switch] $Force
    )

    begin {
        if ($PSVersionTable.PSVersion -ge [version]'7.0') {
            Write-Warning 'PowerShell 7 introduced an AsPlainText parameter to the ConvertFrom-SecureString cmdlet.'
        }
        if (!${Force}) {
            ## Terminating Error
            $Exception = New-Object ArgumentException -ArgumentList 'The system cannot protect plain text output. To suppress this warning and convert a SecureString to plain text, reissue the command specifying the Force parameter.'
            Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::InvalidArgument) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'ConvertSecureStringFailureForceRequired' -TargetObject ${SecureString} -ErrorAction Stop
        }
    }

    process {
        try {
            [IntPtr] $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($SecureString)
            Write-Output ([System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($BSTR))
        }
        finally {
            [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($BSTR)
        }
    }
}

#endregion

#region ConvertTo-Base64String.ps1

<#
.SYNOPSIS
    Convert Byte Array or Plain Text String to Base64 String.
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertTo-Base64String "A string with base64 encoding"
    Convert String with Default Encoding to Base64 String.
.EXAMPLE
    PS C:\>"ASCII string with base64url encoding" | ConvertTo-Base64String -Base64Url -Encoding Ascii
    Convert String with Ascii Encoding to Base64Url String.
.EXAMPLE
    PS C:\>ConvertTo-Base64String ([guid]::NewGuid())
    Convert GUID to Base64 String.
.INPUTS
    System.Object
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertTo-Base64String {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [object] $InputObjects,
        # Use base64url variant
        [Parameter (Mandatory = $false)]
        [switch] $Base64Url,
        # Output encoding to use for text strings
        [Parameter (Mandatory = $false)]
        [ValidateSet('Ascii', 'UTF32', 'UTF7', 'UTF8', 'BigEndianUnicode', 'Unicode')]
        [string] $Encoding = 'Default'
    )

    begin {
        function Transform ([byte[]]$InputBytes) {
            [string] $outBase64String = [System.Convert]::ToBase64String($InputBytes)
            if ($Base64Url) { $outBase64String = $outBase64String.Replace('+', '-').Replace('/', '_').Replace('=', '') }
            return $outBase64String
        }

        ## Create list to capture byte stream from piped input.
        [System.Collections.Generic.List[byte]] $listBytes = New-Object System.Collections.Generic.List[byte]
    }

    process {
        if ($InputObjects -is [byte[]]) {
            Write-Output (Transform $InputObjects)
        }
        else {
            foreach ($InputObject in $InputObjects) {
                [byte[]] $InputBytes = $null
                if ($InputObject -is [byte]) {
                    ## Populate list with byte stream from piped input.
                    if ($listBytes.Count -eq 0) {
                        Write-Verbose 'Creating byte array from byte stream.'
                        Write-Warning ('For better performance when piping a single byte array, use "Write-Output $byteArray -NoEnumerate | {0}".' -f $MyInvocation.MyCommand)
                    }
                    $listBytes.Add($InputObject)
                }
                elseif ($InputObject -is [byte[]]) {
                    $InputBytes = $InputObject
                }
                elseif ($InputObject -is [string]) {
                    $InputBytes = [Text.Encoding]::$Encoding.GetBytes($InputObject)
                }
                elseif ($InputObject -is [bool] -or $InputObject -is [char] -or $InputObject -is [single] -or $InputObject -is [double] -or $InputObject -is [int16] -or $InputObject -is [int32] -or $InputObject -is [int64] -or $InputObject -is [uint16] -or $InputObject -is [uint32] -or $InputObject -is [uint64]) {
                    $InputBytes = [System.BitConverter]::GetBytes($InputObject)
                }
                elseif ($InputObject -is [guid]) {
                    $InputBytes = $InputObject.ToByteArray()
                }
                elseif ($InputObject -is [System.IO.FileSystemInfo]) {
                    if ($PSVersionTable.PSVersion -ge [version]'6.0') {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -AsByteStream
                    }
                    else {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -Encoding Byte
                    }
                }
                else {
                    ## Non-Terminating Error
                    $Exception = New-Object ArgumentException -ArgumentList ('Cannot convert input of type {0} to Base64 string.' -f $InputObject.GetType())
                    Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ParserError) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'ConvertBase64StringFailureTypeNotSupported' -TargetObject $InputObject
                }

                if ($null -ne $InputBytes -and $InputBytes.Count -gt 0) {
                    Write-Output (Transform $InputBytes)
                }
            }
        }
    }

    end {
        ## Output captured byte stream from piped input.
        if ($listBytes.Count -gt 0) {
            Write-Output (Transform $listBytes.ToArray())
        }
    }
}

#endregion

#region ConvertTo-HexString.ps1

<#
.SYNOPSIS
   Convert to Hex String
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertTo-HexString "What is a hex string?"
    Convert string to hex byte string seperated by spaces.
.EXAMPLE
    PS C:\>"ASCII string to hex string" | ConvertTo-HexString -Delimiter "" -Encoding Ascii
    Convert ASCII string to hex byte string with no seperation.
.INPUTS
    System.Object
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertTo-HexString {
    [CmdletBinding()]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [object] $InputObjects,
        # Delimiter between Hex pairs
        [Parameter (Mandatory = $false)]
        [string] $Delimiter = ' ',
        # Encoding to use for text strings
        [Parameter (Mandatory = $false)]
        [ValidateSet('Ascii', 'UTF32', 'UTF7', 'UTF8', 'BigEndianUnicode', 'Unicode')]
        [string] $Encoding = 'Default'
    )

    begin {
        function Transform ([byte[]]$InputBytes) {
            [string[]] $outHexString = New-Object string[] $InputBytes.Count
            for ($iByte = 0; $iByte -lt $InputBytes.Count; $iByte++) {
                $outHexString[$iByte] = $InputBytes[$iByte].ToString('X2')
            }
            return $outHexString -join $Delimiter
        }

        ## Create list to capture byte stream from piped input.
        [System.Collections.Generic.List[byte]] $listBytes = New-Object System.Collections.Generic.List[byte]
    }

    process {
        if ($InputObjects -is [byte[]]) {
            Write-Output (Transform $InputObjects)
        }
        else {
            foreach ($InputObject in $InputObjects) {
                [byte[]] $InputBytes = $null
                if ($InputObject -is [byte]) {
                    ## Populate list with byte stream from piped input.
                    if ($listBytes.Count -eq 0) {
                        Write-Verbose 'Creating byte array from byte stream.'
                        Write-Warning ('For better performance when piping a single byte array, use "Write-Output $byteArray -NoEnumerate | {0}".' -f $MyInvocation.MyCommand)
                    }
                    $listBytes.Add($InputObject)
                }
                elseif ($InputObject -is [byte[]]) {
                    $InputBytes = $InputObject
                }
                elseif ($InputObject -is [string]) {
                    $InputBytes = [Text.Encoding]::$Encoding.GetBytes($InputObject)
                }
                elseif ($InputObject -is [bool] -or $InputObject -is [char] -or $InputObject -is [single] -or $InputObject -is [double] -or $InputObject -is [int16] -or $InputObject -is [int32] -or $InputObject -is [int64] -or $InputObject -is [uint16] -or $InputObject -is [uint32] -or $InputObject -is [uint64]) {
                    $InputBytes = [System.BitConverter]::GetBytes($InputObject)
                }
                elseif ($InputObject -is [guid]) {
                    $InputBytes = $InputObject.ToByteArray()
                }
                elseif ($InputObject -is [System.IO.FileSystemInfo]) {
                    if ($PSVersionTable.PSVersion -ge [version]'6.0') {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -AsByteStream
                    }
                    else {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -Encoding Byte
                    }
                }
                else {
                    ## Non-Terminating Error
                    $Exception = New-Object ArgumentException -ArgumentList ('Cannot convert input of type {0} to Hex string.' -f $InputObject.GetType())
                    Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ParserError) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'ConvertHexFailureTypeNotSupported' -TargetObject $InputObject
                }

                if ($null -ne $InputBytes -and $InputBytes.Count -gt 0) {
                    Write-Output (Transform $InputBytes)
                }
            }
        }
    }

    end {
        ## Output captured byte stream from piped input.
        if ($listBytes.Count -gt 0) {
            Write-Output (Transform $listBytes.ToArray())
        }
    }
}

#endregion

#region ConvertTo-PsParameterString.ps1

<#
.SYNOPSIS
    Convert splatable PowerShell paramters to PowerShell parameter string syntax.
.EXAMPLE
    PS C:\>ConvertTo-PsParameterString @{ key1='value1'; key2='value2' }
    Convert hashtable to PowerShell parameters string.
.INPUTS
    System.String
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertTo-PsParameterString {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        #
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
        [AllowNull()]
        [object] $InputObjects,
        #
        [Parameter(Mandatory = $false)]
        [switch] $Compact,
        #
        [Parameter(Mandatory = $false, Position = 1)]
        [type[]] $RemoveTypes = ([string], [bool], [int], [long]),
        #
        [Parameter(Mandatory = $false)]
        [switch] $NoEnumerate
    )

    begin {
        function GetPsParameterString ($InputObject) {
            $OutputString = New-Object System.Text.StringBuilder

            ## Add Value
            switch ($InputObject.GetType()) {
                { $_.Equals([Hashtable]) -or $_.Equals([System.Collections.Specialized.OrderedDictionary]) -or $_.FullName.StartsWith('System.Collections.Generic.Dictionary') -or ($_.BaseType -and $_.BaseType.FullName.StartsWith('System.Collections.Generic.Dictionary')) } {
                    foreach ($Parameter in $InputObject.GetEnumerator()) {
                        [string] $ParameterValue = (ConvertTo-PsString $Parameter.Value -Compact:$Compact -NoEnumerate)
                        if ($ParameterValue.StartsWith('[')) { $ParameterValue = '({0})' -f $ParameterValue }
                        [void]$OutputString.AppendFormat(' -{0} {1}', $Parameter.Key, $ParameterValue)
                    }
                    break
                }
                { $_.BaseType.Equals([Array]) -or $_.Equals([System.Collections.ArrayList]) -or $_.FullName.StartsWith('System.Collections.Generic.List') } {
                    foreach ($Parameter in $InputObject) {
                        [string] $ParameterValue = (ConvertTo-PsString $Parameter -Compact:$Compact -NoEnumerate)
                        if ($ParameterValue.StartsWith('[')) { $ParameterValue = '({0})' -f $ParameterValue }
                        [void]$OutputString.AppendFormat(' {0}', $ParameterValue)
                    }
                    break
                }
                Default {
                    $Exception = New-Object ArgumentException -ArgumentList ('Cannot convert input of type {0} to PowerShell parameter string. Use -NoEnumerate if providing a single splatable array.' -f $InputObject.GetType())
                    Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ParserError) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'ConvertPowerShellParameterStringFailureTypeNotSupported' -TargetObject $InputObject -ErrorAction Stop
                }
            }

            if ($NoEnumerate) {
                $listOutputString.Add($OutputString.ToString())
            }
            else {
                Write-Output $OutputString.ToString()
            }
        }

        if ($NoEnumerate) {
            $listOutputString = New-Object System.Collections.Generic.List[string]
        }
    }

    process {
        if ($PSCmdlet.MyInvocation.ExpectingInput -or $NoEnumerate) {
            GetPsParameterString $InputObjects
        }
        else {
            foreach ($InputObject in $InputObjects) {
                GetPsParameterString $InputObject
            }
        }
    }

    end {
        if ($NoEnumerate) {
            $OutputArray = New-Object System.Text.StringBuilder
            if ($PSVersionTable.PSVersion -ge [version]'6.0') {
                [void]$OutputArray.AppendJoin('', $listOutputString)
            }
            else {
                [void]$OutputArray.Append(($listOutputString -join ''))
            }
            Write-Output $OutputArray.ToString()
        }
    }
}

#endregion

#region ConvertTo-PsString.ps1

<#
.SYNOPSIS
    Convert PowerShell data types to PowerShell string syntax.
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertTo-PsString @{ key1='value1'; key2='value2' }
    Convert hashtable to PowerShell string.
.INPUTS
    System.String
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertTo-PsString {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        #
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
        [AllowNull()]
        [object] $InputObjects,
        #
        [Parameter(Mandatory = $false)]
        [switch] $Compact,
        #
        [Parameter(Mandatory = $false, Position = 1)]
        [type[]] $RemoveTypes = ([string], [bool], [int], [long]),
        #
        [Parameter(Mandatory = $false)]
        [switch] $NoEnumerate
    )

    begin {
        if ($Compact) {
            [System.Collections.Generic.Dictionary[string, type]] $TypeAccelerators = [psobject].Assembly.GetType('System.Management.Automation.TypeAccelerators')::get
            [System.Collections.Generic.Dictionary[type, string]] $TypeAcceleratorsLookup = New-Object 'System.Collections.Generic.Dictionary[type,string]'
            foreach ($TypeAcceleratorKey in $TypeAccelerators.Keys) {
                if (!$TypeAcceleratorsLookup.ContainsKey($TypeAccelerators[$TypeAcceleratorKey])) {
                    $TypeAcceleratorsLookup.Add($TypeAccelerators[$TypeAcceleratorKey], $TypeAcceleratorKey)
                }
            }
        }

        function Resolve-Type {
            param (
                #
                [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
                [type] $ObjectType,
                #
                [Parameter(Mandatory = $false, Position = 1)]
                [switch] $Compact,
                #
                [Parameter(Mandatory = $false, Position = 1)]
                [type[]] $RemoveTypes
            )

            [string] $OutputString = ''
            if ($ObjectType.IsGenericType -or ($ObjectType.BaseType -and $ObjectType.BaseType.IsGenericType)) {
                if (!$ObjectType.IsGenericType) { $ObjectType = $ObjectType.BaseType }
                if ($ObjectType.FullName.StartsWith('System.Collections.Generic.Dictionary')) {
                    #$OutputString += '[hashtable]'
                    if ($Compact) {
                        $OutputString += '(Invoke-Command { $D = New-Object ''Collections.Generic.Dictionary['
                    }
                    else {
                        $OutputString += '(Invoke-Command { $D = New-Object ''System.Collections.Generic.Dictionary['
                    }
                    $iInput = 0
                    foreach ($GenericTypeArgument in $ObjectType.GenericTypeArguments) {
                        if ($iInput -gt 0) { $OutputString += ',' }
                        $OutputString += Resolve-Type $GenericTypeArgument -Compact:$Compact -RemoveTypes @()
                        $iInput++
                    }
                    $OutputString += ']'''
                }
                elseif ($InputObject.GetType().FullName -match '^(System.(Collections.Generic.[a-zA-Z]+))`[0-9]\[(?:\[(.+?), .+?, Version=.+?, Culture=.+?, PublicKeyToken=.+?\],?)+?\]$') {
                    if ($Compact) {
                        $OutputString += '[{0}[' -f $Matches[2]
                    }
                    else {
                        $OutputString += '[{0}[' -f $Matches[1]
                    }
                    $iInput = 0
                    foreach ($GenericTypeArgument in $ObjectType.GenericTypeArguments) {
                        if ($iInput -gt 0) { $OutputString += ',' }
                        $OutputString += Resolve-Type $GenericTypeArgument -Compact:$Compact -RemoveTypes @()
                        $iInput++
                    }
                    $OutputString += ']]'
                }
            }
            elseif ($ObjectType -eq [System.Collections.Specialized.OrderedDictionary]) {
                $OutputString += '[ordered]'  # Explicit cast does not work with full name. Only [ordered] works.
            }
            elseif ($Compact) {
                if ($ObjectType -notin $RemoveTypes) {
                    if ($TypeAcceleratorsLookup.ContainsKey($ObjectType)) {
                        $OutputString += '[{0}]' -f $TypeAcceleratorsLookup[$ObjectType]
                    }
                    elseif ($ObjectType.FullName.StartsWith('System.')) {
                        $OutputString += '[{0}]' -f $ObjectType.FullName.Substring(7)
                    }
                    else {
                        $OutputString += '[{0}]' -f $ObjectType.FullName
                    }
                }
            }
            else {
                $OutputString += '[{0}]' -f $ObjectType.FullName
            }
            return $OutputString
        }

        function GetPSString ($InputObject) {
            $OutputString = New-Object System.Text.StringBuilder

            if ($null -eq $InputObject) { [void]$OutputString.Append('$null') }
            else {
                ## Add Casting
                [void]$OutputString.Append((Resolve-Type $InputObject.GetType() -Compact:$Compact -RemoveTypes $RemoveTypes))

                ## Add Value
                switch ($InputObject.GetType()) {
                    { $_.Equals([String]) } {
                        [void]$OutputString.AppendFormat("'{0}'", $InputObject.Replace("'", "''")) #.Replace('"','`"')
                        break
                    }
                    { $_.Equals([Char]) } {
                        [void]$OutputString.AppendFormat("'{0}'", ([string]$InputObject).Replace("'", "''"))
                        break
                    }
                    { $_.Equals([Boolean]) -or $_.Equals([switch]) } {
                        [void]$OutputString.AppendFormat('${0}', $InputObject)
                        break
                    }
                    { $_.Equals([DateTime]) } {
                        [void]$OutputString.AppendFormat("'{0}'", $InputObject.ToString('O'))
                        break
                    }
                    { $_.Equals([guid]) } {
                        [void]$OutputString.AppendFormat("'{0}'", $InputObject)
                        break
                    }
                    { $_.BaseType -and $_.BaseType.Equals([Enum]) } {
                        [void]$OutputString.AppendFormat('::{0}', $InputObject)
                        break
                    }
                    { $_.BaseType -and $_.BaseType.Equals([ValueType]) } {
                        [void]$OutputString.AppendFormat('{0}', $InputObject)
                        break
                    }
                    { $_.BaseType.Equals([System.IO.FileSystemInfo]) -or $_.Equals([System.Uri]) } {
                        [void]$OutputString.AppendFormat("'{0}'", $InputObject.ToString().Replace("'", "''")) #.Replace('"','`"')
                        break
                    }
                    { $_.Equals([System.Xml.XmlDocument]) } {
                        [void]$OutputString.AppendFormat("'{0}'", $InputObject.OuterXml.Replace("'", "''")) #.Replace('"','""')
                        break
                    }
                    { $_.Equals([Hashtable]) -or $_.Equals([System.Collections.Specialized.OrderedDictionary]) } {
                        [void]$OutputString.Append('@{')
                        $iInput = 0
                        foreach ($enumHashtable in $InputObject.GetEnumerator()) {
                            if ($iInput -gt 0) { [void]$OutputString.Append(';') }
                            [void]$OutputString.AppendFormat('{0}={1}', (ConvertTo-PsString $enumHashtable.Key -Compact:$Compact -NoEnumerate), (ConvertTo-PsString $enumHashtable.Value -Compact:$Compact -NoEnumerate))
                            $iInput++
                        }
                        [void]$OutputString.Append('}')
                        break
                    }
                    { $_.FullName.StartsWith('System.Collections.Generic.Dictionary') -or ($_.BaseType -and $_.BaseType.FullName.StartsWith('System.Collections.Generic.Dictionary')) } {
                        $iInput = 0
                        foreach ($enumHashtable in $InputObject.GetEnumerator()) {
                            [void]$OutputString.AppendFormat('; $D.Add({0},{1})', (ConvertTo-PsString $enumHashtable.Key -Compact:$Compact -NoEnumerate), (ConvertTo-PsString $enumHashtable.Value -Compact:$Compact -NoEnumerate))
                            $iInput++
                        }
                        [void]$OutputString.Append('; $D })')
                        break
                    }
                    { $_.BaseType -and $_.BaseType.Equals([Array]) } {
                        [void]$OutputString.Append('(Write-Output @(')
                        $iInput = 0
                        for ($iInput = 0; $iInput -lt $InputObject.Count; $iInput++) {
                            if ($iInput -gt 0) { [void]$OutputString.Append(',') }
                            [void]$OutputString.Append((ConvertTo-PsString $InputObject[$iInput] -Compact:$Compact -RemoveTypes $InputObject.GetType().DeclaredMembers.Where( { $_.Name -eq 'Set' })[0].GetParameters()[1].ParameterType -NoEnumerate))
                        }
                        [void]$OutputString.Append(') -NoEnumerate)')
                        break
                    }
                    { $_.Equals([System.Collections.ArrayList]) } {
                        [void]$OutputString.Append('@(')
                        $iInput = 0
                        for ($iInput = 0; $iInput -lt $InputObject.Count; $iInput++) {
                            if ($iInput -gt 0) { [void]$OutputString.Append(',') }
                            [void]$OutputString.Append((ConvertTo-PsString $InputObject[$iInput] -Compact:$Compact -NoEnumerate))
                        }
                        [void]$OutputString.Append(')')
                        break
                    }
                    { $_.FullName.StartsWith('System.Collections.Generic.List') } {
                        [void]$OutputString.Append('@(')
                        $iInput = 0
                        for ($iInput = 0; $iInput -lt $InputObject.Count; $iInput++) {
                            if ($iInput -gt 0) { [void]$OutputString.Append(',') }
                            [void]$OutputString.Append((ConvertTo-PsString $InputObject[$iInput] -Compact:$Compact -RemoveTypes $_.GenericTypeArguments -NoEnumerate))
                        }
                        [void]$OutputString.Append(')')
                        break
                    }
                    ## Convert objects with object initializers
                    { $_ -is [object] -and ($_.GetConstructors() | ForEach-Object { if ($_.IsPublic -and !$_.GetParameters()) { $true } }) } {
                        [void]$OutputString.Append('@{')
                        $iInput = 0
                        foreach ($Item in ($InputObject | Get-Member -MemberType Property, NoteProperty)) {
                            if ($iInput -gt 0) { [void]$OutputString.Append(';') }
                            $PropertyName = $Item.Name
                            [void]$OutputString.AppendFormat('{0}={1}', (ConvertTo-PsString $PropertyName -Compact:$Compact -NoEnumerate), (ConvertTo-PsString $InputObject.$PropertyName -Compact:$Compact -NoEnumerate))
                            $iInput++
                        }
                        [void]$OutputString.Append('}')
                        break
                    }
                    Default {
                        $Exception = New-Object ArgumentException -ArgumentList ('Cannot convert input of type {0} to PowerShell string.' -f $InputObject.GetType())
                        Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ParserError) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'ConvertPowerShellStringFailureTypeNotSupported' -TargetObject $InputObject
                    }
                }
            }

            if ($NoEnumerate) {
                $listOutputString.Add($OutputString.ToString())
            }
            else {
                Write-Output $OutputString.ToString()
            }
        }

        if ($NoEnumerate) {
            $listOutputString = New-Object System.Collections.Generic.List[string]
        }
    }

    process {
        if ($PSCmdlet.MyInvocation.ExpectingInput -or $NoEnumerate -or $null -eq $InputObjects) {
            GetPSString $InputObjects
        }
        else {
            foreach ($InputObject in $InputObjects) {
                GetPSString $InputObject
            }
        }
    }

    end {
        if ($NoEnumerate) {
            if (($null -eq $InputObjects -and $listOutputString.Count -eq 0) -or $listOutputString.Count -gt 1) {
                Write-Warning ('To avoid losing strong type on outermost enumerable type when piping, use "Write-Output $Array -NoEnumerate | {0}".' -f $MyInvocation.MyCommand)
                $OutputArray = New-Object System.Text.StringBuilder
                [void]$OutputArray.Append('(Write-Output @(')
                if ($PSVersionTable.PSVersion -ge [version]'6.0') {
                    [void]$OutputArray.AppendJoin(',', $listOutputString)
                }
                else {
                    [void]$OutputArray.Append(($listOutputString -join ','))
                }
                [void]$OutputArray.Append(') -NoEnumerate)')
                Write-Output $OutputArray.ToString()
            }
            else {
                Write-Output $listOutputString[0]
            }

        }
    }
}

#endregion

#region ConvertTo-QueryString.ps1

<#
.SYNOPSIS
    Convert Hashtable to Query String.
.DESCRIPTION

.EXAMPLE
    PS C:\>ConvertTo-QueryString @{ name = 'path/file.json'; index = 10 }
    Convert hashtable to query string.
.EXAMPLE
    PS C:\>[ordered]@{ title = 'convert&prosper'; id = [guid]'352182e6-9ab0-4115-807b-c36c88029fa4' } | ConvertTo-QueryString
    Convert ordered dictionary to query string.
.INPUTS
    System.Collections.Hashtable
.LINK
    https://github.com/jasoth/Utility.PS
#>

function ConvertTo-QueryString {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [object] $InputObjects,
        # URL encode parameter names
        [Parameter(Mandatory = $false)]
        [switch] $EncodeParameterNames
    )

    process {
        foreach ($InputObject in $InputObjects) {
            $QueryString = New-Object System.Text.StringBuilder
            if ($InputObject -is [hashtable] -or $InputObject -is [System.Collections.Specialized.OrderedDictionary] -or $InputObject.GetType().FullName.StartsWith('System.Collections.Generic.Dictionary')) {
                foreach ($Item in $InputObject.GetEnumerator()) {
                    if ($QueryString.Length -gt 0) { [void]$QueryString.Append('&') }
                    [string] $ParameterName = $Item.Key
                    if ($EncodeParameterNames) { $ParameterName = [System.Net.WebUtility]::UrlEncode($ParameterName) }
                    [void]$QueryString.AppendFormat('{0}={1}', $ParameterName, [System.Net.WebUtility]::UrlEncode($Item.Value))
                }
            }
            elseif ($InputObject -is [object] -and $InputObject -isnot [ValueType]) {
                foreach ($Item in ($InputObject | Get-Member -MemberType Property, NoteProperty)) {
                    if ($QueryString.Length -gt 0) { [void]$QueryString.Append('&') }
                    [string] $ParameterName = $Item.Name
                    if ($EncodeParameterNames) { $ParameterName = [System.Net.WebUtility]::UrlEncode($ParameterName) }
                    [void]$QueryString.AppendFormat('{0}={1}', $ParameterName, [System.Net.WebUtility]::UrlEncode($InputObject.($Item.Name)))
                }
            }
            else {
                ## Non-Terminating Error
                $Exception = New-Object ArgumentException -ArgumentList ('Cannot convert input of type {0} to query string.' -f $InputObject.GetType())
                Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ParserError) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'ConvertQueryStringFailureTypeNotSupported' -TargetObject $InputObject
                continue
            }

            Write-Output $QueryString.ToString()
        }
    }
}

#endregion

#region Expand-Data.ps1

<#
.SYNOPSIS
    Decompress data using DEFLATE (RFC 1951) or GZIP file format (RFC 1952).
.DESCRIPTION

.EXAMPLE
    [byte[]] $byteArray = @(115,84,40,46,41,202,204,75,87,72,203,47,82,72,206,207,45,40,74,45,46,206,204,207,3,0)
    PS C:\>Expand-Data $byteArray
    Decompress string using Deflate.
.INPUTS
    System.String
.LINK
    https://github.com/jasoth/Utility.PS
#>

function Expand-Data {
    [CmdletBinding()]
    [Alias('Decompress-Data')]
    [Alias('Inflate-Data')]
    [OutputType([string], [byte[]])]
    param (
        # Value to convert
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [object] $InputObjects,
        # Input is gzip file format
        [Parameter(Mandatory = $false)]
        [switch] $GZip,
        # Output raw byte array
        [Parameter (Mandatory = $false)]
        [switch] $RawBytes,
        # Encoding to use for text strings
        [Parameter (Mandatory = $false)]
        [ValidateSet('Ascii', 'UTF32', 'UTF7', 'UTF8', 'BigEndianUnicode', 'Unicode')]
        [string] $Encoding = 'Default'
    )

    begin {
        function Expand ([byte[]]$InputBytes) {
            try {
                $streamOutput = New-Object System.IO.MemoryStream
                try {
                    $streamInput = New-Object System.IO.MemoryStream -ArgumentList @($InputBytes, $false)
                    try {
                        if ($GZip) {
                            $streamCompression = New-Object System.IO.Compression.GZipStream -ArgumentList $streamInput, ([System.IO.Compression.CompressionMode]::Decompress)
                        }
                        else {
                            $streamCompression = New-Object System.IO.Compression.DeflateStream -ArgumentList $streamInput, ([System.IO.Compression.CompressionMode]::Decompress)
                        }
                        $streamCompression.CopyTo($streamOutput)
                    }
                    catch {
                        Write-Error -Exception $_.Exception.InnerException -Category ([System.Management.Automation.ErrorCategory]::InvalidData) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'ExpandDataFailureInvalidData' -TargetObject $InputBytes -ErrorAction Stop
                    }
                    finally { $streamCompression.Dispose() }
                    [byte[]] $OutputBytes = $streamOutput.ToArray()
                }
                finally { $streamInput.Dispose() }
            }
            finally { $streamOutput.Dispose() }

            Write-Output $OutputBytes
        }

        ## Create list to capture byte stream from piped input.
        [System.Collections.Generic.List[byte]] $listBytes = New-Object System.Collections.Generic.List[byte]
    }

    process {
        if ($InputObjects -is [byte[]]) {
            [byte[]] $outBytes = Expand $InputObjects
            if ($RawBytes) {
                Write-Output $outBytes -NoEnumerate
            }
            else {
                [string] $outString = ([Text.Encoding]::$Encoding.GetString($outBytes))
                Write-Output $outString
            }
        }
        else {
            foreach ($InputObject in $InputObjects) {
                [byte[]] $InputBytes = $null
                if ($InputObject -is [byte]) {
                    ## Populate list with byte stream from piped input.
                    if ($listBytes.Count -eq 0) {
                        Write-Verbose 'Creating byte array from byte stream.'
                        Write-Warning ('For better performance when piping a single byte array, use "Write-Output $byteArray -NoEnumerate | {0}".' -f $MyInvocation.MyCommand)
                    }
                    $listBytes.Add($InputObject)
                }
                elseif ($InputObject -is [byte[]]) {
                    $InputBytes = $InputObject
                }
                elseif ($InputObject -is [bool] -or $InputObject -is [char] -or $InputObject -is [single] -or $InputObject -is [double] -or $InputObject -is [int16] -or $InputObject -is [int32] -or $InputObject -is [int64] -or $InputObject -is [uint16] -or $InputObject -is [uint32] -or $InputObject -is [uint64]) {
                    $InputBytes = [System.BitConverter]::GetBytes($InputObject)
                }
                elseif ($InputObject -is [System.IO.FileSystemInfo]) {
                    if ($PSVersionTable.PSVersion -ge [version]'6.0') {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -AsByteStream
                    }
                    else {
                        $InputBytes = Get-Content $InputObject.FullName -Raw -Encoding Byte
                    }
                }
                else {
                    ## Non-Terminating Error
                    $Exception = New-Object ArgumentException -ArgumentList ('Cannot compress input of type {0}.' -f $InputObject.GetType())
                    Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ParserError) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'CompressDataFailureTypeNotSupported' -TargetObject $InputObject
                }

                if ($null -ne $InputBytes -and $InputBytes.Count -gt 0) {
                    [byte[]] $outBytes = Expand $InputBytes
                    if ($RawBytes) {
                        Write-Output $outBytes -NoEnumerate
                    }
                    else {
                        [string] $outString = ([Text.Encoding]::$Encoding.GetString($outBytes))
                        Write-Output $outString
                    }
                }
            }
        }
    }

    end {
        ## Output captured byte stream from piped input.
        if ($listBytes.Count -gt 0) {
            [byte[]] $outBytes = Expand $listBytes.ToArray()
            if ($RawBytes) {
                Write-Output $outBytes -NoEnumerate
            }
            else {
                [string] $outString = ([Text.Encoding]::$Encoding.GetString($outBytes))
                Write-Output $outString
            }
        }
    }
}

#endregion

#region Get-MsftUserRealm.ps1

<#
.SYNOPSIS
   Get User Realm Information for a Microsoft user account.
.EXAMPLE
   Get-MsftUserRealm user@domain.com
.EXAMPLE
   'user1@domainA.com','user2@domainA.com','user@domainB.com' | Get-MsftUserRealm
#>

function Get-MsftUserRealm {
    [CmdletBinding()]
    [OutputType([PsCustomObject[]])]
    param (
        # User Principal Name
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 1)]
        [string[]] $User,
        # Check For Microsoft Account
        [Parameter(Mandatory = $false)]
        [switch] $CheckForMicrosoftAccount,
        # API Version
        [Parameter(Mandatory = $false)]
        [string] $ApiVersion = '2.1'
    )

    process {
        foreach ($_User in $User) {
            $uriUserRealm = New-Object System.UriBuilder 'https://login.microsoftonline.com/common/userrealm'
            $uriUserRealm.Query = ConvertTo-QueryString @{
                'api-version' = $ApiVersion
                'checkForMicrosoftAccount' = $CheckForMicrosoftAccount
                'user'        = $_User
            }

            $Result = Invoke-RestMethod -UseBasicParsing -Method Get -Uri $uriUserRealm.Uri.AbsoluteUri
            Write-Output $Result
        }
    }
}

#endregion

#region Get-ObjectPropertyValue.ps1

<#
.SYNOPSIS
    Get object property value.
.EXAMPLE
    PS C:\>$object = New-Object psobject -Property @{ title = 'title value' }
    PS C:\>$object | Get-ObjectPropertyValue -Property 'title'
    Get value of object property named title.
.EXAMPLE
    PS C:\>$object = New-Object psobject -Property @{ lvl1 = (New-Object psobject -Property @{ nextLevel = 'lvl2 data' }) }
    PS C:\>Get-ObjectPropertyValue $object -Property 'lvl1', 'nextLevel'
    Get value of nested object property named nextLevel.
.INPUTS
    System.Collections.Hashtable
    System.Management.Automation.PSObject
#>

function Get-ObjectPropertyValue {
    [CmdletBinding()]
    [OutputType([psobject])]
    param (
        # Object containing property values
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [AllowNull()]
        [psobject] $InputObjects,
        # Name of property. Specify an array of property names to tranverse nested objects.
        [Parameter(Mandatory = $true, ValueFromRemainingArguments = $true)]
        [string[]] $Property
    )

    process {
        foreach ($InputObject in $InputObjects) {
            for ($iProperty = 0; $iProperty -lt $Property.Count; $iProperty++) {
                ## Get property value
                if ($InputObject -is [hashtable]) {
                    if ($InputObject.ContainsKey($Property[$iProperty])) {
                        $PropertyValue = $InputObject[$Property[$iProperty]]
                    }
                    else { $PropertyValue = $null }
                }
                else {
                    $PropertyValue = Select-Object -InputObject $InputObject -ExpandProperty $Property[$iProperty] -ErrorAction Ignore
                    if ($null -eq $PropertyValue) { break }
                }
                ## Check for more nested properties
                if ($iProperty -lt $Property.Count - 1) {
                    $InputObject = $PropertyValue
                    if ($null -eq $InputObject) { break }
                }
                else {
                    Write-Output $PropertyValue
                }
            }
        }
    }
}

#endregion

#region Get-OpenIdProviderConfiguration.ps1

<#
.SYNOPSIS
    Parse OpenId Provider Configuration and Keys
.EXAMPLE
    PS C:\>Get-MsIdAuthorityUri -TenantId tenant.onmicrosoft.com | Get-OpenIdProviderConfiguration
    Get OpenId Provider Configuration for a specific Microsoft organizational tenant (Azure AD).
.EXAMPLE
    PS C:\>Get-MsIdAuthorityUri -TenantId tenant.onmicrosoft.com | Get-OpenIdProviderConfiguration -Keys
    Get public keys for OpenId Provider for a specific Microsoft organizational tenant (Azure AD).
.EXAMPLE
    PS C:\>Get-MsIdAuthorityUri -Msa | Get-OpenIdProviderConfiguration
    Get OpenId Provider Configuration for Microsoft consumer accounts (MSA).
.EXAMPLE
    PS C:\>Get-OpenIdProviderConfiguration 'https://accounts.google.com/'
    Get OpenId Provider Configuration for Google Accounts.
.INPUTS
    System.Uri
#>

function Get-OpenIdProviderConfiguration {
    [CmdletBinding()]
    [OutputType([PsCustomObject[]])]
    param (
        # Identity Provider Authority URI
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 1)]
        [uri] $Issuer,
        # Return configuration keys
        [Parameter(Mandatory = $false)]
        [switch] $Keys
    )
    ## Build common OpenId provider configuration URI
    $uriOpenIdProviderConfiguration = New-Object System.UriBuilder $Issuer.AbsoluteUri
    if (!$uriOpenIdProviderConfiguration.Path.EndsWith('/.well-known/openid-configuration')) { $uriOpenIdProviderConfiguration.Path += '/.well-known/openid-configuration' }

    ## Download and parse configuration
    $OpenIdProviderConfiguration = Invoke-RestMethod -UseBasicParsing -Uri $uriOpenIdProviderConfiguration.Uri.AbsoluteUri  # Should return ContentType 'application/json'
    if ($Keys) {
        $OpenIdProviderConfigurationJwks = Invoke-RestMethod -UseBasicParsing -Uri $OpenIdProviderConfiguration.jwks_uri  # Should return ContentType 'application/json'
        return $OpenIdProviderConfigurationJwks.keys
    }
    else {
        return $OpenIdProviderConfiguration
    }
}

#endregion

#region Get-ParsedTokenFromResponse.ps1

<#
.SYNOPSIS
    Parses token from response as plain text string.
.EXAMPLE
    PS C:\>Get-ParsedTokenFromResponse $response
    Parses token from $response as plain text string.
#>

function Get-ParsedTokenFromResponse {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        # HTTP response
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string] $HttpResponse,
        [Parameter(Mandatory=$true, Position = 1)]
        # Protocol SAML or WsFed
        [ValidateSet("SAML", "WsFed")]
        [string]$Protocol
  
    )

    $token = ""

    if ($Protocol -eq "SAML") {
        # <input type="hidden" name="SAMLResponse" value=" ... " />
        if($HttpResponse -match '<input type=\"hidden\" name=\"SAMLResponse\" value=\"(.+)\" \/><noscript>') {
            # $token = $Matches[1] | ConvertFrom-Base64String
            $token = $Matches[1] | ConvertFrom-SamlMessage
        }
    }
    else {
        # <input type="hidden" name="wresult" value=" ... " />
        if($HttpResponse -match '<input type=\"hidden\" name=\"wresult\" value=\"(.+)\" \/><noscript>') {
            $token = [System.Net.WebUtility]::HtmlDecode($Matches[1]) | ConvertFrom-SamlMessage
        }
    }


    return $token
}
#endregion

#region Get-SamlFederationMetadata.ps1

<#
.SYNOPSIS
    Parse Federation Metadata
.EXAMPLE
    PS C:\>Get-MsIdAuthorityUri -TenantId tenant.onmicrosoft.com -AppType 'Saml' | Get-SamlFederationMetadata
    Get SAML or WS-Fed Federation Metadata for a specific Microsoft tenant.
.EXAMPLE
    PS C:\>Get-MsIdAuthorityUri -TenantId tenant.onmicrosoft.com -AppType 'Saml' | Get-SamlFederationMetadata -AppId 00000000-0000-0000-0000-000000000000
    Get SAML or WS-Fed Federation Metadata for a specific application within a specific Microsoft tenant.
.EXAMPLE
    PS C:\>Get-SamlFederationMetadata 'https://adfs.contoso.com'
    Get SAML or WS-Fed Federation Metadata for an ADFS farm.
.INPUTS
    System.Uri
#>

function Get-SamlFederationMetadata {
    [CmdletBinding()]
    [Alias('Get-WsFedFederationMetadata')]
    [OutputType([xml], [System.Xml.XmlElement[]])]
    param (
        # Identity Provider Authority URI
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 1)]
        [uri] $Issuer,
        # Azure AD Application Id
        [Parameter(Mandatory = $false, Position = 2)]
        [guid] $AppId
    )

    ## Remove Microsoft v2.0 endpoint because it is only for OAuth2
    if ($Issuer.Authority -eq 'login.microsoftonline.com') { $Issuer = $Issuer.AbsoluteUri -replace '[/\\]v2.0[/\\]?$', '' }

    ## Build common federation metadata URI
    $uriFederationMetadata = New-Object System.UriBuilder $Issuer.AbsoluteUri
    if (!$uriFederationMetadata.Path.EndsWith('/FederationMetadata/2007-06/FederationMetadata.xml', $true, $null)) { $uriFederationMetadata.Path += '/FederationMetadata/2007-06/FederationMetadata.xml' }
    if ($AppId) {
        $uriFederationMetadata.Query = ConvertTo-QueryString @{
            AppId = $AppId
        }
    }

    ## Download and parse federation metadata
    $FederationMetadata = Invoke-RestMethod -UseBasicParsing -Uri $uriFederationMetadata.Uri.AbsoluteUri -ErrorAction Stop  # Should return ContentType 'application/samlmetadata+xml'
    if ($FederationMetadata -is [string]) {
        try {
            [xml] $xmlFederationMetadata = $FederationMetadata -replace '^[^<]*', ''
        }
        catch { throw }
    }
    else {
        [xml] $xmlFederationMetadata = $FederationMetadata
    }

    return $xmlFederationMetadata.GetElementsByTagName('EntityDescriptor')
}

#endregion

#region Get-X509Certificate.ps1

<#
.SYNOPSIS
    Get certificate object for X509 certificate.
.DESCRIPTION
    Get certificate object for X509 certificate.
.EXAMPLE
    PS C:\>[byte[]] $DERCert = @(48,130,4,18,48,130,2,250,160,3,2,1,2,2,15,0,193,0,139,60,60,136,17,209,62,246,99,236,223,64,48,13,6,9,42,134,72,134,247,13,1,1,4,5,0,48,112,49,43,48,41,6,3,85,4,11,19,34,67,111,112,121,114,105,103,104,116,32,40,99,41,32,49,57,57,55,32,77,105,99,114,111,115,111,102,116,32,67,111,114,112,46,49,30,48,28,6,3,85,4,11,19,21,77,105,99,114,111,115,111,102,116,32,67,111,114,112,111,114,97,116,105,111,110,49,33,48,31,6,3,85,4,3,19,24,77,105,99,114,111,115,111,102,116,32,82,111,111,116,32,65,117,116,104,111,114,105,116,121,48,30,23,13,57,55,48,49,49,48,48,55,48,48,48,48,90,23,13,50,48,49,50,51,49,48,55,48,48,48,48,90,48,112,49,43,48,41,6,3,85,4,11,19,34,67,111,112,121,114,105,103,104,116,32,40,99,41,32,49,57,57,55,32,77,105,99,114,111,115,111,102,116,32,67,111,114,112,46,49,30,48,28,6,3,85,4,11,19,21,77,105,99,114,111,115,111,102,116,32,67,111,114,112,111,114,97,116,105,111,110,49,33,48,31,6,3,85,4,3,19,24,77,105,99,114,111,115,111,102,116,32,82,111,111,116,32,65,117,116,104,111,114,105,116,121,48,130,1,34,48,13,6,9,42,134,72,134,247,13,1,1,1,5,0,3,130,1,15,0,48,130,1,10,2,130,1,1,0,169,2,189,193,112,230,59,242,78,27,40,159,151,120,94,48,234,162,169,141,37,95,248,254,149,76,163,183,254,157,162,32,62,124,81,162,155,162,143,96,50,107,209,66,100,121,238,172,118,201,84,218,242,235,156,134,28,143,159,132,102,179,197,107,122,98,35,214,29,60,222,15,1,146,232,150,196,191,45,102,154,154,104,38,153,208,58,44,191,12,181,88,38,193,70,231,10,62,56,150,44,169,40,57,168,236,73,131,66,227,132,15,187,154,108,85,97,172,130,124,161,96,45,119,76,233,153,180,100,59,154,80,28,49,8,36,20,159,169,231,145,43,24,230,61,152,99,20,96,88,5,101,159,29,55,82,135,247,167,239,148,2,198,27,211,191,85,69,179,137,128,191,58,236,84,148,78,174,253,167,122,109,116,78,175,24,204,150,9,40,33,0,87,144,96,105,55,187,75,18,7,60,86,255,91,251,164,102,10,8,166,210,129,86,87,239,182,59,94,22,129,119,4,218,246,190,174,128,149,254,176,205,127,214,167,26,114,92,60,202,188,240,8,163,34,48,179,6,133,201,179,32,119,19,133,223,2,3,1,0,1,163,129,168,48,129,165,48,129,162,6,3,85,29,1,4,129,154,48,129,151,128,16,91,208,112,239,105,114,158,35,81,126,20,178,77,142,255,203,161,114,48,112,49,43,48,41,6,3,85,4,11,19,34,67,111,112,121,114,105,103,104,116,32,40,99,41,32,49,57,57,55,32,77,105,99,114,111,115,111,102,116,32,67,111,114,112,46,49,30,48,28,6,3,85,4,11,19,21,77,105,99,114,111,115,111,102,116,32,67,111,114,112,111,114,97,116,105,111,110,49,33,48,31,6,3,85,4,3,19,24,77,105,99,114,111,115,111,102,116,32,82,111,111,116,32,65,117,116,104,111,114,105,116,121,130,15,0,193,0,139,60,60,136,17,209,62,246,99,236,223,64,48,13,6,9,42,134,72,134,247,13,1,1,4,5,0,3,130,1,1,0,149,232,11,192,141,243,151,24,53,237,184,1,36,216,119,17,243,92,96,50,159,158,11,203,62,5,145,136,143,201,58,230,33,242,240,87,147,44,181,160,71,200,98,239,252,215,204,59,59,90,169,54,84,105,254,36,109,63,201,204,170,222,5,124,221,49,141,61,159,16,112,106,187,254,18,79,24,105,192,252,208,67,227,17,90,32,79,234,98,123,175,170,25,200,43,55,37,45,190,101,161,18,138,37,15,99,163,247,84,28,249,33,201,214,21,243,82,172,110,67,50,7,253,130,23,248,229,103,108,13,81,246,189,241,82,199,189,231,196,48,252,32,49,9,136,29,149,41,26,77,213,29,2,165,241,128,224,3,180,91,244,177,221,200,87,238,101,73,199,82,84,182,180,3,40,18,255,144,214,240,8,143,126,184,151,197,171,55,44,228,122,228,168,119,227,118,160,0,208,106,63,193,210,54,138,224,65,18,168,53,106,27,106,219,53,225,212,28,4,228,168,69,4,200,90,51,56,110,77,28,13,98,183,10,162,140,211,213,84,63,70,205,28,85,166,112,219,18,58,135,147,117,159,167,210,160)
    PS C:\>Get-X509Certificate $DERCert -Verbose
    Get certificate details from binary (DER) encoded X509 certificate.
.EXAMPLE
    PS C:\>[string] $Base64Cert = 'MIIEEjCCAvqgAwIBAgIPAMEAizw8iBHRPvZj7N9AMA0GCSqGSIb3DQEBBAUAMHAxKzApBgNVBAsTIkNvcHlyaWdodCAoYykgMTk5NyBNaWNyb3NvZnQgQ29ycC4xHjAcBgNVBAsTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEhMB8GA1UEAxMYTWljcm9zb2Z0IFJvb3QgQXV0aG9yaXR5MB4XDTk3MDExMDA3MDAwMFoXDTIwMTIzMTA3MDAwMFowcDErMCkGA1UECxMiQ29weXJpZ2h0IChjKSAxOTk3IE1pY3Jvc29mdCBDb3JwLjEeMBwGA1UECxMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMSEwHwYDVQQDExhNaWNyb3NvZnQgUm9vdCBBdXRob3JpdHkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCpAr3BcOY78k4bKJ+XeF4w6qKpjSVf+P6VTKO3/p2iID58UaKboo9gMmvRQmR57qx2yVTa8uuchhyPn4Rms8VremIj1h083g8BkuiWxL8tZpqaaCaZ0Dosvwy1WCbBRucKPjiWLKkoOajsSYNC44QPu5psVWGsgnyhYC13TOmZtGQ7mlAcMQgkFJ+p55ErGOY9mGMUYFgFZZ8dN1KH96fvlALGG9O/VUWziYC/OuxUlE6u/ad6bXROrxjMlgkoIQBXkGBpN7tLEgc8Vv9b+6RmCgim0oFWV++2O14WgXcE2va+roCV/rDNf9anGnJcPMq88AijIjCzBoXJsyB3E4XfAgMBAAGjgagwgaUwgaIGA1UdAQSBmjCBl4AQW9Bw72lyniNRfhSyTY7/y6FyMHAxKzApBgNVBAsTIkNvcHlyaWdodCAoYykgMTk5NyBNaWNyb3NvZnQgQ29ycC4xHjAcBgNVBAsTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEhMB8GA1UEAxMYTWljcm9zb2Z0IFJvb3QgQXV0aG9yaXR5gg8AwQCLPDyIEdE+9mPs30AwDQYJKoZIhvcNAQEEBQADggEBAJXoC8CN85cYNe24ASTYdxHzXGAyn54Lyz4FkYiPyTrmIfLwV5MstaBHyGLv/NfMOztaqTZUaf4kbT/JzKreBXzdMY09nxBwarv+Ek8YacD80EPjEVogT+pie6+qGcgrNyUtvmWhEoolD2Oj91Qc+SHJ1hXzUqxuQzIH/YIX+OVnbA1R9r3xUse958Qw/CAxCYgdlSkaTdUdAqXxgOADtFv0sd3IV+5lScdSVLa0AygS/5DW8AiPfriXxas3LOR65Kh343agANBqP8HSNorgQRKoNWobats14dQcBOSoRQTIWjM4bk0cDWK3CqKM09VUP0bNHFWmcNsSOoeTdZ+n0qA='
    PS C:\>$Base64Cert | Get-X509Certificate -Verbose
    Get certificate details from Base64 encoded X509 certificate.
.EXAMPLE
    PS C:\>Get-Item "certificateFile.cer" | Get-X509Certificate
    Get certificate details from .cer file.
.INPUTS
    System.Object
.LINK
    https://github.com/jasoth/Utility.PS
#>

function Get-X509Certificate {
    [CmdletBinding()]
    [OutputType([System.Security.Cryptography.X509Certificates.X509Certificate2], [System.Security.Cryptography.X509Certificates.X509Certificate2Collection])]
    param (
        # X.509 certificate that is binary (DER) encoded or Base64-encoded
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
        [object] $InputObjects,
        # Only return the end-entity certificate
        [Parameter(Mandatory = $false)]
        [switch] $EndEntityCertificateOnly
    )

    begin {
        ## Create list to capture byte stream from piped input.
        [System.Collections.Generic.List[byte]] $listBytes = New-Object System.Collections.Generic.List[byte]

        function Transform ([byte[]]$InputBytes) {
            $X509CertificateCollection = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2Collection
            $X509CertificateCollection.Import($InputBytes, $null, [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::EphemeralKeySet)
            Write-Output $X509CertificateCollection -NoEnumerate
        }
    }

    process {
        if ($InputObjects -is [byte[]]) {
            $X509CertificateCollection = Transform $InputObjects
            if ($EndEntityCertificateOnly) { Write-Output $X509CertificateCollection[-1] }
            else { Write-Output $X509CertificateCollection }
        }
        else {
            foreach ($InputObject in $InputObjects) {
                [byte[]] $inputBytes = $null
                if ($InputObject -is [byte]) {
                    ## Populate list with byte stream from piped input.
                    if ($listBytes.Count -eq 0) {
                        Write-Verbose 'Creating byte array from byte stream.'
                        Write-Warning ('For better performance when piping a single byte array, use "Write-Output $byteArray -NoEnumerate | {0}".' -f $MyInvocation.MyCommand)
                    }
                    $listBytes.Add($InputObject)
                }
                elseif ($InputObject -is [byte[]]) {
                    $inputBytes = $InputObject
                }
                elseif ($InputObject -is [SecureString]) {
                    Write-Verbose 'Decrypting SecureString and decoding Base64 string to byte array.'
                    if ($PSVersionTable.PSVersion -ge [version]'7.0') {
                        $inputBytes = [System.Convert]::FromBase64String((ConvertFrom-SecureString $InputObject -AsPlainText))
                    }
                    else {
                        $inputBytes = [System.Convert]::FromBase64String((ConvertFrom-SecureStringAsPlainText $InputObject -Force))
                    }
                }
                elseif ($InputObject -is [string]) {
                    Write-Verbose 'Decoding Base64 string to byte array.'
                    $inputBytes = [System.Convert]::FromBase64String($InputObject)
                }
                elseif ($InputObject -is [System.IO.FileSystemInfo]) {
                    Write-Verbose 'Decoding file content to byte array.'
                    if ($PSVersionTable.PSVersion -ge [version]'6.0') {
                        $inputBytes = Get-Content $InputObject.FullName -Raw -AsByteStream
                    }
                    else {
                        $inputBytes = Get-Content $InputObject.FullName -Raw -Encoding Byte
                    }
                }
                else {
                    # Otherwise, write a terminating error message indicating that input object type is not supported.
                    $errorMessage = 'Cannot convert input of type {0} to X.509 certificate.' -f $InputObject.GetType()
                    Write-Error -Message $errorMessage -Category ([System.Management.Automation.ErrorCategory]::ParserError) -ErrorId 'GetX509CertificateFailureTypeNotSupported' -ErrorAction Stop
                }

                ## Only write output if the input is not a byte stream.
                if ($listBytes.Count -eq 0) {
                    $X509CertificateCollection = Transform $inputBytes
                    if ($EndEntityCertificateOnly) { Write-Output $X509CertificateCollection[-1] }
                    else { Write-Output $X509CertificateCollection }
                }
            }
        }
    }

    end {
        ## Output captured byte stream from piped input.
        if ($listBytes.Count -gt 0) {
            $X509CertificateCollection = Transform $listBytes
            if ($EndEntityCertificateOnly) { Write-Output $X509CertificateCollection[-1] }
            else { Write-Output $X509CertificateCollection }
        }
    }
}

#endregion

#region Import-AdfsModule.ps1

<#
.SYNOPSIS
    Imports the AD FS PowerShell module.
.DESCRIPTION
    Imports the AD FS PowerShell module if not imported and returns $true. Returns $false in case it is not installed.
.EXAMPLE
    PS > if (Import-AdfsModule) { Write-Host 'AD FS PowerShell module is present' }

    Displays a string if the AD FS module was sucessfully imported.
#>

function Import-AdfsModule {
    $module = 'ADFS'
    
    if(-not(Get-Module -Name $module)) {
        if(Get-Module -ListAvailable | Where-Object { $_.name -eq $module }) {
            Import-Module -Name $module
            $true
        }
        else { $false }
    }
    else { $true } #module already loaded
}

#endregion

#region Invoke-CommandAsSystem.ps1

<#
.SYNOPSIS
    Run PowerShell commands under system context.
.EXAMPLE
    PS C:\>Invoke-CommandAsSystem { [System.Security.Principal.WindowsIdentity]::GetCurrent().Name }
    Run the ScriptBlock under the system context.
.INPUTS
    System.Management.Automation.ScriptBlock
.LINK
    https://github.com/jasoth/Utility.PS
#>

function Invoke-CommandAsSystem {
    [CmdletBinding()]
    param (
        #
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 1)]
        [ScriptBlock] $ScriptBlock,
        #
        [Parameter(Mandatory = $false, Position = 2)]
        [string[]] $ArgumentList
    )

    begin {
        ## Initialize Critical Dependencies
        $CriticalError = $null
        try {
            Import-Module PSScheduledJob, ScheduledTasks -ErrorAction Stop
        }
        catch { Write-Error -ErrorRecord $_ -ErrorVariable CriticalError; return }
    }

    process {
        ## Return Immediately On Critical Error
        if ($CriticalError) { return }

        ## Process
        [guid] $GUID = New-Guid

        try {
            ## Register ScheduleJob
            if ($ArgumentList) {
                $ScheduledJob = Register-ScheduledJob -Name $GUID -ScheduledJobOption (New-ScheduledJobOption -RunElevated) -ScriptBlock $ScriptBlock -ArgumentList $ArgumentList -ErrorAction Stop
            }
            else {
                $ScheduledJob = Register-ScheduledJob -Name $GUID -ScheduledJobOption (New-ScheduledJobOption -RunElevated) -ScriptBlock $ScriptBlock -ErrorAction Stop
            }
            try {
                ## Register ScheduledTask for ScheduledJob
                $ScheduledTask = Register-ScheduledTask -TaskName $GUID -Action (New-ScheduledTaskAction -Execute $ScheduledJob.PSExecutionPath -Argument $ScheduledJob.PSExecutionArgs) -Principal (New-ScheduledTaskPrincipal -UserId 'NT AUTHORITY\SYSTEM' -LogonType ServiceAccount -RunLevel Highest) -ErrorAction Stop

                try {
                    ## Execute ScheduledTask Job to Run ScheduledJob Job
                    $ScheduledTask | Start-ScheduledTask -AsJob -ErrorAction Stop | Wait-Job | Remove-Job -Force -Confirm:$False

                    ## Wait for ScheduledTask to finish
                    While (($ScheduledTask | Get-ScheduledTaskInfo).LastTaskResult -eq 267009) { Start-Sleep -Milliseconds 150 }

                    ## Find ScheduledJob and get the result
                    $Job = Get-Job -Name $GUID -ErrorAction SilentlyContinue | Wait-Job
                    $Result = $Job | Receive-Job -Wait -AutoRemoveJob
                }
                finally {
                    ## Unregister ScheduledTask for ScheduledJob
                    $ScheduledTask | Unregister-ScheduledTask -Confirm:$false
                }
            }
            finally {
                ## Unregister ScheduleJob
                $ScheduledJob | Unregister-ScheduledJob -Force -Confirm:$False
            }
        }
        catch { Write-Error -ErrorRecord $_; return }

        return $Result
    }
}

#endregion

#region New-AdfsLoginFormFields.ps1

<#
.SYNOPSIS
    Gets the form fields to login to AD FS server for the login URL and credentials.
.DESCRIPTION
.EXAMPLE
    PS C:\>New-AdfsLoginFormFields -Url $url -Credential $credential
    Gets the form fields for the variables.
#>

function New-AdfsLoginFormFields {
    [CmdletBinding()]
    [OutputType([System.Collections.Generic.Dictionary[string, string]])]
    param (
        # User credential
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [pscredential] $Credential
    )

    $user = $Credential.UserName
    $password = ConvertFrom-SecureStringAsPlainText $Credential.Password -Force

    $fields = New-Object -TypeName "System.Collections.Generic.Dictionary[string,string]"
    $fields.Add("UserName",$user)
    $fields.Add("Password",$password)
    $fields.Add("AuthMethod","FormsAuthentication")

    return $fields
}
#endregion

#region Resolve-XmlAttribute.ps1

function Resolve-XmlAttribute {
    [CmdletBinding(DefaultParameterSetName = "QualifiedName")]
    [OutputType([System.Xml.XmlAttribute])]
    param
    (
        #
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ValueFromPipeline = $true, Position = 1)]
        [System.Xml.XmlElement] $ParentNode,
        #
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "QualifiedName")]
        [string] $QualifiedName,
        #
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "Prefix")]
        [string] $Prefix,
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "Prefix")]
        [string] $LocalName,
        #
        [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = "QualifiedName")]
        [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true, ParameterSetName = "Prefix")]
        [string] $NamespaceURI,
        #
        [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
        [Alias("Create")]
        [switch] $CreateMissing
    )

    process {
        [System.Xml.XmlAttribute] $xmlAttribute = $null
        switch ($PSCmdlet.ParameterSetName) {
            'QualifiedName' {
                $resultSelectXml = Select-Xml -Xml $ParentNode -XPath ('@{0}' -f $QualifiedName)
                if ($resultSelectXml) { $xmlAttribute = $resultSelectXml.Node }
                elseif ($CreateMissing) {
                    if ($NamespaceURI) { $xmlAttribute = $ParentNode.SetAttributeNode($ParentNode.OwnerDocument.CreateAttribute($QualifiedName, $NamespaceURI)) }
                    else { $xmlAttribute = $ParentNode.SetAttributeNode(($ParentNode.OwnerDocument.CreateAttribute($QualifiedName))) }
                }
                break 
            }
            'Prefix' {
                if ($Prefix -eq "xmlns") { $resultSelectXml = Select-Xml -Xml $ParentNode -XPath ('namespace::{0}' -f $LocalName) }
                else { $resultSelectXml = Select-Xml -Xml $ParentNode -XPath ('@{0}:{1}' -f $Prefix, $LocalName) -Namespace @{ $Prefix = $ParentNode.GetNamespaceOfPrefix($Prefix) } }
                if ($resultSelectXml) { $xmlAttribute = $resultSelectXml.Node }
                elseif ($CreateMissing) { $xmlAttribute = $ParentNode.SetAttributeNode($ParentNode.OwnerDocument.CreateAttribute($Prefix, $LocalName, $ParentNode.GetNamespaceOfPrefix($Prefix))) }
                break 
            }
        }
        return $xmlAttribute
    }
}

#endregion

#region Resolve-XmlElement.ps1

function Resolve-XmlElement {
    [CmdletBinding(DefaultParameterSetName = "QualifiedName")]
    [OutputType([System.Xml.XmlElement[]])]
    param
    (
        #
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ValueFromPipeline = $true, Position = 1)]
        [System.Xml.XmlElement] $ParentNode,
        #
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "QualifiedName")]
        [string] $QualifiedName,
        #
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "Prefix")]
        [string] $Prefix,
        #
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "Prefix")]
        [string] $LocalName,
        #
        [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true,  ParameterSetName = "QualifiedName")]
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = "Prefix")]
        [string] $NamespaceURI,
        #
        [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
        [Alias("Clear")]
        [switch] $ClearExisting = $false,
        #
        [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
        [Alias("Create")]
        [switch] $CreateMissing
    )
        
    process {
        [System.Xml.XmlElement[]] $xmlElement = @()
                
        switch ($PSCmdlet.ParameterSetName) {
            'QualifiedName' {
                [Microsoft.PowerShell.Commands.SelectXmlInfo[]] $resultSelectXml = Select-Xml -Xml $ParentNode -XPath ('./p:{0}' -f $QualifiedName) -Namespace @{ 'p' = $ParentNode.NamespaceURI }
                if ($ClearExisting) {
                    foreach ($result in $resultSelectXml) { $ParentNode.RemoveChild($result.Node) | Out-Null }
                    $resultSelectXml = @()
                }
                if ($resultSelectXml) { $xmlElement = $resultSelectXml.Node }
                elseif ($CreateMissing) { $xmlElement = $ParentNode.AppendChild($ParentNode.OwnerDocument.CreateElement($QualifiedName, $ParentNode.NamespaceURI)) }
                break 
            }
            'Prefix' {
                [Microsoft.PowerShell.Commands.SelectXmlInfo[]] $resultSelectXml = Select-Xml -Xml $ParentNode -XPath ('./{0}:{1}' -f $Prefix, $LocalName) -Namespace @{ $Prefix = $ParentNode.GetNamespaceOfPrefix($Prefix) }
                if ($ClearExisting) {
                    foreach ($result in $resultSelectXml) { $ParentNode.RemoveChild($result.Node) | Out-Null }
                    $resultSelectXml = @()
                }
                if ($resultSelectXml) { $xmlElement = $resultSelectXml.Node }
                elseif ($CreateMissing) { $xmlElement = $ParentNode.AppendChild($ParentNode.OwnerDocument.CreateElement($Prefix, $LocalName, $ParentNode.GetNamespaceOfPrefix($Prefix))) }
                break 
            }
        }
        return $xmlElement
    }
}
#endregion

#region Test-IpAddressInSubnet.ps1

<#
.SYNOPSIS
    Determine if an IP address exists in the specified subnet.
.EXAMPLE
    PS C:\>Test-IpAddressInSubnet 192.168.1.10 -Subnet '192.168.1.1/32','192.168.1.0/24'
    Determine if the IPv4 address exists in the specified subnet.
.EXAMPLE
    PS C:\>Test-IpAddressInSubnet 2001:db8:1234::1 -Subnet '2001:db8:a::123/64','2001:db8:1234::/48'
    Determine if the IPv6 address exists in the specified subnet.
.INPUTS
    System.Net.IPAddress
.LINK
    https://github.com/jasoth/Utility.PS
#>

function Test-IpAddressInSubnet {
    [CmdletBinding()]
    [OutputType([bool], [string[]])]
    param (
        # IP Address to test against provided subnets.
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 1)]
        [ipaddress[]] $IpAddresses,
        # List of subnets in CIDR notation. For example, "192.168.1.0/24" or "2001:db8:1234::/48".
        [Parameter(Mandatory = $true)]
        [string[]] $Subnets,
        # Return list of matching subnets rather than a boolean result.
        [Parameter(Mandatory = $false)]
        [switch] $ReturnMatchingSubnets
    )

    begin {
        function ConvertBitArrayToByteArray([System.Collections.BitArray] $BitArray) {
            [byte[]] $ByteArray = New-Object byte[] ([System.Math]::Ceiling($BitArray.Length / 8))
            $BitArray.CopyTo($ByteArray, 0)
            return $ByteArray
        }

        function ConvertBitArrayToBigInt([System.Collections.BitArray] $BitArray) {
            return [bigint][byte[]](ConvertBitArrayToByteArray $BitArray)
        }
    }

    process {
        foreach ($IpAddress in $IpAddresses) {
            if ($IpAddress.AddressFamily -eq [System.Net.Sockets.AddressFamily]::InterNetwork) {
                [int32] $bitIpAddress = [BitConverter]::ToInt32($IpAddress.GetAddressBytes(), 0)
            }
            else {
                [System.Collections.BitArray] $bitIpAddress = $IpAddress.GetAddressBytes()
            }

            [System.Collections.Generic.List[string]] $listSubnets = New-Object System.Collections.Generic.List[string]
            [bool] $Result = $false
            foreach ($Subnet in $Subnets) {
                [string[]] $SubnetComponents = $Subnet.Split('/')
                [ipaddress] $SubnetAddress = $SubnetComponents[0]
                [int] $SubnetMaskLength = $SubnetComponents[1]

                if ($IpAddress.AddressFamily -eq $SubnetAddress.AddressFamily) {
                    if ($IpAddress.AddressFamily -eq [System.Net.Sockets.AddressFamily]::InterNetwork) {
                        ## Supports IPv4 (32 bit) only but more performant than BitArray?
                        #[int32] $bitIpAddress = [BitConverter]::ToInt32($IpAddress.GetAddressBytes(), 0)
                        [int32] $bitSubnetAddress = [BitConverter]::ToInt32($SubnetAddress.GetAddressBytes(), 0)
                        [int32] $bitSubnetMaskHostOrder = 0
                        if ($SubnetMaskLength -gt 0) {
                            $bitSubnetMaskHostOrder = -1 -shl (32 - $SubnetMaskLength)
                        }
                        [int32] $bitSubnetMask = [ipaddress]::HostToNetworkOrder($bitSubnetMaskHostOrder)

                        ## Check IP
                        if (($bitIpAddress -band $bitSubnetMask) -eq ($bitSubnetAddress -band $bitSubnetMask)) {
                            if ($ReturnMatchingSubnets) {
                                $listSubnets.Add($Subnet)
                            }
                            else {
                                $Result = $true
                                continue
                            }
                        }
                    }
                    else {
                        ## BitArray supports IPv4 (32 bits) and IPv6 (128 bits). Would Int128 type in .NET 7 improve performance?
                        #[System.Collections.BitArray] $bitIpAddress = $IpAddress.GetAddressBytes()
                        [System.Collections.BitArray] $bitSubnetAddress = $SubnetAddress.GetAddressBytes()
                        [System.Collections.BitArray] $bitSubnetMask = New-Object System.Collections.BitArray -ArgumentList ($bitSubnetAddress.Length - $SubnetMaskLength), $true
                        $bitSubnetMask.Length = $bitSubnetAddress.Length
                        [void]$bitSubnetMask.Not()
                        [byte[]] $ByteArray = ConvertBitArrayToByteArray $bitSubnetMask
                        [array]::Reverse($ByteArray)  # Convert to Network byte order
                        [System.Collections.BitArray] $bitSubnetMask = $ByteArray
                
                        ## Check IP
                        if ((ConvertBitArrayToBigInt $bitIpAddress.And($bitSubnetMask)) -eq (ConvertBitArrayToBigInt $bitSubnetAddress.And($bitSubnetMask))) {
                            if ($ReturnMatchingSubnets) {
                                $listSubnets.Add($Subnet)
                            }
                            else {
                                $Result = $true
                                continue
                            }
                        }
                    }
                }
            }

            ## Return list of matches or boolean result
            if ($ReturnMatchingSubnets) {
                if ($listSubnets.Count -gt 1) { Write-Output $listSubnets.ToArray() -NoEnumerate }
                elseif ($listSubnets.Count -eq 1) { Write-Output $listSubnets.ToArray() }
                else {
                    $Exception = New-Object ArgumentException -ArgumentList ('The IP address {0} does not belong to any of the provided subnets.' -f $IpAddress)
                    Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::ObjectNotFound) -CategoryActivity $MyInvocation.MyCommand -ErrorId 'TestIpAddressInSubnetNoMatch' -TargetObject $IpAddress
                }
            }
            else {
                Write-Output $Result
            }
        }
    }
}

#endregion

#region Test-MgCommandPrerequisites.ps1

<#
.SYNOPSIS
    Test Mg Graph Command Prerequisites
.EXAMPLE
    PS > Test-MgCommandPrerequisites 'Get-MgUser'
.INPUTS
    System.String
#>

function Test-MgCommandPrerequisites {
    [CmdletBinding()]
    [OutputType([bool])]
    param (
        # The name of a command.
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 1)]
        [Alias('Command')]
        [string[]] $Name,
        # The service API version.
        [Parameter(Mandatory = $false, Position = 2)]
        [ValidateSet('v1.0', 'beta')]
        [string] $ApiVersion = 'beta',
        # Specifies a minimum version.
        [Parameter(Mandatory = $false)]
        [version] $MinimumVersion,
        # Require "list" permissions rather than "get" permissions when Get-Mg* commands are specified.
        [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
        [switch] $RequireListPermissions
    )

    begin {
        [version] $MgAuthenticationModuleVersion = $null
        $Assembly = [System.AppDomain]::CurrentDomain.GetAssemblies() | Where-Object FullName -Like "Microsoft.Graph.Authentication,*"
        if ($Assembly.FullName -match "Version=(([0-9]+.[0-9]+.[0-9]+).[0-9]+),") {
            $MgAuthenticationModuleVersion = $Matches[2]
        }
        else {
            $MgAuthenticationModuleVersion = Get-Command 'Connect-MgGraph' -Module 'Microsoft.Graph.Authentication' | Select-Object -ExpandProperty Version
        }
        Write-Debug "Microsoft.Graph.Authentication module version loaded: $MgAuthenticationModuleVersion"
    }

    process {
        ## Initialize
        $result = $true

        ## Get Graph Command Details
        [hashtable] $MgCommandLookup = @{}
        foreach ($CommandName in $Name) {
            [array] $MgCommands = Find-MgGraphCommand -Command $CommandName -ApiVersion $ApiVersion

            $MgCommand = $MgCommands[0]
            if ($MgCommands.Count -gt 1) {
                ## Resolve from multiple results
                [array] $MgCommandsWithPermissions = $MgCommands | Where-Object Permissions -NE $null
                [array] $MgCommandsWithListPermissions = $MgCommandsWithPermissions | Where-Object URI -NotLike "*}"
                [array] $MgCommandsWithGetPermissions = $MgCommandsWithPermissions | Where-Object URI -Like "*}"
                if ($MgCommandsWithListPermissions -and $RequireListPermissions) {
                    $MgCommand = $MgCommandsWithListPermissions[0]
                }
                elseif ($MgCommandsWithGetPermissions) {
                    $MgCommand = $MgCommandsWithGetPermissions[0]
                }
                else {
                    $MgCommand = $MgCommands[0]
                }
            }

            $MgCommandLookup[$MgCommand.Command] = $MgCommand
        }

        ## Import Required Modules
        [string[]] $MgModules = @()
        foreach ($MgCommand in $MgCommandLookup.Values) {
            if (!$MgModules.Contains($MgCommand.Module)) {
                $MgModules += $MgCommand.Module
                [string] $ModuleName = "Microsoft.Graph.$($MgCommand.Module)"
                try {
                    if ($MgAuthenticationModuleVersion -lt $MinimumVersion) {
                        ## Check for newer module but load will likely fail due to old Microsoft.Graph.Authentication module
                        try {
                            Import-Module $ModuleName -MinimumVersion $MinimumVersion -Scope Global -ErrorAction Stop -Verbose:$false
                        }
                        catch [System.IO.FileLoadException] {
                            $result = $false
                            Write-Error -Exception $_.Exception -Category ResourceUnavailable -ErrorId 'MgModuleOutOfDate' -Message ("The module '{0}' with minimum version '{1}' was found but currently loaded 'Microsoft.Graph.Authentication' module is version '{2}'. To resolve, try opening a new PowerShell session and running the command again." -f $ModuleName, $MinimumVersion, $MgAuthenticationModuleVersion) -TargetObject $ModuleName -RecommendedAction ("Import-Module {0} -MinimumVersion '{1}'" -f $ModuleName, $MinimumVersion)
                        }
                        catch [System.IO.FileNotFoundException] {
                            $result = $false
                            Write-Error -Exception $_.Exception -Category ResourceUnavailable -ErrorId 'MgModuleWithVersionNotFound' -Message ("The module '{0}' with minimum version '{1}' not found. To resolve, try installing module '{0}' with the latest version. For example: Install-Module {0} -MinimumVersion '{1}'" -f $ModuleName, $MinimumVersion) -TargetObject $ModuleName -RecommendedAction ("Install-Module {0} -MinimumVersion '{1}'" -f $ModuleName, $MinimumVersion)
                        }
                    }
                    else {
                        ## Load module to match currently loaded Microsoft.Graph.Authentication module
                        try {
                            Import-Module $ModuleName -RequiredVersion $MgAuthenticationModuleVersion -Scope Global -ErrorAction Stop -Verbose:$false
                        }
                        catch [System.IO.FileLoadException] {
                            $result = $false
                            Write-Error -Exception $_.Exception -Category ResourceUnavailable -ErrorId 'MgModuleOutOfDate' -Message ("The module '{0}' was found but is not a compatible version. To resolve, try updating module '{0}' to version '{1}' to match currently loaded modules. For example: Update-Module {0} -RequiredVersion '{1}'" -f $ModuleName, $MgAuthenticationModuleVersion) -TargetObject $ModuleName -RecommendedAction ("Update-Module {0} -RequiredVersion '{1}'" -f $ModuleName, $MgAuthenticationModuleVersion)
                        }
                        catch [System.IO.FileNotFoundException] {
                            $result = $false
                            Write-Error -Exception $_.Exception -Category ResourceUnavailable -ErrorId 'MgModuleWithVersionNotFound' -Message ("The module '{0}' with version '{1}' not found. To resolve, try installing module '{0}' with version '{1}' to match currently loaded modules. For example: Install-Module {0} -RequiredVersion '{1}'" -f $ModuleName, $MgAuthenticationModuleVersion) -TargetObject $ModuleName -RecommendedAction ("Install-Module {0} -RequiredVersion '{1}'" -f $ModuleName, $MgAuthenticationModuleVersion)
                        }
                    }
                }
                catch {
                    $result = $false
                    Write-Error -ErrorRecord $_
                }
            }
        }
        Write-Verbose ('Required Microsoft Graph Modules: {0}' -f (($MgModules | ForEach-Object { "Microsoft.Graph.$_" }) -join ', '))

        ## Check MgModule Connection
        $MgContext = Get-MgContext
        if ($MgContext) {
            if ($MgContext.AuthType -eq 'Delegated') {
                ## Check MgModule Consented Scopes
                foreach ($MgCommand in $MgCommandLookup.Values) {
                    if ($MgCommand.Permissions -and (!$MgContext.Scopes -or !(Compare-Object $MgCommand.Permissions.Name -DifferenceObject $MgContext.Scopes -ExcludeDifferent -IncludeEqual))) {
                        $Exception = New-Object System.Security.SecurityException -ArgumentList "Additional scope required for command '$($MgCommand.Command)', call Connect-MgGraph with one of the following scopes: $($MgCommand.Permissions.Name -join ', ')"
                        Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::PermissionDenied) -ErrorId 'MgScopePermissionRequired'
                        $result = $false
                    }
                }
            }
            else {
                ## Check MgModule Consented Scopes
                foreach ($MgCommand in $MgCommandLookup.Values) {
                    if ($MgCommand.Permissions -and (!$MgContext.Scopes -or !(Compare-Object $MgCommand.Permissions.Name -DifferenceObject $MgContext.Scopes -ExcludeDifferent -IncludeEqual))) {
                        Write-Warning "Additional scope may be required for command '$($MgCommand.Command), add and consent ClientId '$($MgContext.ClientId)' to one of the following app scopes: $($MgCommand.Permissions.Name -join ', ')"
                    }
                }
            }
        }
        else {
            $Exception = New-Object System.Security.Authentication.AuthenticationException -ArgumentList "Authentication needed, call Connect-MgGraph."
            Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::AuthenticationError) -CategoryReason 'AuthenticationException' -ErrorId 'MgAuthenticationRequired'
            $result = $false
        }

        return $result
    }
}

#endregion

#region Test-MgModulePrerequisites.ps1

<#
.SYNOPSIS
    Test Mg Graph Module Prerequisites
.EXAMPLE
    PS > Test-MgModulePrerequisites 'CrossTenantInformation.ReadBasic.All'
.INPUTS
    System.String
#>

function Test-MgModulePrerequisites {
    [CmdletBinding()]
    [OutputType([bool])]
    param (
        # The name of scope
        [Parameter(Mandatory = $false, ValueFromPipeline = $true)]
        [Alias('Permission')]
        [string[]] $Scope
    )

    process {
        ## Initialize
        $result = $true
        
        ## Check MgModule Connection
        $MgContext = Get-MgContext
        if ($MgContext) {
            if ($Scope) {
                ## Check MgModule Consented Scopes
                [string[]] $ScopesMissing = Compare-Object $Scope -DifferenceObject $MgContext.Scopes | Where-Object SideIndicator -EQ '<=' | Select-Object -ExpandProperty InputObject
                if ($ScopesMissing) {
                    $Exception = New-Object System.Security.SecurityException -ArgumentList "Additional scope(s) needed, call Connect-MgGraph with all of the following scopes: $($ScopesMissing -join ', ')"
                    Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::PermissionDenied) -ErrorId 'MgScopePermissionRequired' -RecommendedAction ("Connect-MgGraph -Scopes $($ScopesMissing -join ',')")
                    $result = $false
                }
            }
        }
        else {
            $Exception = New-Object System.Security.Authentication.AuthenticationException -ArgumentList "Authentication needed, call Connect-MgGraph."
            Write-Error -Exception $Exception -Category ([System.Management.Automation.ErrorCategory]::AuthenticationError) -CategoryReason 'AuthenticationException' -ErrorId 'MgAuthenticationRequired'
            $result = $false
        }

        return $result
    }
}

#endregion

#region Test-PsElevation.ps1

<#
.SYNOPSIS
    Test if current PowerShell process is elevated to local administrator privileges.
.DESCRIPTION
    Test if current PowerShell process is elevated to local administrator privileges.
.EXAMPLE
    PS C:\>Test-PsElevation
    Test is current PowerShell process is elevated.
.LINK
    https://github.com/jasoth/Utility.PS
#>

function Test-PsElevation {
    [CmdletBinding()]
    [OutputType([bool])]
    param()

    try {
        $WindowsIdentity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        $WindowsPrincipal = New-Object 'System.Security.Principal.WindowsPrincipal' $WindowsIdentity
        $LocalAdministrator = [System.Security.Principal.WindowsBuiltInRole]::Administrator
        return $WindowsPrincipal.IsInRole($LocalAdministrator)
    }
    catch { 
        if ($_.Exception.InnerException) {
            Write-Error -Exception $_.Exception.InnerException -Category $_.CategoryInfo.Category -CategoryActivity $_.CategoryInfo.Activity -ErrorId $_.FullyQualifiedErrorId -TargetObject $_.TargetObject
        }
        else { Write-Error -ErrorRecord $_ }
    }
}

#endregion

#region Write-HostPrompt.ps1

<#
.SYNOPSIS
    Displays a PowerShell prompt for multiple fields or multiple choices.
.DESCRIPTION
    Displays a PowerShell prompt for multiple fields or multiple choices.
.EXAMPLE
    PS C:\>Write-HostPrompt "Prompt Caption" -Fields "Field 1", "Field 2"
    Display simple prompt for 2 fields.
.EXAMPLE
    PS C:\>$IntegerField = New-Object System.Management.Automation.Host.FieldDescription -ArgumentList "Integer Field" -Property @{ HelpMessage = "Help Message for Integer Field" }
    PS C:\>$IntegerField.SetParameterType([int[]])
    PS C:\>$DateTimeField = New-Object System.Management.Automation.Host.FieldDescription -ArgumentList "DateTime Field" -Property @{ HelpMessage = "Help Message for DateTime Field" }
    PS C:\>$DateTimeField.SetParameterType([datetime])
    PS C:\>Write-HostPrompt "Prompt Caption" "Prompt Message" -Fields $IntegerField, $DateTimeField
    Display prompt for 2 type-specific fields, with int field being an array.
.EXAMPLE
    PS C:\>Write-HostPrompt "Prompt Caption" -Choices "Choice &1", "Choice &2"
    Display simple prompt with 2 choices.
.EXAMPLE
    PS C:\>Write-HostPrompt "Prompt Caption" "Prompt Message" -DefaultChoice 2 -Choices @(
        New-Object System.Management.Automation.Host.ChoiceDescription -ArgumentList "&1`bChoice one" -Property @{ HelpMessage = "Help Message for Choice 1" }
        New-Object System.Management.Automation.Host.ChoiceDescription -ArgumentList "&2`bChoice two" -Property @{ HelpMessage = "Help Message for Choice 2" }
    )
    Display prompt with 2 choices and help messages that defaults to the second choice.
.EXAMPLE
    PS C:\>Write-HostPrompt "Prompt Caption" "Choose a number" -Choices "Menu Item A", "Menu Item B", "Menu Item C" -HelpMessages "Menu Item A Needs Help", "Menu Item B Needs More Help",, "Menu Item C Needs Crazy Help" -NumberedHotKeys
    Display prompt with 3 choices and help message that are automatically numbered.
.INPUTS
    System.Management.Automation.Host.FieldDescription
    System.Management.Automation.Host.ChoiceDescription
.OUTPUTS
    System.Collections.Generic.Dictionary[System.String,System.Management.Automation.PSObject]
    System.Int32
.LINK
    https://github.com/jasoth/Utility.PS
#>

function Write-HostPrompt {
    [CmdletBinding()]
    param
    (
        # Caption to preceed or title the prompt.
        [Parameter(Mandatory = $true, Position = 1)]
        [string] $Caption,
        # A message that describes the prompt.
        [Parameter(Mandatory = $false, Position = 2)]
        [string] $Message,
        # The fields in the prompt.
        [Parameter(Mandatory = $true, ParameterSetName = 'Fields', Position = 3, ValueFromPipeline = $true)]
        [System.Management.Automation.Host.FieldDescription[]] $Fields,
        # The choices the shown in the prompt.
        [Parameter(Mandatory = $true, ParameterSetName = 'Choices', Position = 3, ValueFromPipeline = $true)]
        [System.Management.Automation.Host.ChoiceDescription[]] $Choices,
        # Specifies a help message for each field or choice.
        [Parameter(Mandatory = $false, Position = 4)]
        [string[]] $HelpMessages = @(),
        # The index of the label in the choices to make default.
        [Parameter(Mandatory = $false, ParameterSetName = 'Choices', Position = 5)]
        [int] $DefaultChoice,
        # Use numbered hot keys (aka "keyboard accelerator") for each choice.
        [Parameter(Mandatory = $false, ParameterSetName = 'Choices', Position = 6)]
        [switch] $NumberedHotKeys
    )

    begin {
        ## Create list to capture multiple fields or multiple choices.
        [System.Collections.Generic.List[System.Management.Automation.Host.FieldDescription]] $listFields = New-Object System.Collections.Generic.List[System.Management.Automation.Host.FieldDescription]
        [System.Collections.Generic.List[System.Management.Automation.Host.ChoiceDescription]] $listChoices = New-Object System.Collections.Generic.List[System.Management.Automation.Host.ChoiceDescription]
    }

    process {
        switch ($PSCmdlet.ParameterSetName) {
            'Fields' {
                for ($iField = 0; $iField -lt $Fields.Count; $iField++) {
                    if ($iField -lt $HelpMessages.Count -and $HelpMessages[$iField]) { $Fields[$iField].HelpMessage = $HelpMessages[$iField] }
                    $listFields.Add($Fields[$iField])
                }
            }
            'Choices' {
                for ($iChoice = 0; $iChoice -lt $Choices.Count; $iChoice++) {
                    if ($NumberedHotKeys) { $Choices[$iChoice] = New-Object System.Management.Automation.Host.ChoiceDescription -ArgumentList "&$($iChoice+1)`b$($Choices[$iChoice].Label)" -Property @{ HelpMessage = $Choices[$iChoice].HelpMessage } }
                    #elseif (!$Choices[$iChoice].Label.Contains('&')) { $Choices[$iChoice] = New-Object System.Management.Automation.Host.ChoiceDescription -ArgumentList "&$($Choices[$iChoice].Label)" -Property @{ HelpMessage = $Choices[$iChoice].HelpMessage } }
                    if ($iChoice -lt $HelpMessages.Count -and $HelpMessages[$iChoice]) { $Choices[$iChoice].HelpMessage = $HelpMessages[$iChoice] }
                    $listChoices.Add($Choices[$iChoice])
                }
            }
        }
    }

    end {
        try {
            switch ($PSCmdlet.ParameterSetName) {
                'Fields' { return $Host.UI.Prompt($Caption, $Message, $listFields.ToArray()) }
                'Choices' { return $Host.UI.PromptForChoice($Caption, $Message, $listChoices.ToArray(), $DefaultChoice - 1) + 1 }
            }
        }
        catch [System.Management.Automation.PSInvalidOperationException] {
            ## Write Non-Terminating Error When In Non-Interactive Mode.
            Write-Error -ErrorRecord $_ -CategoryActivity $MyInvocation.MyCommand
        }
    }
}

#endregion

#region Add-MsIdServicePrincipal.ps1

<#
.SYNOPSIS
    Create service principal for existing application registration

.EXAMPLE
    PS > Add-MsIdServicePrincipal 10000000-0000-0000-0000-000000000001

    Create service principal for existing appId, 10000000-0000-0000-0000-000000000001.

.INPUTS
    System.String

#>

function Add-MsIdServicePrincipal {
    [CmdletBinding()]
    [OutputType([object])]
    param (
        # AppID of Application
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 1)]
        [string[]] $AppId
    )

    begin {
        ## Initialize Critical Dependencies
        $CriticalError = $null
        if (!(Test-MgCommandPrerequisites 'New-MgServicePrincipal' -MinimumVersion 2.8.0 -ErrorVariable CriticalError)) { return }
    }

    process {
        if ($CriticalError) { return }

        foreach ($_AppId in $AppId) {
            ## Create Service Principal from Application Registration
            New-MgServicePrincipal -AppId $_AppId
        }
    }
}

#endregion

#region Confirm-MsIdJwtTokenSignature.ps1

<#
.SYNOPSIS
    Validate the digital signature for JSON Web Token.

.EXAMPLE
    PS > Confirm-MsIdJwtTokenSignature $OpenIdConnectToken

    Validate the OpenId token was signed by token issuer based on the OIDC Provider Configuration for token issuer.

.EXAMPLE
    PS > Confirm-MsIdJwtTokenSignature $AccessToken

    Validate the access token was signed by token issuer based on the OIDC Provider Configuration for token issuer.

.INPUTS
    System.String
    
#>

function Confirm-MsIdJwtTokenSignature {
    [CmdletBinding()]
    [Alias('Confirm-JwtSignature')]
    [OutputType([bool])]
    param (
        # JSON Web Token (JWT)
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $Tokens
    )

    process {
        foreach ($Token in $Tokens) {
            $Jws = ConvertFrom-JsonWebSignature $Token
            $SigningKeys = $Jws.Payload.iss | Get-OpenIdProviderConfiguration -Keys | Where-Object use -EQ 'sig'
            $SigningKey = $SigningKeys | Where-Object kid -EQ $Jws.Header.kid
            $SigningCertificate = Get-X509Certificate $SigningKey.x5c

            Confirm-JsonWebSignature $Token -SigningCertificate $SigningCertificate
        }
    }
}

#endregion

#region ConvertFrom-MsIdAadcAadConnectorSpaceDn.ps1

<#
.SYNOPSIS
    Convert Azure AD connector space object Distinguished Name (DN) in AAD Connect

.EXAMPLE
    PS > ConvertFrom-MsIdAadcAadConnectorSpaceDn 'CN={414141414141414141414141414141414141414141413D3D}'

    Convert Azure AD connector space object DN in AAD Connect to sourceAnchor and sourceGuid.

.EXAMPLE
    PS > 'CN={4F626A656374547970655F30303030303030302D303030302D303030302D303030302D303030303030303030303030}' | ConvertFrom-MsIdAadcAadConnectorSpaceDn
    
    Convert Azure AD connector space object DN in AAD Connect to cloudAnchor and cloudGuid.

.INPUTS
    System.String
    
#>

function ConvertFrom-MsIdAadcAadConnectorSpaceDn {
    [CmdletBinding()]
    [OutputType([PSCustomObject])]
    param (
        # Azure AD Connector Space DN from AAD Connect
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
        [string] $InputObject
    )

    process {
        ## Extract Hex String
        if ($InputObject -imatch '(?:CN=)?\{?([0-9a-f]+)\}?') {
            [string] $HexString = $Matches[1]
        }
        else {
            [string] $HexString = $InputObject
        }

        ## Decode Hex String
        [string] $DecodedString = ConvertFrom-HexString $HexString
        if ($DecodedString -imatch '([a-z]+)_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})') {
            [guid] $CloudGuid = $Matches[2]
            $Result = [PSCustomObject]@{
                cloudAnchor = $DecodedString
                cloudGuid   = $CloudGuid
            }
        }
        else {
            [guid] $SourceGuid = ConvertFrom-Base64String $DecodedString -RawBytes
            $Result = [PSCustomObject]@{
                sourceAnchor = $DecodedString
                sourceGuid   = $SourceGuid
            }
        }

        Write-Output $Result
    }
}

#endregion

#region ConvertFrom-MsIdAadcSourceAnchor.ps1

<#
.SYNOPSIS
    Convert Azure AD Connect metaverse object sourceAnchor or Azure AD ImmutableId to sourceGuid.
    
.EXAMPLE
    PS > ConvertFrom-MsIdAadcSourceAnchor 'AAAAAAAAAAAAAAAAAAAAAA=='

    Convert Azure AD Connect metaverse object sourceAnchor base64 format to sourceGuid.

.EXAMPLE
    PS > ConvertFrom-MsIdAadcSourceAnchor '00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00'

    Convert Azure AD Connect metaverse object sourceAnchor hex format to sourceGuid.

.INPUTS
    System.String

#>

function ConvertFrom-MsIdAadcSourceAnchor {
    [CmdletBinding()]
    [Alias('ConvertFrom-MsIdAzureAdImmutableId')]
    [OutputType([guid], [string])]
    param (
        # Azure AD Connect metaverse object sourceAnchor.
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)]
        [string] $InputObject
    )

    process {
        if ($InputObject -imatch '(?:^|,)((?:[0-9a-f]{2} ?)+)(?:$|,)') {
            [guid] $SourceGuid = ConvertFrom-HexString $Matches[1].Trim() -RawBytes
        }
        elseif ($InputObject -imatch '(?:^|,)([0-9a-z+/=]+=+)(?:$|,)') {
            [guid] $SourceGuid = ConvertFrom-Base64String $Matches[1] -RawBytes
        }
        else {
            [guid] $SourceGuid = ConvertFrom-Base64String $InputObject -RawBytes
        }

        Write-Output $SourceGuid
    }
}

#endregion

#region ConvertFrom-MsIdUniqueTokenIdentifier.ps1

<#
.SYNOPSIS
    Convert Azure AD Unique Token Identifier to Request Id.
    
.EXAMPLE
    PS > ConvertFrom-MsIdUniqueTokenIdentifier 'AAAAAAAAAAAAAAAAAAAAAA'

    Convert Azure AD Unique Token Identifier to Request Id.

.EXAMPLE
    PS > Get-MgBetaAuditLogSignIn -Top 1 | ConvertFrom-MsIdUniqueTokenIdentifier

    Get a Sign-in Log Entry and Convert Azure AD Unique Token Identifier to Request Id.

.INPUTS
    System.String

#>

function ConvertFrom-MsIdUniqueTokenIdentifier {
    [CmdletBinding()]
    [OutputType([guid])]
    param (
        # Azure AD Unique Token Identifier
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [ValidateLength(22,22)]
        [Alias("UniqueTokenIdentifier")]
        [string] $InputObject
    )

    process {
        [guid] $SourceGuid = ConvertFrom-Base64String $InputObject -Base64Url -RawBytes
        return $SourceGuid
    }
}

#endregion

#region ConvertFrom-MsIdJwtToken.ps1

<#
.SYNOPSIS
    Convert Msft Identity token structure to PowerShell object.

.EXAMPLE
    PS > ConvertFrom-MsIdJwtToken $OpenIdConnectToken

    Convert OAuth Id Token JWS to PowerShell object.

.EXAMPLE
    PS > ConvertFrom-MsIdJwtToken $AccessToken

    Convert OAuth Access Token JWS to PowerShell object.

.INPUTS
    System.String
    
#>

function ConvertFrom-MsIdJwtToken {
    [CmdletBinding()]
    [OutputType([PSCustomObject])]
    param (
        # JSON Web Token (JWT)
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $Tokens
    )

    process {
        foreach ($Token in $Tokens) {
            ConvertFrom-JsonWebSignature $Token
        }
    }
}

#endregion

#region ConvertFrom-MsIdSamlMessage.ps1

<#
.SYNOPSIS
    Convert SAML Message structure to PowerShell object.

.EXAMPLE
    PS > ConvertFrom-MsIdSamlMessage 'Base64String'

    Convert Saml Message to XML object.

.INPUTS
    System.String

.OUTPUTS
    SamlMessage : System.Xml.XmlDocument
    
#>

function ConvertFrom-MsIdSamlMessage {
    [CmdletBinding()]
    [Alias('ConvertFrom-MsIdSamlRequest')]
    [Alias('ConvertFrom-MsIdSamlResponse')]
    #[OutputType([xml])]
    param (
        # SAML Message
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $InputObject
    )

    process {
        foreach ($_InputObject in $InputObject) {
            ConvertFrom-SamlMessage $_InputObject
        }
    }
}

#endregion

#region Expand-MsIdJwtTokenPayload.ps1

<#
.SYNOPSIS
    Extract Json Web Token (JWT) payload from JWS structure to PowerShell object.

.EXAMPLE
    PS > $MsalToken.IdToken | Expand-MsIdJwtTokenPayload

    Extract Json Web Token (JWT) payload from JWS structure to PowerShell object.

.INPUTS
    System.String
    
#>

function Expand-MsIdJwtTokenPayload {
    [CmdletBinding()]
    [OutputType([PSCustomObject])]
    param (
        # JSON Web Token (JWT)
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true)]
        [string[]] $Tokens
    )

    process {
        foreach ($Token in $Tokens) {
            $Jwt = ConvertFrom-JsonWebSignature $Token
            Write-Output $Jwt.Payload
        }
    }
}

#endregion

#region Export-MsIdAppConsentGrantReport.ps1

<#
.SYNOPSIS
    Lists and categorizes privilege for delegated permissions (OAuth2PermissionGrants) and application permissions (AppRoleAssignments).
    NOTE: This cmdlet can take many hours to run on large tenants.

.DESCRIPTION
    This cmdlet requires the `ImportExcel` module to be installed if you use the `-ReportOutputType ExcelWorkbook` parameter.

.EXAMPLE
    PS > Install-Module ImportExcel
    PS > Connect-MgGragh -Scopes Directory.Read.All
    PS > Export-MsIdAppConsentGrantReport -ReportOutputType ExcelWorkbook -ExcelWorkbookPath .\report.xlsx

    Output a report in Excel format

.EXAMPLE
    PS > Export-MsIdAppConsentGrantReport -ReportOutputType ExcelWorkbook -ExcelWorkbookPath .\report.xlsx -PermissionsTableCsvPath .\table.csv

    Output a report in Excel format and specify a local path for a customized CSV containing consent privilege categorizations

.EXAMPLE
    PS > $appConsent = Export-MsIdAppConsentGrantReport -ReportOutputType PowerShellObjects

    Return the resuls as hashtable for processing or exporting to other formats like csv or json.

.EXAMPLE
    PS > Export-MsIdAppConsentGrantReport -ExcelWorkbookPath .\report.xlsx -ThrottleLimit 5

    Increase the throttle limit to speed things up or reduce if you are getting throttling errors. Default is 20

#>

function Export-MsIdAppConsentGrantReport {
    param (
        # Output file location for Excel Workbook
        [Parameter(ParameterSetName = 'Excel', Mandatory = $true, Position = 1)]
        [string]
        $ExcelWorkbookPath,

        # Output type for the report.
        [ValidateSet("ExcelWorkbook", "PowerShellObjects")]
        [Parameter(ParameterSetName = 'Excel', Mandatory = $false, Position = 2)]
        [Parameter(ParameterSetName = 'PowerShell', Mandatory = $false, Position = 1)]
        [string]
        $ReportOutputType = "ExcelWorkbook",

        # Path to CSV file for Permissions Table
        # If not provided the default table will be downloaded from GitHub https://raw.githubusercontent.com/AzureAD/MSIdentityTools/main/assets/aadconsentgrantpermissiontable.csv
        [string]
        $PermissionsTableCsvPath,

        # The number of parallel threads to use when calling the Microsoft Graph API. Default is 20.
        [int]
        $ThrottleLimit = 20
    )

    $script:ObjectByObjectId = @{} # Cache for all directory objects
    $script:KnownMSTenantIds = @("f8cdef31-a31e-4b4a-93e4-5f571e91255a", "72f988bf-86f1-41af-91ab-2d7cd011db47")

    function Main() {
        if ("ExcelWorkbook" -eq $ReportOutputType) {
            # Determine if the ImportExcel module is installed since the parameter was included
            if ($null -eq (Get-Module -Name ImportExcel -ListAvailable)) {
                throw "The ImportExcel module is not installed. This is used to export the results to an Excel worksheet. Please install the ImportExcel Module before using this parameter or run without this parameter."
            }
        }

        if ($null -eq (Get-MgContext)) {
            Connect-MgGraph -Scopes Directory.Read.All
        }
        if ($null -eq (Get-MgContext)) {
            throw "You must connect to the Microsoft Graph before running this command."
        }

        $appConsents = GetAppConsentGrants

        if ($null -ne $appConsents) {

            $appConsentsWithRisk = AddConsentRisk $appConsents

            if ("ExcelWorkbook" -eq $ReportOutputType) {
                Write-Verbose "Generating Excel workbook at $ExcelWorkbookPath"

                WriteMainProgress Complete -Status "Saving report..." -ForceRefresh
                GenerateExcelReport -AppConsentsWithRisk $appConsentsWithRisk -Path $ExcelWorkbookPath
            }
            else {
                WriteMainProgress Complete -Status "Finishing up" -ForceRefresh
                Write-Output $appConsentsWithRisk
            }

        }
        else {
            throw "An error occurred while retrieving app consent grants. Please try again."
        }
    }

    function GetAppConsentGrants {
        # Get all ServicePrincipal objects and add to the cache
        Write-Verbose "Retrieving ServicePrincipal objects..."

        WriteMainProgress ServicePrincipal -Status "This can take some time..." -ForceRefresh
        $count = Get-MgServicePrincipalCount -ConsistencyLevel eventual
        WriteMainProgress ServicePrincipal -ChildPercent 5 -Status "Retrieving $count service principals. This can take some time..." -ForceRefresh
        Start-Sleep -Milliseconds 500 #Allow message to update
        $servicePrincipalProps = "id,appId,appOwnerOrganizationId,displayName,appRoles,appRoleAssignmentRequired"
        $script:ServicePrincipals = Get-MgServicePrincipal -ExpandProperty "appRoleAssignments" -Select $servicePrincipalProps -All -PageSize 999


        $appPerms = GetApplicationPermissions
        $delPerms = GetDelegatePermissions

        $allPermissions = @()
        $allPermissions += $appPerms
        $allPermissions += $delPerms
        return $allPermissions
    }

    function CacheObject($Object) {
        if ($Object) {
            $script:ObjectByObjectId[$Object.Id] = $Object
        }
    }

    # Function to retrieve an object from the cache (if it's there), or from Entra ID (if not).
    function GetObjectByObjectId($ObjectId) {
        if (-not $script:ObjectByObjectId.ContainsKey($ObjectId)) {
            Write-Verbose ("Querying Entra ID for object '{0}'" -f $ObjectId)
            try {
                $object = (Get-MgDirectoryObjectById -Ids $ObjectId)
                CacheObject -Object $object
            }
            catch {
                Write-Verbose "Object not found."
            }
        }
        return $script:ObjectByObjectId[$ObjectId]
    }

    function IsMicrosoftApp($AppOwnerOrganizationId) {
        if ($AppOwnerOrganizationId -in $script:KnownMSTenantIds) { return "Yes" }
        else { return "No" }
    }

    function GetScopeLink($scope) {
        if ("ExcelWorkbook" -ne $ReportOutputType) { return $scope }
        if ([string]::IsNullOrEmpty($scope)) { return $scope }
        return "=HYPERLINK(`"https://graphpermissions.merill.net/permission/$scope`",`"$scope`")"
    }

    function GetServicePrincipalLink($spId, $appId, $name) {
        if ("ExcelWorkbook" -ne $ReportOutputType) { return $name }
        if ([string]::IsNullOrEmpty($spId) -or [string]::IsNullOrEmpty($appId) -or [string]::IsNullOrEmpty($name)) { return $name }
        return "=HYPERLINK(`"https://entra.microsoft.com/#view/Microsoft_AAD_IAM/ManagedAppMenuBlade/~/Overview/objectId/$($spId)/appId/$($appId)/preferredSingleSignOnMode~/null/servicePrincipalType/Application/fromNav/`",`"$($name)`")"
    }

    function GetUserLink($userId, $name) {
        $returnValue = $name
        if ([string]::IsNullOrEmpty($name)) { $returnValue = $userId } # If we don't have a name, show the userid

        if ("ExcelWorkbook" -eq $ReportOutputType -and ![string]::IsNullOrEmpty($userId)) { #If Excel and linkable then show name
            $returnValue = "=HYPERLINK(`"https://entra.microsoft.com/#view/Microsoft_AAD_UsersAndTenants/UserProfileMenuBlade/~/overview/userId/$($userId)/hidePreviewBanner~/true`",`"$($name)`")"
        }
        return $returnValue
    }

    function GetApplicationPermissions() {
        $count = 0
        $permissions = @()

        # We need to call Get-MgServicePrincipal again so we can expand appRoleAssignments

        #$servicePrincipalsWithAppRoleAssignments = Get-MgServicePrincipal -ExpandProperty "appRoleAssignments" -Select $servicePrincipalProps -All -PageSize 999
        foreach ($client in $script:ServicePrincipals) {
            $count++
            $appPercent = (($count / $servicePrincipals.Count) * 100)
            WriteMainProgress AppPerm -Status "[$count of $($servicePrincipals.Count)] $($client.DisplayName)" -ChildPercent $appPercent

            $isMicrosoftApp = IsMicrosoftApp -AppOwnerOrganizationId $client.AppOwnerOrganizationId
            $spLink = GetServicePrincipalLink -spId $client.Id -appId $client.AppId -name $client.DisplayName
            Write-Verbose "Getting app permissions: [$count of $($servicePrincipals.Count)] $($client.DisplayName)"

            foreach ($grant in $client.AppRoleAssignments) {
                # Look up the related SP to get the name of the permission from the AppRoleId GUID
                $appRole = $servicePrincipals.AppRoles | Where-Object { $_.id -eq $grant.AppRoleId } | Select-Object -First 1
                $appRoleValue = $grant.AppRoleId
                if ($null -ne $appRole -and ![string]::IsNullOrEmpty($appRole.value)) {
                    $appRoleValue = $appRole.Value
                }

                $permissions += New-Object PSObject -Property ([ordered]@{
                        "PermissionType"            = "Application"
                        "ConsentTypeFilter"         = "Application"
                        "ClientObjectId"            = $client.Id
                        "AppId"                     = $client.AppId
                        "ClientDisplayName"         = $spLink
                        "ResourceObjectId"          = $grant.ResourceId
                        "ResourceObjectIdFilter"    = $grant.ResourceId
                        "ResourceDisplayName"       = $grant.ResourceDisplayName
                        "ResourceDisplayNameFilter" = $grant.ResourceDisplayName
                        "Permission"                = GetScopeLink $appRoleValue
                        "PermissionFilter"          = $appRoleValue
                        "PrincipalObjectId"         = ""
                        "PrincipalDisplayName"      = ""
                        "MicrosoftApp"              = $isMicrosoftApp
                        "AppOwnerOrganizationId"    = $client.AppOwnerOrganizationId
                    })
            }
        }
        return $permissions
    }

    function GetDelegatePermissions {

        $permissions = @()
        $servicePrincipals = $script:servicePrincipals

        $spList = [System.Collections.Concurrent.ConcurrentDictionary[string, object]]::new()
        $spListFailed = [System.Collections.Concurrent.ConcurrentDictionary[string, object]]::new()

        WriteMainProgress DownloadDelegatePerm -Status "Downloading all delegate permissions..." -ForceRefresh
        Write-Verbose "Downloading all delegate permissions using $ThrottleLimit threads"

        $job = $script:servicePrincipals | ForEach-Object -AsJob -ThrottleLimit $ThrottleLimit -Parallel {
            $dict = $using:spList
            $dictFailed = $using:spList
            $servicePrincipalId = $_.Id

            try {
                $oAuth2PermGrants = Get-MgServicePrincipalOauth2PermissionGrant -ServicePrincipalId $servicePrincipalId -All -PageSize 999
                $item = New-Object PSObject -Property ([ordered]@{
                        ServicePrincipal       = $_
                        Oauth2PermissionGrants = $oAuth2PermGrants
                    })
                $success = $dict.TryAdd($servicePrincipalId, $item)
                if (!$success) {
                    $dictFailed.TryAdd($servicePrincipalId, "Failed to add service principal $servicePrincipalId") | Out-Null
                }
            }
            catch {
                $dictFailed.TryAdd($servicePrincipalId, $_) | Out-Null
            }
        }

        while ($job.State -eq 'Running') {
            $count = $spList.Count
            if ($count -eq 0) {
                Start-Sleep -Seconds 1
            }
            else {
                $totalCount = $servicePrincipals.Count
                # get the last item by index
                $lastSp = $servicePrincipals[$count]

                $delPercent = (($count / $totalCount) * 100)
                WriteMainProgress DownloadDelegatePerm -Status "[$count of $totalCount] $($lastSp.DisplayName)" -ChildPercent $delPercent -ForceRefresh
            }
        }

        if ($spListFailed.Count -gt 0) {
            Write-Error "Failed to retrieve delegate permissions for $($spListFailed.Count) service principals."
            Write-Error "Try reducing the -ParallelBatchSize parameter to avoid throttling issues."
            Write-Error $spListFailed.Values
            throw
        }

        $totalCount = $spList.Values.Count
        $count = 0
        foreach ($sp in $spList.Values) {
            $client = $sp.ServicePrincipal

            $count++
            $delPercent = (($count / $totalCount) * 100)
            WriteMainProgress ProcessDelegatePerm -status "[$count of $($totalCount)] $($client.DisplayName)" -childPercent $delPercent
            Write-Verbose "Processing delegate permissions for $($client.DisplayName)"

            $isMicrosoftApp = IsMicrosoftApp -AppOwnerOrganizationId $client.AppOwnerOrganizationId
            $spLink = GetServicePrincipalLink -spId $client.Id -appId $client.AppId -name $client.DisplayName
            $oAuth2PermGrants = $sp.Oauth2PermissionGrants

            foreach ($grant in $oAuth2PermGrants) {
                if ($grant.Scope) {
                    $grant.Scope.Split(" ") | Where-Object { $_ } | ForEach-Object {
                        $scope = $_
                        $resource = GetObjectByObjectId -ObjectId $grant.ResourceId
                        $principalDisplayName = ""

                        if ($grant.PrincipalId) {
                            $principal = GetObjectByObjectId -ObjectId $grant.PrincipalId
                            $principalDisplayName = $principal.AdditionalProperties.displayName
                        }

                        $simplifiedgranttype = ""
                        if ($grant.ConsentType -eq "AllPrincipals") {
                            $simplifiedgranttype = "Delegated-AllPrincipals"
                        }
                        elseif ($grant.ConsentType -eq "Principal") {
                            $simplifiedgranttype = "Delegated-Principal"
                        }

                        $permissions += New-Object PSObject -Property ([ordered]@{
                                "PermissionType"            = $simplifiedgranttype
                                "ConsentTypeFilter"         = $simplifiedgranttype
                                "ClientObjectId"            = $client.Id
                                "AppId"                     = $client.AppId
                                "ClientDisplayName"         = $spLink
                                "ResourceObjectId"          = $grant.ResourceId
                                "ResourceObjectIdFilter"    = $grant.ResourceId
                                "ResourceDisplayName"       = $resource.AdditionalProperties.displayName
                                "ResourceDisplayNameFilter" = $resource.AdditionalProperties.displayName
                                "Permission"                = GetScopeLink $scope
                                "PermissionFilter"          = $scope
                                "PrincipalObjectId"         = $grant.PrincipalId
                                "PrincipalDisplayName"      = GetUserLink -userId $grant.PrincipalId -name $principalDisplayName
                                "MicrosoftApp"              = $isMicrosoftApp
                                "AppOwnerOrganizationId"    = $client.AppOwnerOrganizationId
                            })
                    }
                }
            }
        }
        return $permissions
    }

    function AddConsentRisk ($AppConsents) {

        $permstable = GetPermissionsTable -PermissionsTableCsvPath $PermissionsTableCsvPath
        $permsHash = @{}

        foreach ($perm in $permstable) {
            $key = $perm.Type + $perm.Permission
            $permsHash[$key] = $perm
            if ($perm.permission -Match ".") {
                $key = $perm.Type + $perm.Permission.Split(".")[0]
                $permsHash[$key] = $perm
            }
        }
        # Process Privilege for gathered data
        $count = 0
        $AppConsents | ForEach-Object {

            $consent = $_
            $count++

            WriteMainProgress GenerateExcel -Status "[$count of $($AppConsents.Count)] $($consent.PermissionFilter)" -ChildPercent (($count / $AppConsents.Count) * 100)
            $scope = $consent.PermissionFilter
            $type = ""
            if ($consent.PermissionType -eq "Delegated-AllPrincipals" -or $consent.PermissionType -eq "Delegated-Principal") {
                $type = "Delegated"
            }
            elseif ($consent.PermissionType -eq "Application") {
                $type = "Application"
            }

            # Check permission table for an exact match
            Write-Debug ("Permission Scope: $Scope")

            $scoperoot = $scope.Split(".")[0]

            $risk = "Unranked"
            # Search for matching root level permission if there was no exact match
            if ($permsHash.ContainsKey($type + $scope)) {
                # Exact match e.g. Application.Read.All
                $risk = $permsHash[$type + $scope].Privilege
            }
            elseif ($permsHash.ContainsKey($type + $scoperoot)) {
                #Matches top level e.g. Application.
                $risk = $permsHash[$type + $scoperoot].Privilege
            }
            elseif ($type -eq "Application") {
                # Application permissions without exact or root matches with write scope
                $risk = "Medium"
                if ($scope -like "*Write*") {
                    $risk = "High"
                }
            }
            # Add the privilege to the current object
            Add-Member -InputObject $_ -MemberType NoteProperty -Name Privilege -Value $risk
            Add-Member -InputObject $_ -MemberType NoteProperty -Name PrivilegeFilter -Value $risk
        }

        return $AppConsents
    }

    function GetPermissionsTable {
        param ($PermissionsTableCsvPath)

        if ($null -like $PermissionsTableCsvPath) {
            # Create hash table of permissions and permissions privilege
            $permstable = Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/AzureAD/MSIdentityTools/main/assets/aadconsentgrantpermissiontable.csv' | ConvertFrom-Csv -Delimiter ','
        }
        else {

            $permstable = Import-Csv $PermissionsTableCsvPath -Delimiter ','
        }

        return $permstable
    }

    function WriteMainProgress(
        # The current step of the overal generation
        [ValidateSet("ServicePrincipal", "AppPerm", "DownloadDelegatePerm", "ProcessDelegatePerm", "GenerateExcel", "Complete")]
        $MainStep,
        $Status = "Processing...",
        # The percentage of completion within the child step
        $ChildPercent,
        [switch]$ForceRefresh) {
        $percent = 0
        switch ($MainStep) {
            "ServicePrincipal" {
                $percent = GetNextPercent $ChildPercent 2 10
                $activity = "Downloading service principals"
            }
            "AppPerm" {
                $percent = GetNextPercent $ChildPercent 10 50
                $activity = "Downloading application permissions"
            }
            "DownloadDelegatePerm" {
                $percent = GetNextPercent $ChildPercent 50 75
                $activity = "Downloading delegate permissions"
            }
            "ProcessDelegatePerm" {
                $percent = GetNextPercent $ChildPercent 75 90
                $activity = "Processing delegate permissions"
            }
            "GenerateExcel" {
                $percent = GetNextPercent $ChildPercent 90 99
                $activity = "Processing risk information"
            }
            "Complete" {
                $percent = 100
                $activity = "Complete"
            }
        }

        if ($ForceRefresh.IsPresent) {
            Start-Sleep -Milliseconds 250
        }
        Write-Progress -Id 0 -Activity $activity -PercentComplete $percent -Status $Status
    }

    function GetNextPercent($childPercent, $parentPercent, $nextPercent) {
        if ($childPercent -eq 0) { return $parentPercent }

        $gap = $nextPercent - $parentPercent
        return (($childPercent / 100) * $gap) + $parentPercent
    }

    function GenerateExcelReport ($AppConsentsWithRisk, $Path) {

        $maxRows = $AppConsentsWithRisk.Count + 1

        # Delete the existing output file if it already exists
        $OutputFileExists = Test-Path $Path
        if ($OutputFileExists -eq $true) {
            Get-ChildItem $Path | Remove-Item -Force
        }

        $servicePrincipalAssignedToList = @{}
        $highprivilegeobjects = $AppConsentsWithRisk | Where-Object { $_.PrivilegeFilter -eq "High" }
        $highprivilegeobjects | ForEach-Object {
            $clientId = $_.ClientObjectId
            if (!$servicePrincipalAssignedToList.ContainsKey($clientId)) {
                # If we already have the value, don't call graph again
                $servicePrincipal = $script:ServicePrincipals | Where-Object { $_.Id -eq $clientId }

                $assignedTo = ""
                if ($servicePrincipal.AppRoleAssignmentRequired -eq $true) {
                    $userAssignments = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $_.ClientObjectId -All:$true
                    $group = $userAssignments | Group-Object -Property PrincipalType
                    foreach ($g in $group) {
                        if ($g.Name -eq "User") {
                            $assignedTo += "$($g.Count) $($g.Name)s "
                        }
                    }
                }
                elseif ($servicePrincipal.AppRoleAssignmentRequired -eq $false) {
                    $assignedTo = "All Users"
                }
                $servicePrincipalAssignedToList[$clientId] = $assignedTo
            }
            $assignedToValue = $servicePrincipalAssignedToList[$clientId]
            Add-Member -InputObject $_ -MemberType NoteProperty -Name AssignedTo -Value $assignedToValue
        }
        $highprivilegeusers = $highprivilegeobjects | Where-Object { ![string]::IsNullOrEmpty($_.PrincipalObjectId) } | Select-Object PrincipalDisplayName, Privilege | Sort-Object PrincipalDisplayName -Unique</