MSIdentityTools

2.0.21

Set-MsIdServicePrincipalVisibleInMyApps.ps1

                                
    function Set-MsIdServicePrincipalVisibleInMyApps {

    <#

    .SYNOPSIS

        Toggles whether application service principals are visible when launching myapplications.microsoft.com (MyApps)

    .DESCRIPTION

        For each provided service principal ID, this cmdlet will add (or remove) the 'HideApp' tag to (or from) its list of tags.

        MyApps reads this tag to determine whether to show the service principal in the UX.

        -Verbose will give insight into the cmdlet's activities.

        Requires Application.ReadWrite.All (to manage service principals), i.e. Connect-MgGraph -Scopes Application.ReadWrite.All

    .PARAMETER Visible

        Whether to show or hide the SP. Supply $true or $false.

    .PARAMETER InFile

        A file specifying the list of SP IDs to process. Provide one guid per line with no other characters.

    .PARAMETER OutFile

        (Optional) The list of changed SPs is written to a file at this location for easy recovery. A default file will be generated if a path is not provided.

    .PARAMETER WhatIf

        (Optional) When set, shows which SPs would be changed without changing them.

    .PARAMETER Top

        (Optional) The number of SPs to process from the list with each request. Default 100.

    .PARAMETER Skip

        (Optional) Determines where in the list to begin executing.

    .PARAMETER Continue

        (Optional) After a failure due to request throttling, set this to the number of inputs that were evaluated before throttling began on the previous request.

    .EXAMPLE

        Set-MsIdServicePrincipalVisibleInMyApps -Visible $false -InFile .\sps.txt -OutFile .\output.txt -Verbose

        Adds the 'HideApp' tag for each Service Principal listed by guid in the sps.txt file. This ensures that the app is no longer visible in the MyApps portal.

        Creates a list of changed SPs, written to output.txt, at the script execution directory.

        Provides verbose output to assist with monitoring.

    .EXAMPLE

        Set-MsIdServicePrincipalVisibleInMyApps -Visible $true -InFile .\sps.txt -OutFile .\output.txt -Verbose

        Removes the 'HideApp' tag for each Service Principal listed by guid in the sps.txt file. This ensures that the app is visible in the MyApps portal.

        Creates a list of changed SPs, written to output.txt, at the script execution directory.

        Provides verbose output to assist with monitoring.

    .EXAMPLE

        Set-MsIdServicePrincipalVisibleInMyApps -Visible $true -InFile .\sps.txt -WhatIf

        Removes the 'HideApp' tag for each Service Principal listed by guid in the sps.txt file. This ensures that the app is visible in the MyApps portal.

        Provides a 'whatif' analysis to show what would've been updated without the -WhatIf switch.

    .EXAMPLE

        Set-MsIdServicePrincipalVisibleInMyApps -Visible $true -InFile .\sps.txt -WhatIf -Top 200

        Removes the 'HideApp' tag for each Service Principal listed by guid in the sps.txt file. This ensures that the app is visible in the MyApps portal.

        Provides a 'whatif' analysis to show what would've been updated without the -WhatIf switch. Processes 200 service principals.

    .NOTES

        THIS CODE-SAMPLE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED 

        OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR 

        FITNESS FOR A PARTICULAR PURPOSE.

        This sample is not supported under any Microsoft standard support program or service. 

        The script is provided AS IS without warranty of any kind. Microsoft further disclaims all

        implied warranties including, without limitation, any implied warranties of merchantability

        or of fitness for a particular purpose. The entire risk arising out of the use or performance

        of the sample and documentation remains with you. In no event shall Microsoft, its authors,

        or anyone else involved in the creation, production, or delivery of the script be liable for 

        any damages whatsoever (including, without limitation, damages for loss of business profits, 

        business interruption, loss of business information, or other pecuniary loss) arising out of 

        the use of or inability to use the sample or documentation, even if Microsoft has been advised 

        of the possibility of such damages, rising out of the use of or inability to use the sample script, 

        even if Microsoft has been advised of the possibility of such damages.   

    #>

    [CmdletBinding()]

    Param(

        [Parameter(Mandatory=$true)]

        [bool]$Visible,

        [Parameter(Mandatory=$true)]

        [string]$InFile,

        [Parameter(Mandatory=$false)]

        [string]$OutFile,

        [Parameter(Mandatory=$false)]

        [switch]$WhatIf,

        [Parameter(Mandatory=$false)]

        [int]$Top=100,

        [Parameter(Mandatory=$false)]

        [int]$Skip=0,

        [Parameter(Mandatory=$false)]

        [int]$Continue=0

    )

    begin {

        function ConvertTo-ValidGuid {

            Param(

                [Parameter(ValueFromPipeline=$true, Mandatory=$true)]

                [string]$Value

            )

            try {

                $id = [System.Guid]::Parse($value)

                return $id

            } catch {

                Write-Warning "$(Get-Date -f T) - Failed to parse SP id: $($value)"

                return $null

            }

        }

        function ConvertTo-ServicePrincipal {

            Param(

                [Parameter(ValueFromPipeline=$true, Mandatory=$true)]

                [string]$Value

            )

            try {

                $sp = Get-MgServicePrincipal -ServicePrincipalId $Value

                if ($null -eq $sp) {

                    Write-Warning "$(Get-Date -f T) - SP not found for id: $($Value)"

                }

                else {

                    Write-Verbose "$(Get-Date -f T) - SP found for id: $($Value)"

                }

                return $sp

            } catch {

                # 429 means we are being throttled

                # so we want to back off from additional calls as well

                if ($_ -Contains '429') {

                    throw $_

                }

                Write-Warning "$(Get-Date -f T) - Error retrieving SP: $($Value)"

                return $null

            }

        }

        function Assert-IsHidden {

            Param(

                [Parameter(Mandatory=$true)]

                [Object]$Sp,

                [Parameter(Mandatory=$true)]

                [bool]$Value

            )

            return ($Sp.Tags -Contains $Tag_HideApp) -eq $Value

        }

        function Set-IsHidden {

            Param(

                [Parameter(Mandatory=$true)]

                [Object]$Sp,

                [Parameter(Mandatory=$true)]

                [bool]$Value

            )

            if ($Value) {

                $tags = $Sp.Tags + $Tag_HideApp

            } else {

                if (($Sp.Tags.count -eq 1) -and ($Sp.Tags -Contains $Tag_HideApp)) {

                    $tags = @()

                } else {

                    $tags = $Sp.Tags | Where-Object {$_ -ne $Tag_HideApp}

                }

            }

            try {

                Update-MgServicePrincipal -ServicePrincipalId $Sp.Id -Tags $tags

                return $true

            } catch {

                # 429 means we are being throttled

                # so we want to back off from additional calls as well

                if ($_ -Contains '429') {

                    throw $_

                }

                Write-Warning "$(Get-Date -f T) - Error setting SP tags: $($Sp.Id)"

                return $false

            }

        }

        function New-OutFile {

            Param(

                [Parameter(Mandatory=$true)]

                [string]$Path

            )

            if (Test-Path -Path $Path) {

                Clear-Content -Path $Path

            } else {

                New-Item -Path $Path -ItemType "file" > $null

            }

        }

        ## Initialize Critical Dependencies

        $CriticalError = $null

        try {

            ## Import Required Modules

            Import-Module Microsoft.Graph.Applications -MinimumVersion 1.10.0 -ErrorAction Stop

            ## Check MgModule Connection

            $MgContext = Get-MgContext

            if ($MgContext) {

                ## Check MgModule Consented Scopes

                $MgPermissions = Find-MgGraphCommand -Command Update-MgServicePrincipal | Select-Object -First 1 -ExpandProperty Permissions

                if (!(Compare-Object $MgPermissions.Name -DifferenceObject $MgContext.Scopes -ExcludeDifferent)) {

                    Write-Error "Additional scope needed, call Connect-MgGraph with one of the following scopes: $($MgPermissions.Name -join ', ')" -ErrorAction Stop

                }

            }

            else {

                Write-Error "Authentication needed, call Connect-MgGraph." -ErrorAction Stop

            }

        }

        catch { Write-Error -ErrorRecord $_ -ErrorVariable CriticalError; return }

    }

    process {

        ## Return immediately on critical error

        if ($CriticalError) { return }

        #Define outfile

        if ([string]::IsNullOrEmpty($OutFile))

        {

            $OutFile = "sp-backup-$((New-Guid).ToString()).txt"

        }

        #Hide app tag

        $Tag_HideApp = 'HideApp'

        #Count variables

        $i = -1

        $updated = @()

        $count_NotParsed = 0

        $count_NotFound = 0

        $count_NotChanged = 0

        $count_NotSaved = 0

        $throttled = $false

        #Get the list of SPs to be processed

        $sps = Get-Content $InFile

        $total = $sps.Count

        Write-Verbose -Message "$(Get-Date -f T) - $($total) inputs to process"

        for ($i = $Continue; $i -lt $Top -and $i+$Skip -lt $total; $i++) {

            Write-Verbose -Message "$(Get-Date -f T) - Processing $($i)"

            if ($total -eq 1) {

                $value = $sps

            } else {

                $value = $sps[$i+$Skip]

            }

            Write-Verbose -Message "$(Get-Date -f T) - Input: $($value)"

            $id = $value | ConvertTo-ValidGuid

            if ($null -eq $id) {

                $count_NotParsed++

                continue

            }

            try {

                $sp = $id | ConvertTo-ServicePrincipal

                if ($null -eq $sp) {

                    $count_NotFound++

                    continue

                }

            } catch {

                $throttled = $true

                break

            }

            if (Assert-IsHidden -Sp $sp -Value (!$Visible)) {

                $count_NotChanged++

                continue

            }

            if ($WhatIf) {

                $updated += $sp.Id

            } else {

                try {

                    if (Set-IsHidden -Sp $sp -Value (!$Visible)) {

                        $updated += $sp.Id

                    } else {

                        $count_NotSaved++

                        continue

                    }

                } catch {

                    $throttled = $true

                    break

                }

            }

        }

        Write-Verbose -Message "$(Get-Date -f T) - Generating output"

        if ($Continue -eq 0 -and $Skip -eq 0) {

            New-OutFile -Path $OutFile

        }

        $updated | ForEach-Object { $_ | Add-Content -Path $OutFile }

        Write-Verbose -Message "$(Get-Date -f T) - $($count_NotParsed) inputs not parseable as guids"

        Write-Verbose -Message "$(Get-Date -f T) - $($count_NotFound) guids do not map to SP Ids"

        Write-Verbose -Message "$(Get-Date -f T) - $($count_NotChanged) SPs were already in the desired state"

        if ($WhatIf) {

            Write-Verbose -Message "$(Get-Date -f T) - $($updated.Count) SPs would be changed. A list of guids has been written to $($OutFile)"

        } else {

            Write-Verbose -Message "$(Get-Date -f T) - $($count_NotSaved) SPs had an error trying to save the change"

            Write-Verbose -Message "$(Get-Date -f T) - $($updated.Count) SPs were changed. A list of guids has been written to $($OutFile)"

        }

        if ($throttled) {

            Write-Warning "Operation throttled after processing $($i) items"

            if (!$WhatIf) {

                Write-Warning "$(Get-Date -f T) - Please wait 5 minutes then execute the following script to continue:"

                Write-Warning "$(Get-Date -f T) - Set-MsIdServicePrincipalVisibleInMyApps -InFile $($InFile) -OutFile $($OutFile) -Visible `$$($Visible) -Top $($Top) -Skip $($Skip) -Continue $($i)"

            }

        } elseif ($sps.Count -gt $Skip+$Top) {

            if (!$WhatIf) {

                Write-Verbose -Message "$(Get-Date -f T) - Run the following script to process the next batch of $($Top):"

                Write-Verbose -Message "$(Get-Date -f T) - Set-MsIdServicePrincipalVisibleInMyApps -InFile $($InFile) -OutFile $($OutFile) -Visible `$$($Visible) -Top $($Top) -Skip $($Skip+$Top)"

            }

        }

        if (!$WhatIf) {

                Write-Verbose -Message "$(Get-Date -f T) - Run the following script to roll back this operation:"

                Write-Verbose -Message "$(Get-Date -f T) - Set-MsIdServicePrincipalVisibleInMyApps -InFile $($OutFile) -Visible `$$(!$Visible)"

        }

    }

}

# SIG # Begin signature block

# MIInrQYJKoZIhvcNAQcCoIInnjCCJ5oCAQExDzANBglghkgBZQMEAgEFADB5Bgor

# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG

# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCALoLmc3CRe9ocO

# 99DL8A6hI33Un8GvB+X99oyJRd1myKCCDYEwggX/MIID56ADAgECAhMzAAACzI61

# lqa90clOAAAAAALMMA0GCSqGSIb3DQEBCwUAMH4xCzAJBgNVBAYTAlVTMRMwEQYD

# VQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jvc29mdCBDb2RlIFNpZ25p

# bmcgUENBIDIwMTEwHhcNMjIwNTEyMjA0NjAxWhcNMjMwNTExMjA0NjAxWjB0MQsw

# CQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9u

# ZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMR4wHAYDVQQDExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB

# AQCiTbHs68bADvNud97NzcdP0zh0mRr4VpDv68KobjQFybVAuVgiINf9aG2zQtWK

# No6+2X2Ix65KGcBXuZyEi0oBUAAGnIe5O5q/Y0Ij0WwDyMWaVad2Te4r1Eic3HWH

# UfiiNjF0ETHKg3qa7DCyUqwsR9q5SaXuHlYCwM+m59Nl3jKnYnKLLfzhl13wImV9

# DF8N76ANkRyK6BYoc9I6hHF2MCTQYWbQ4fXgzKhgzj4zeabWgfu+ZJCiFLkogvc0

# RVb0x3DtyxMbl/3e45Eu+sn/x6EVwbJZVvtQYcmdGF1yAYht+JnNmWwAxL8MgHMz

# xEcoY1Q1JtstiY3+u3ulGMvhAgMBAAGjggF+MIIBejAfBgNVHSUEGDAWBgorBgEE

# AYI3TAgBBggrBgEFBQcDAzAdBgNVHQ4EFgQUiLhHjTKWzIqVIp+sM2rOHH11rfQw

# UAYDVR0RBEkwR6RFMEMxKTAnBgNVBAsTIE1pY3Jvc29mdCBPcGVyYXRpb25zIFB1

# ZXJ0byBSaWNvMRYwFAYDVQQFEw0yMzAwMTIrNDcwNTI5MB8GA1UdIwQYMBaAFEhu

# ZOVQBdOCqhc3NyK1bajKdQKVMFQGA1UdHwRNMEswSaBHoEWGQ2h0dHA6Ly93d3cu

# bWljcm9zb2Z0LmNvbS9wa2lvcHMvY3JsL01pY0NvZFNpZ1BDQTIwMTFfMjAxMS0w

# Ny0wOC5jcmwwYQYIKwYBBQUHAQEEVTBTMFEGCCsGAQUFBzAChkVodHRwOi8vd3d3

# Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2NlcnRzL01pY0NvZFNpZ1BDQTIwMTFfMjAx

# MS0wNy0wOC5jcnQwDAYDVR0TAQH/BAIwADANBgkqhkiG9w0BAQsFAAOCAgEAeA8D

# sOAHS53MTIHYu8bbXrO6yQtRD6JfyMWeXaLu3Nc8PDnFc1efYq/F3MGx/aiwNbcs

# J2MU7BKNWTP5JQVBA2GNIeR3mScXqnOsv1XqXPvZeISDVWLaBQzceItdIwgo6B13

# vxlkkSYMvB0Dr3Yw7/W9U4Wk5K/RDOnIGvmKqKi3AwyxlV1mpefy729FKaWT7edB

# d3I4+hldMY8sdfDPjWRtJzjMjXZs41OUOwtHccPazjjC7KndzvZHx/0VWL8n0NT/

# 404vftnXKifMZkS4p2sB3oK+6kCcsyWsgS/3eYGw1Fe4MOnin1RhgrW1rHPODJTG

# AUOmW4wc3Q6KKr2zve7sMDZe9tfylonPwhk971rX8qGw6LkrGFv31IJeJSe/aUbG

# dUDPkbrABbVvPElgoj5eP3REqx5jdfkQw7tOdWkhn0jDUh2uQen9Atj3RkJyHuR0

# GUsJVMWFJdkIO/gFwzoOGlHNsmxvpANV86/1qgb1oZXdrURpzJp53MsDaBY/pxOc

# J0Cvg6uWs3kQWgKk5aBzvsX95BzdItHTpVMtVPW4q41XEvbFmUP1n6oL5rdNdrTM

# j/HXMRk1KCksax1Vxo3qv+13cCsZAaQNaIAvt5LvkshZkDZIP//0Hnq7NnWeYR3z

# 4oFiw9N2n3bb9baQWuWPswG0Dq9YT9kb+Cs4qIIwggd6MIIFYqADAgECAgphDpDS

# AAAAAAADMA0GCSqGSIb3DQEBCwUAMIGIMQswCQYDVQQGEwJVUzETMBEGA1UECBMK

# V2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0

# IENvcnBvcmF0aW9uMTIwMAYDVQQDEylNaWNyb3NvZnQgUm9vdCBDZXJ0aWZpY2F0

# ZSBBdXRob3JpdHkgMjAxMTAeFw0xMTA3MDgyMDU5MDlaFw0yNjA3MDgyMTA5MDla

# MH4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdS

# ZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMT

# H01pY3Jvc29mdCBDb2RlIFNpZ25pbmcgUENBIDIwMTEwggIiMA0GCSqGSIb3DQEB

# AQUAA4ICDwAwggIKAoICAQCr8PpyEBwurdhuqoIQTTS68rZYIZ9CGypr6VpQqrgG

# OBoESbp/wwwe3TdrxhLYC/A4wpkGsMg51QEUMULTiQ15ZId+lGAkbK+eSZzpaF7S

# 35tTsgosw6/ZqSuuegmv15ZZymAaBelmdugyUiYSL+erCFDPs0S3XdjELgN1q2jz

# y23zOlyhFvRGuuA4ZKxuZDV4pqBjDy3TQJP4494HDdVceaVJKecNvqATd76UPe/7

# 4ytaEB9NViiienLgEjq3SV7Y7e1DkYPZe7J7hhvZPrGMXeiJT4Qa8qEvWeSQOy2u

# M1jFtz7+MtOzAz2xsq+SOH7SnYAs9U5WkSE1JcM5bmR/U7qcD60ZI4TL9LoDho33

# X/DQUr+MlIe8wCF0JV8YKLbMJyg4JZg5SjbPfLGSrhwjp6lm7GEfauEoSZ1fiOIl

# XdMhSz5SxLVXPyQD8NF6Wy/VI+NwXQ9RRnez+ADhvKwCgl/bwBWzvRvUVUvnOaEP

# 6SNJvBi4RHxF5MHDcnrgcuck379GmcXvwhxX24ON7E1JMKerjt/sW5+v/N2wZuLB

# l4F77dbtS+dJKacTKKanfWeA5opieF+yL4TXV5xcv3coKPHtbcMojyyPQDdPweGF

# RInECUzF1KVDL3SV9274eCBYLBNdYJWaPk8zhNqwiBfenk70lrC8RqBsmNLg1oiM

# CwIDAQABo4IB7TCCAekwEAYJKwYBBAGCNxUBBAMCAQAwHQYDVR0OBBYEFEhuZOVQ

# BdOCqhc3NyK1bajKdQKVMBkGCSsGAQQBgjcUAgQMHgoAUwB1AGIAQwBBMAsGA1Ud

# DwQEAwIBhjAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFHItOgIxkEO5FAVO

# 4eqnxzHRI4k0MFoGA1UdHwRTMFEwT6BNoEuGSWh0dHA6Ly9jcmwubWljcm9zb2Z0

# LmNvbS9wa2kvY3JsL3Byb2R1Y3RzL01pY1Jvb0NlckF1dDIwMTFfMjAxMV8wM18y

# Mi5jcmwwXgYIKwYBBQUHAQEEUjBQME4GCCsGAQUFBzAChkJodHRwOi8vd3d3Lm1p

# Y3Jvc29mdC5jb20vcGtpL2NlcnRzL01pY1Jvb0NlckF1dDIwMTFfMjAxMV8wM18y

# Mi5jcnQwgZ8GA1UdIASBlzCBlDCBkQYJKwYBBAGCNy4DMIGDMD8GCCsGAQUFBwIB

# FjNodHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2RvY3MvcHJpbWFyeWNw

# cy5odG0wQAYIKwYBBQUHAgIwNB4yIB0ATABlAGcAYQBsAF8AcABvAGwAaQBjAHkA

# XwBzAHQAYQB0AGUAbQBlAG4AdAAuIB0wDQYJKoZIhvcNAQELBQADggIBAGfyhqWY

# 4FR5Gi7T2HRnIpsLlhHhY5KZQpZ90nkMkMFlXy4sPvjDctFtg/6+P+gKyju/R6mj

# 82nbY78iNaWXXWWEkH2LRlBV2AySfNIaSxzzPEKLUtCw/WvjPgcuKZvmPRul1LUd

# d5Q54ulkyUQ9eHoj8xN9ppB0g430yyYCRirCihC7pKkFDJvtaPpoLpWgKj8qa1hJ

# Yx8JaW5amJbkg/TAj/NGK978O9C9Ne9uJa7lryft0N3zDq+ZKJeYTQ49C/IIidYf

# wzIY4vDFLc5bnrRJOQrGCsLGra7lstnbFYhRRVg4MnEnGn+x9Cf43iw6IGmYslmJ

# aG5vp7d0w0AFBqYBKig+gj8TTWYLwLNN9eGPfxxvFX1Fp3blQCplo8NdUmKGwx1j

# NpeG39rz+PIWoZon4c2ll9DuXWNB41sHnIc+BncG0QaxdR8UvmFhtfDcxhsEvt9B

# xw4o7t5lL+yX9qFcltgA1qFGvVnzl6UJS0gQmYAf0AApxbGbpT9Fdx41xtKiop96

# eiL6SJUfq/tHI4D1nvi/a7dLl+LrdXga7Oo3mXkYS//WsyNodeav+vyL6wuA6mk7

# r/ww7QRMjt/fdW1jkT3RnVZOT7+AVyKheBEyIXrvQQqxP/uozKRdwaGIm1dxVk5I

# RcBCyZt2WwqASGv9eZ/BvW1taslScxMNelDNMYIZgjCCGX4CAQEwgZUwfjELMAkG

# A1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQx

# HjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEoMCYGA1UEAxMfTWljcm9z

# b2Z0IENvZGUgU2lnbmluZyBQQ0EgMjAxMQITMwAAAsyOtZamvdHJTgAAAAACzDAN

# BglghkgBZQMEAgEFAKCBrjAZBgkqhkiG9w0BCQMxDAYKKwYBBAGCNwIBBDAcBgor

# BgEEAYI3AgELMQ4wDAYKKwYBBAGCNwIBFTAvBgkqhkiG9w0BCQQxIgQgN7KsenhC

# 4BMxSyXGj/eynbSTbo3E7r1ytyEP64AmZjcwQgYKKwYBBAGCNwIBDDE0MDKgFIAS

# AE0AaQBjAHIAbwBzAG8AZgB0oRqAGGh0dHA6Ly93d3cubWljcm9zb2Z0LmNvbTAN

# BgkqhkiG9w0BAQEFAASCAQB0wd0BZCUz3A/HxA1QTAX22RgK25VyIAQFX750RAdx

# zcJP76v33yaR3p+66gPILA23rdRRjOVaawsSlGvYHCqgu2NTyyCTxHevXoyy3FQ9

# d2BWD1wHjycN+2EU7kgpWwZQ9P8QDTEspmAkZjZxX6jlnpC0HsXkDd1uoGjpt22w

# YTrz8QqI1tkiCPaRJOORX0TiALDGuL0FkoeFIPkahiBL0LlkVpgVv0HDWu+J67dw

# 4qta1KdjWJD4h8B430rssfkKOALbqEdTncZRDzt0CHJUaf/4A7us/gVPLmBa8Jey

# jDFWPhhAeaznPdB3OFAdDt2Fy8BtXmm8UsGPD76KAvmvoYIXDDCCFwgGCisGAQQB

# gjcDAwExghb4MIIW9AYJKoZIhvcNAQcCoIIW5TCCFuECAQMxDzANBglghkgBZQME

# AgEFADCCAVUGCyqGSIb3DQEJEAEEoIIBRASCAUAwggE8AgEBBgorBgEEAYRZCgMB

# MDEwDQYJYIZIAWUDBAIBBQAEIEbkFl2jSYfGiECuGGBpL9cDlDGfpzDkIqwkz9Su

# a8c9AgZjKgmNLjwYEzIwMjIwOTI2MjIwMTAwLjIxMVowBIACAfSggdSkgdEwgc4x

# CzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRt

# b25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKTAnBgNVBAsTIE1p

# Y3Jvc29mdCBPcGVyYXRpb25zIFB1ZXJ0byBSaWNvMSYwJAYDVQQLEx1UaGFsZXMg

# VFNTIEVTTjozMkJELUUzRDUtM0IxRDElMCMGA1UEAxMcTWljcm9zb2Z0IFRpbWUt

# U3RhbXAgU2VydmljZaCCEV8wggcQMIIE+KADAgECAhMzAAABrfzfTVjjXTLpAAEA

# AAGtMA0GCSqGSIb3DQEBCwUAMHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNo

# aW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29y

# cG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEw

# MB4XDTIyMDMwMjE4NTEzNloXDTIzMDUxMTE4NTEzNlowgc4xCzAJBgNVBAYTAlVT

# MRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQK

# ExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKTAnBgNVBAsTIE1pY3Jvc29mdCBPcGVy

# YXRpb25zIFB1ZXJ0byBSaWNvMSYwJAYDVQQLEx1UaGFsZXMgVFNTIEVTTjozMkJE

# LUUzRDUtM0IxRDElMCMGA1UEAxMcTWljcm9zb2Z0IFRpbWUtU3RhbXAgU2Vydmlj

# ZTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAOieUyqlTSrVLhvY7TO8

# vgC+T5N/y/MXeR3oNwE0rLI1Eg/gM5g9NhP+KqqJc/7uPL4TsoALb+RVf6roYNll

# yQrYmquUjwsq262MD5L9l9rU1plz2tMPehP8addVlNIjYIBh0NC4CyME6txVppQr

# 7eFd/bW0X9tnZy1aDW+zoaJB2FY8haokq5cRONEW4uoVsTTXsICkbYOAYffIIGak

# MFXVvB30NcsuiDn6uDk83XXTs0tnSr8FxzPoD8SgPPIcWaWPEjCQLr5I0BxfdUli

# wNPHIPEglqosrClRjXG7rcZWbWeODgATi0i6DUsv1Wn0LOW4svK4/Wuc/v9dlmuI

# ramv9whbgCykUuYZy8MxTzsQqU2Rxcm8h89CXA5jf1k7k3ZiaLUJ003MjtTtNXzl

# gb+k1A5eL17G3C4Ejw5AoViM+UBGQvxuTxpFeaGoQFqeOGGtEK0qk0wdUX9p/4Au

# 9Xsle5D5fvypBdscXBslUBcT6+CYq0kQ9smsTyhV4DK9wb9Zn7ObEOfT0AQyppI6

# jwzBjHhAGFyrKYjIbglMaEixjRv7XdNic2VuYKyS71A0hs6dbbDx/V7hDbdv2srt

# Z2VTO0y2E+4QqMRKtABv4AggjYKz5TYGuQ4VbbPY8fBO9Xqva3Gnx1ZDOQ3nGVFK

# HwarGDcNdB3qesvtJbIGJgJjAgMBAAGjggE2MIIBMjAdBgNVHQ4EFgQUfVB0HQS8

# qiFabmqEqOV9LrLGwVkwHwYDVR0jBBgwFoAUn6cVXQBeYl2D9OXSZacbUzUZ6XIw

# XwYDVR0fBFgwVjBUoFKgUIZOaHR0cDovL3d3dy5taWNyb3NvZnQuY29tL3BraW9w

# cy9jcmwvTWljcm9zb2Z0JTIwVGltZS1TdGFtcCUyMFBDQSUyMDIwMTAoMSkuY3Js

# MGwGCCsGAQUFBwEBBGAwXjBcBggrBgEFBQcwAoZQaHR0cDovL3d3dy5taWNyb3Nv

# ZnQuY29tL3BraW9wcy9jZXJ0cy9NaWNyb3NvZnQlMjBUaW1lLVN0YW1wJTIwUENB

# JTIwMjAxMCgxKS5jcnQwDAYDVR0TAQH/BAIwADATBgNVHSUEDDAKBggrBgEFBQcD

# CDANBgkqhkiG9w0BAQsFAAOCAgEAi9AdRbsx/gOSdBXndwRejQuutQqce3k3bgs1

# slPjZSx6FDXp1IZzjOyT1Jo/3eUWDBFJdi+Heu1NoyDdGn9vL6rxly1L68K4MnfL

# Bm+ybyjN+xa1eNa4+4cOoOuxE2Kt8jtmZbIhx2jvY7F9qY/lanR5PSbUKyClhNQh

# xsnNUp/JSQ+o7nAuQJ+wsCwPCrXYE7C+TvKDja6e6WU0K4RiBXFGU1z6Mt3K9wlM

# D/QGU4+/IGZDmE+/Z/k0JfJjZyxCAlcmhe3rgdhDzAsGxJYq4PblGZTBdr8wkQwp

# P2jggyMMawMM5DggwvXaDbrqCQ8gksNhCZzTqfS2dbgLF0m7HfwlUMrcnzi/bdTS

# RWzIXg5QsH1t5XaaIH+TZ1uZBtwXJ8EOXr6S+2A6q8RQVY10KnBH6YpGE9OhXPfu

# Iu882muFEdh4EXbPdARUR1IMSIxg88khSBC/YBwQhCpjTksq5J3Z+jyHWZ4MnXX5

# R42mAR584iRYc7agYvuotDEqcD0U9lIjgW31PqfqZQ1tuYZTiGcKE9QcYGvZFKnV

# dkqK8V0M9e+kF5CqDOrMMYRV2+I/FhyQsJHxK/G53D0O5bvdIh2gDnEHRAFihdZj

# 29Z7W0paGPotGX0oB5r9wqNjM3rbvuEe6FJ323MPY1x9/N1g126T/SokqADJBTKq

# yBYN4zMwggdxMIIFWaADAgECAhMzAAAAFcXna54Cm0mZAAAAAAAVMA0GCSqGSIb3

# DQEBCwUAMIGIMQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4G

# A1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMTIw

# MAYDVQQDEylNaWNyb3NvZnQgUm9vdCBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkgMjAx

# MDAeFw0yMTA5MzAxODIyMjVaFw0zMDA5MzAxODMyMjVaMHwxCzAJBgNVBAYTAlVT

# MRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQK

# ExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1l

# LVN0YW1wIFBDQSAyMDEwMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA

# 5OGmTOe0ciELeaLL1yR5vQ7VgtP97pwHB9KpbE51yMo1V/YBf2xK4OK9uT4XYDP/

# XE/HZveVU3Fa4n5KWv64NmeFRiMMtY0Tz3cywBAY6GB9alKDRLemjkZrBxTzxXb1

# hlDcwUTIcVxRMTegCjhuje3XD9gmU3w5YQJ6xKr9cmmvHaus9ja+NSZk2pg7uhp7

# M62AW36MEBydUv626GIl3GoPz130/o5Tz9bshVZN7928jaTjkY+yOSxRnOlwaQ3K

# Ni1wjjHINSi947SHJMPgyY9+tVSP3PoFVZhtaDuaRr3tpK56KTesy+uDRedGbsoy

# 1cCGMFxPLOJiss254o2I5JasAUq7vnGpF1tnYN74kpEeHT39IM9zfUGaRnXNxF80

# 3RKJ1v2lIH1+/NmeRd+2ci/bfV+AutuqfjbsNkz2K26oElHovwUDo9Fzpk03dJQc

# NIIP8BDyt0cY7afomXw/TNuvXsLz1dhzPUNOwTM5TI4CvEJoLhDqhFFG4tG9ahha

# YQFzymeiXtcodgLiMxhy16cg8ML6EgrXY28MyTZki1ugpoMhXV8wdJGUlNi5UPkL

# iWHzNgY1GIRH29wb0f2y1BzFa/ZcUlFdEtsluq9QBXpsxREdcu+N+VLEhReTwDwV

# 2xo3xwgVGD94q0W29R6HXtqPnhZyacaue7e3PmriLq0CAwEAAaOCAd0wggHZMBIG

# CSsGAQQBgjcVAQQFAgMBAAEwIwYJKwYBBAGCNxUCBBYEFCqnUv5kxJq+gpE8RjUp

# zxD/LwTuMB0GA1UdDgQWBBSfpxVdAF5iXYP05dJlpxtTNRnpcjBcBgNVHSAEVTBT

# MFEGDCsGAQQBgjdMg30BATBBMD8GCCsGAQUFBwIBFjNodHRwOi8vd3d3Lm1pY3Jv

# c29mdC5jb20vcGtpb3BzL0RvY3MvUmVwb3NpdG9yeS5odG0wEwYDVR0lBAwwCgYI

# KwYBBQUHAwgwGQYJKwYBBAGCNxQCBAweCgBTAHUAYgBDAEEwCwYDVR0PBAQDAgGG

# MA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAU1fZWy4/oolxiaNE9lJBb186a

# GMQwVgYDVR0fBE8wTTBLoEmgR4ZFaHR0cDovL2NybC5taWNyb3NvZnQuY29tL3Br

# aS9jcmwvcHJvZHVjdHMvTWljUm9vQ2VyQXV0XzIwMTAtMDYtMjMuY3JsMFoGCCsG

# AQUFBwEBBE4wTDBKBggrBgEFBQcwAoY+aHR0cDovL3d3dy5taWNyb3NvZnQuY29t

# L3BraS9jZXJ0cy9NaWNSb29DZXJBdXRfMjAxMC0wNi0yMy5jcnQwDQYJKoZIhvcN

# AQELBQADggIBAJ1VffwqreEsH2cBMSRb4Z5yS/ypb+pcFLY+TkdkeLEGk5c9MTO1

# OdfCcTY/2mRsfNB1OW27DzHkwo/7bNGhlBgi7ulmZzpTTd2YurYeeNg2LpypglYA

# A7AFvonoaeC6Ce5732pvvinLbtg/SHUB2RjebYIM9W0jVOR4U3UkV7ndn/OOPcbz

# aN9l9qRWqveVtihVJ9AkvUCgvxm2EhIRXT0n4ECWOKz3+SmJw7wXsFSFQrP8DJ6L

# GYnn8AtqgcKBGUIZUnWKNsIdw2FzLixre24/LAl4FOmRsqlb30mjdAy87JGA0j3m

# Sj5mO0+7hvoyGtmW9I/2kQH2zsZ0/fZMcm8Qq3UwxTSwethQ/gpY3UA8x1RtnWN0

# SCyxTkctwRQEcb9k+SS+c23Kjgm9swFXSVRk2XPXfx5bRAGOWhmRaw2fpCjcZxko

# JLo4S5pu+yFUa2pFEUep8beuyOiJXk+d0tBMdrVXVAmxaQFEfnyhYWxz/gq77EFm

# PWn9y8FBSX5+k77L+DvktxW/tM4+pTFRhLy/AsGConsXHRWJjXD+57XQKBqJC482

# 2rpM+Zv/Cuk0+CQ1ZyvgDbjmjJnW4SLq8CdCPSWU5nR0W2rRnj7tfqAxM328y+l7

# vzhwRNGQ8cirOoo6CGJ/2XBjU02N7oJtpQUQwXEGahC0HVUzWLOhcGbyoYIC0jCC

# AjsCAQEwgfyhgdSkgdEwgc4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5n

# dG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9y

# YXRpb24xKTAnBgNVBAsTIE1pY3Jvc29mdCBPcGVyYXRpb25zIFB1ZXJ0byBSaWNv

# MSYwJAYDVQQLEx1UaGFsZXMgVFNTIEVTTjozMkJELUUzRDUtM0IxRDElMCMGA1UE

# AxMcTWljcm9zb2Z0IFRpbWUtU3RhbXAgU2VydmljZaIjCgEBMAcGBSsOAwIaAxUA

# QJLRrUVR4ZbBDgWPjuNqVctUzpCggYMwgYCkfjB8MQswCQYDVQQGEwJVUzETMBEG

# A1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWlj

# cm9zb2Z0IENvcnBvcmF0aW9uMSYwJAYDVQQDEx1NaWNyb3NvZnQgVGltZS1TdGFt

# cCBQQ0EgMjAxMDANBgkqhkiG9w0BAQUFAAIFAObccN8wIhgPMjAyMjA5MjYyMjQx

# MzVaGA8yMDIyMDkyNzIyNDEzNVowdzA9BgorBgEEAYRZCgQBMS8wLTAKAgUA5txw

# 3wIBADAKAgEAAgIYywIB/zAHAgEAAgIRUTAKAgUA5t3CXwIBADA2BgorBgEEAYRZ

# CgQCMSgwJjAMBgorBgEEAYRZCgMCoAowCAIBAAIDB6EgoQowCAIBAAIDAYagMA0G

# CSqGSIb3DQEBBQUAA4GBAH/moP55GkLWYTbpteCe7t3M7HokpeGPdnursDv8HuLv

# +yudIvIOEVFQz4tIkfdwyz0ywIdHKmi88U75pmjtE9YSwwLtWTf/zvhF3MxzIAAo

# oEdaOIPQKaQywGaCpukC1ZyIXFziutSqaTzODAdKWQD0Flav7nUFJIpawMrByu7+

# MYIEDTCCBAkCAQEwgZMwfDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0

# b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3Jh

# dGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENBIDIwMTACEzMA

# AAGt/N9NWONdMukAAQAAAa0wDQYJYIZIAWUDBAIBBQCgggFKMBoGCSqGSIb3DQEJ

# AzENBgsqhkiG9w0BCRABBDAvBgkqhkiG9w0BCQQxIgQg0ThFfWHVnO0VyeM6zsvi

# R+4EedjhyahToHXINIsCft8wgfoGCyqGSIb3DQEJEAIvMYHqMIHnMIHkMIG9BCCf

# 6nw9CR5e1+Ottcn1w992Kmn8YMTY/DWPIHeMbMtQgjCBmDCBgKR+MHwxCzAJBgNV

# BAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4w

# HAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29m

# dCBUaW1lLVN0YW1wIFBDQSAyMDEwAhMzAAABrfzfTVjjXTLpAAEAAAGtMCIEIFvp

# AUbEuK3/8i1wVN77PwRRCqGZ/Qoo9fCM5ExNqdJnMA0GCSqGSIb3DQEBCwUABIIC

# AErjA3w37cCrW12JUstnIQmhc4EyNXL2rVrLioHgTFSEtuKqGLfhAr6nq+9VooFp

# wtE6V5DrLQ5zYL/+c1H+b2QwrjZBa7JoY+YkoPFF9U9lYLO0Yrr23LAM7xjmGG18

# 7dRvdWP9ZTKod77SA5fQX2XBahMU+cTyh5vue218+V8tHnaNVHLZj623nu/q9zE2

# BMkcq17mlTy/9s9zRA4/mITTTkvRLkLpOmYEsayhaHJpRhfKC1sieWC7+pmF52H5

# 1XaFBnO9PVmvnGCIvuFJQcVqoTprLJMmqf94G16qs4b0uPxvGJJfTW8xBO8bRx6r

# yLc4IhDJmUW6e2039mVshsFKBW/4wtI7g0wjJ8KSIjIbpjFhkJDRCwamHoyejYPZ

# O9GeuhTLrm3po/IhHQqTc2YQDaJu3NwE7gskS20NILwGxtHWypShOKtNtKdsk2Zk

# mwkWiFRQZ4slCerfU8jjVDY6qrYkEWNQ8I07JAsNKZADyQ7PHFFqHAcBHzzrbBe6

# NiFOIiUU0FHB5aepbKuq8+SJWurzihqbN11FxUMcmPjduQQfCk8PWhcMKZcEvRiR

# 085dMsLYo8Bprgqbl0VpLZLiXYE4pkpT72uRTJPP9PKbrkPSj4mBMMyDE6MgNCco

# ZLtzllJ/NnczzHEm2sWt8y4lStEtHs/eKXbeYQHMe8sT

# SIG # End signature block