AadAuthenticationFactory

1.2.3

AadAuthenticationFactory.psm1

                                function New-AadAuthenticationFactory

{

    <#

.SYNOPSIS

    Creates authentication factory with provided parameters for Public or Confidential client flows

.DESCRIPTION

    Creates authentication factory with provided parameters for Public or Confidential client flows

    Authentication uses by default well-know clientId of Azure Powershell, but can accept clientId of app registered in your own tenant.

.OUTPUTS

    AadAuthenticationFactory object

.EXAMPLE

New-AadAuthenticationFactory -TenantId mydomain.com -RequiredScopes @('https://my-db.documents.azure.com/.default') -AuthMode Interactive

Description

-----------

This command returns AAD authentication factory for Public client auth flow with well-known clientId for Azure PowerShell and interactive authentication for getting tokens for CosmosDB account

.EXAMPLE

$proxy=new-object System.Net.WebProxy('http://myproxy.mycompany.com:8080')

$proxy.BypassProxyOnLocal=$true

$factory = New-AadAuthenticationFactory -TenantId mydomain.com  -RequiredScopes @('https://eventgrid.azure.net/.default') -AuthMode deviceCode -Proxy $proxy

$token = $factory | Get-AadToken

Description

-----------

Command works in on prem environment where access to internet is available via proxy. Command authenticates user with device code flow.

#>

    param

    (

        [Parameter(Mandatory)]

        [string[]]

            #Scopes to ask token for

        $RequiredScopes,

        [Parameter(Mandatory,ParameterSetName = 'ConfidentialClientWithSecret')]

        [Parameter(Mandatory,ParameterSetName = 'ConfidentialClientWithCertificate')]

        [Parameter(Mandatory,ParameterSetName = 'PublicClient')]

        [Parameter(Mandatory,ParameterSetName = 'ResourceOwnerPasssword')]

        [string]

            #Id of tenant where to autenticate the user. Can be tenant id, or any registerd DNS domain

        $TenantId,

        [Parameter()]

        [string]

            #ClientId of application that gets token

            #Default: well-known clientId for Azure PowerShell

        $ClientId,

        [Parameter(ParameterSetName = 'ConfidentialClientWithSecret')]

        [string]

            #Client secret for ClientID

            #Used to get access as application rather than as calling user

        $ClientSecret,

        [Parameter(ParameterSetName = 'ResourceOwnerPasssword')]

        [pscredential]

            #Resource Owner username and password

            #Used to get access as user

            #Note: Does not work for federated authentication

        $ResourceOwnerCredential,

        [Parameter(ParameterSetName = 'ConfidentialClientWithCertificate')]

        [System.Security.Cryptography.X509Certificates.X509Certificate2]

            #Authentication certificate for ClientID

            #Used to get access as application rather than as calling user

        $X509Certificate,

        [Parameter(ParameterSetName = 'ConfidentialClientWithSecret')]

        [Parameter(ParameterSetName = 'ConfidentialClientWithCertificate')]

        [Parameter(ParameterSetName = 'PublicClient')]

        [Parameter(ParameterSetName = 'ResourceOwnerPasssword')]

        [string]

            #AAD auth endpoint

            #Default: endpoint for public cloud

        $LoginApi = 'https://login.microsoftonline.com',

        [Parameter(Mandatory, ParameterSetName = 'PublicClient')]

        [ValidateSet('Interactive', 'DeviceCode', 'WIA')]

        [string]

            #How to authenticate client - via web view, via device code flow, or via Windows Integrated Auth

            #Used in public client flows

        $AuthMode,

        [Parameter(ParameterSetName = 'PublicClient')]

        [string]

            #Username hint for authentication UI

            #Optional

        $UserNameHint,

        [Parameter(ParameterSetName = 'MSI')]

        [Switch]

            #tries to get parameters from environment and token from internal endpoint provided by Azure MSI support

        $UseManagedIdentity,

        [Parameter()]

        [System.Net.WebProxy]

            #Web proxy configuration

            #Optional

        $proxy = $null

    )

    process

    {

        switch($PSCmdlet.ParameterSetName)

        {

            'ConfidentialClientWithSecret' {

                $script:AadLastCreatedFactory = new-object GreyCorbel.Identity.Authentication.AadAuthenticationFactory($tenantId, $ClientId, $clientSecret, $RequiredScopes, $LoginApi,$proxy)

                break;

            }

            'ConfidentialClientWithCertificate' {

                $script:AadLastCreatedFactory = new-object GreyCorbel.Identity.Authentication.AadAuthenticationFactory($tenantId, $ClientId, $X509Certificate, $RequiredScopes, $LoginApi,$proxy)

                break;

            }

            'PublicClient' {

                $script:AadLastCreatedFactory = new-object GreyCorbel.Identity.Authentication.AadAuthenticationFactory($tenantId, $ClientId, $RequiredScopes, $LoginApi, $AuthMode, $UserNameHint,$proxy)

                break;

            }

            'MSI' {

                $script:AadLastCreatedFactory = new-object GreyCorbel.Identity.Authentication.AadAuthenticationFactory($ClientId, $RequiredScopes,$proxy)

                break;

            }

            'ResourceOwnerPasssword' {

                $script:AadLastCreatedFactory = new-object GreyCorbel.Identity.Authentication.AadAuthenticationFactory($tenantId, $ClientId, $RequiredScopes, $ResourceOwnerCredential.UserName, $ResourceOwnerCredential.Password, $LoginApi,$proxy)

                break;

            }

        }

        $script:AadLastCreatedFactory

    }

}

function Get-AadToken

{

    <#

.SYNOPSIS

    Retrieves AAD token according to configuration of authentication factory

.DESCRIPTION

    Retrieves AAD token according to configuration of authentication factory

.OUTPUTS

    Authentication result from AAD with tokens and other information

.EXAMPLE

$factory = New-AadAuthenticationFactory -TenantId mydomain.com  -RequiredScopes @('https://eventgrid.azure.net/.default') -AuthMode Interactive

$token = $factory | Get-AadToken

Description

-----------

Command creates authentication factory and retrieves AAD token from it, authenticating user via web view or browser

.EXAMPLE

$cosmosDbAccountName = 'myCosmosDBAcct

$factory = New-AadAuthenticationFactory -RequiredScopes @("https://$cosmosDbAccountName`.documents.azure.com/.default") -UseManagedIdentity

$token = $factory | Get-AadToken

Description

-----------

Command creates authentication factory and retrieves AAD token for access data plane of cosmos DB aaccount.

For deatils on CosmosDB RBAC access, see https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-setup-rbac

.EXAMPLE

$factory = New-AadAuthenticationFactory -TenantId mydomain.com  -RequiredScopes @('https://eventgrid.azure.net/.default') -AuthMode WIA

$token = $factory | Get-AadToken

.EXAMPLE

New-AadAuthenticationFactory -TenantId mydomain.com  -RequiredScopes @('api://mycompany.com/mypai/.default') -AuthMode WIA

$headers = Get-AadToken -AsHashtable

invoke-RestMethod -Uri "https://myapi.mycomany.com/items" -Headers $headers 

Description

-----------

Command shows how to get token as hashtable containing properly formatted Authorization header and use it to authenticate call of REST method

#>

    param

    (

        [Parameter(ValueFromPipeline)]

        [GreyCorbel.Identity.Authentication.AadAuthenticationFactory]

            #AAD authentication factory created via New-AadAuthenticationFactory

        $Factory = $script:AadLastCreatedFactory,

        [Parameter()]

            #Scopes to be returned in the token.

            #If not specified, returns scopes provided when creating the factory

        [string[]]$Scopes = $null,

            #If set, command returns hashtable with Authorization header containing acess token

        [Parameter()]

            #access token for user

            #used to identify for in on-behalf-of flows

        [string]$UserToken,

            #when specified, hashtable with Authorization header is returned instead of token

            #this is shortcut to use when just need to have token for authorization header to call REST API (e.g. via Invoke-RestMethod)

        [switch]$AsHashTable

    )

    process

    {

        try {

            #I don't know how to support Ctrl+Break

            if(-not [string]::IsNullOrEmpty($UserToken))

            {

                $task = $factory.AuthenticateAsync($UserToken, $scopes)

            }

            else

            {

                $task = $factory.AuthenticateAsync($scopes)

            }

            $result = $task.GetAwaiter().GetResult()

            if($AsHashTable)

            {

                @{

                    Authorization = $result.CreateAuthorizationHeader()

                }

            }

            else {

                $result

            }

        }

        catch [System.OperationCanceledException] {

            Write-Verbose "Authentication process has been cancelled"

        }

    }

}

function Test-AadToken

{

    <#

.SYNOPSIS

    Parses and validates AAD issues token

.DESCRIPTION

    Parses provided IdToken or AccessToken and checks for its validity.

    Note that some tokens may not be properly validated - this is in case then 'nonce' field present and set in the haeder. AAD issues such tokens for Graph API and nonce is taken into consideration when validating the token.

    See discussing at https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/issues/609 for more details.

.OUTPUTS

    Parsed token and information about its validity

.EXAMPLE

$factory = New-AadAuthenticationFactory -TenantId mydomain.com  -RequiredScopes @('https://eventgrid.azure.net/.default') -AuthMode Interactive

$token = $factory | Get-AadToken

$token.idToken | Test-AadToken | fl

Description

-----------

Command creates authentication factory, asks it to issue token for EventGrid and parses IdToken and validates it

#>

[CmdletBinding()]

    param (

        [Parameter(Mandatory,ValueFromPipeline)]

        [string]

        #IdToken or AccessToken field from token returned by Get-AadToken

        $Token

    )

    process

    {

        $parts = $token.split('.')

        if($parts.Length -ne 3)

        {

            throw 'Invalid format of provided token'

        }

        $result = [PSCustomObject]@{

            Header = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String((Base64UrlDecode -Data $parts[0]))) | ConvertFrom-Json

            Payload = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String((Base64UrlDecode -Data $parts[1]))) | ConvertFrom-Json

            IsValid = $false

        }

        #validate the result using published keys

        $endpoint = $result.Payload.iss.Replace('/v2.0','/')

        $signingKeys = Invoke-RestMethod -Method Get -Uri "$($endpoint)discovery/keys"

        $key = $signingKeys.keys | Where-object{$_.kid -eq $result.Header.kid}

        if($null -eq $key)

        {

            throw "Could not find signing key with id = $($result.Header.kid)"

        }

        $cert = new-object System.Security.Cryptography.X509Certificates.X509Certificate2(,[Convert]::FromBase64String($key.x5c[0]))

        $rsa = $cert.PublicKey.Key

        $payload = "$($parts[0]).$($parts[1])"

        $dataToVerify = [System.Text.Encoding]::UTF8.GetBytes($payload)

        $sig = Base64UrlDecode -Data $parts[2]

        $signature = [Convert]::FromBase64String($sig)

        switch($result.Header.alg)

        {

            'RS384' {

                $hash = [System.Security.Cryptography.HashAlgorithmName]::SHA384

                break;

            }

            'RS512' {

                $hash = [System.Security.Cryptography.HashAlgorithmName]::SHA512

                break;

            }

            default {

                $hash = [System.Security.Cryptography.HashAlgorithmName]::SHA256

                break;

            }

        }

        $padding = [System.Security.Cryptography.RSASignaturePadding]::Pkcs1

        $result.IsValid = $rsa.VerifyData($dataToVerify,$signature,$hash,$Padding)

        $cert.Dispose()

        if($null -ne $result.Header.nonce)

        {

            Write-Verbose "Header contains nonce, so token may not be properly validated. See https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/issues/609"

        }

        $result.psobject.typenames.Insert(0,'GreyCorbel.Identity.Authentication.TokenValidationResult')

        $result

    }

}

#region Internals

function Base64UrlDecode

{

    param

    (

        [Parameter(Mandatory,ValueFromPipeline)]

        [string]$Data

    )

    process

    {

        $result = $Data

        $result = $result.Replace('-','+').Replace('_','/')

        switch($result.Length % 4)

        {

            0 {break;}

            2 {$result = "$result=="; break}

            3 {$result = "$result="; break;}

            default {throw "Invalid data format"}

        }

        $result

    }

}

function Init

{

    param()

    process

    {

        switch($PSEdition)

        {

            'Core'

            {

                #only load when not present

                try {

                    [Microsoft.Identity.Client.PublicClientApplication] | Out-Null

                }

                catch

                {

                    Add-type -Path "$PSScriptRoot\Shared\netcoreapp2.1\Microsoft.Identity.Client.dll"

                }

                break;

            }

            'Desktop'

            {

                #only load when not present

                try {

                    [Microsoft.Identity.Client.PublicClientApplication] | Out-Null

                }

                catch

                {

                    Add-Type -Path "$PSScriptRoot\Shared\net461\Microsoft.Identity.Client.dll"

                }

                Add-Type -Assembly System.Net.Http

                break;

            }

        }

        #only load when not present

        try {

            [GreyCorbel.Identity.Authentication.AadAuthenticationFactory] | Out-Null

        }

        catch

        {

            Add-Type -Path "$PSScriptRoot\Shared\netstandard2.0\GreyCorbel.Identity.Authentication.dll"

        }

        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

    }

}

#endregion

Init

# SIG # Begin signature block

# MIInDQYJKoZIhvcNAQcCoIIm/jCCJvoCAQExDzANBglghkgBZQMEAgEFADB5Bgor

# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG

# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCCg/IbgYAkUB5+D

# qTX9cK1SZtIE2XcdmTqiVItOKmrt8qCCIJAwggWNMIIEdaADAgECAhAOmxiO+dAt

# 5+/bUOIIQBhaMA0GCSqGSIb3DQEBDAUAMGUxCzAJBgNVBAYTAlVTMRUwEwYDVQQK

# EwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xJDAiBgNV

# BAMTG0RpZ2lDZXJ0IEFzc3VyZWQgSUQgUm9vdCBDQTAeFw0yMjA4MDEwMDAwMDBa

# Fw0zMTExMDkyMzU5NTlaMGIxCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2Vy

# dCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xITAfBgNVBAMTGERpZ2lD

# ZXJ0IFRydXN0ZWQgUm9vdCBHNDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC

# ggIBAL/mkHNo3rvkXUo8MCIwaTPswqclLskhPfKK2FnC4SmnPVirdprNrnsbhA3E

# MB/zG6Q4FutWxpdtHauyefLKEdLkX9YFPFIPUh/GnhWlfr6fqVcWWVVyr2iTcMKy

# unWZanMylNEQRBAu34LzB4TmdDttceItDBvuINXJIB1jKS3O7F5OyJP4IWGbNOsF

# xl7sWxq868nPzaw0QF+xembud8hIqGZXV59UWI4MK7dPpzDZVu7Ke13jrclPXuU1

# 5zHL2pNe3I6PgNq2kZhAkHnDeMe2scS1ahg4AxCN2NQ3pC4FfYj1gj4QkXCrVYJB

# MtfbBHMqbpEBfCFM1LyuGwN1XXhm2ToxRJozQL8I11pJpMLmqaBn3aQnvKFPObUR

# WBf3JFxGj2T3wWmIdph2PVldQnaHiZdpekjw4KISG2aadMreSx7nDmOu5tTvkpI6

# nj3cAORFJYm2mkQZK37AlLTSYW3rM9nF30sEAMx9HJXDj/chsrIRt7t/8tWMcCxB

# YKqxYxhElRp2Yn72gLD76GSmM9GJB+G9t+ZDpBi4pncB4Q+UDCEdslQpJYls5Q5S

# UUd0viastkF13nqsX40/ybzTQRESW+UQUOsxxcpyFiIJ33xMdT9j7CFfxCBRa2+x

# q4aLT8LWRV+dIPyhHsXAj6KxfgommfXkaS+YHS312amyHeUbAgMBAAGjggE6MIIB

# NjAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBTs1+OC0nFdZEzfLmc/57qYrhwP

# TzAfBgNVHSMEGDAWgBRF66Kv9JLLgjEtUYunpyGd823IDzAOBgNVHQ8BAf8EBAMC

# AYYweQYIKwYBBQUHAQEEbTBrMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC5kaWdp

# Y2VydC5jb20wQwYIKwYBBQUHMAKGN2h0dHA6Ly9jYWNlcnRzLmRpZ2ljZXJ0LmNv

# bS9EaWdpQ2VydEFzc3VyZWRJRFJvb3RDQS5jcnQwRQYDVR0fBD4wPDA6oDigNoY0

# aHR0cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0QXNzdXJlZElEUm9vdENB

# LmNybDARBgNVHSAECjAIMAYGBFUdIAAwDQYJKoZIhvcNAQEMBQADggEBAHCgv0Nc

# Vec4X6CjdBs9thbX979XB72arKGHLOyFXqkauyL4hxppVCLtpIh3bb0aFPQTSnov

# Lbc47/T/gLn4offyct4kvFIDyE7QKt76LVbP+fT3rDB6mouyXtTP0UNEm0Mh65Zy

# oUi0mcudT6cGAxN3J0TU53/oWajwvy8LpunyNDzs9wPHh6jSTEAZNUZqaVSwuKFW

# juyk1T3osdz9HNj0d1pcVIxv76FQPfx2CWiEn2/K2yCNNWAcAgPLILCsWKAOQGPF

# mCLBsln1VWvPJ6tsds5vIy30fnFqI2si/xK4VC0nftg62fC2h5b9W9FcrBjDTZ9z

# twGpn1eqXijiuZQwggauMIIElqADAgECAhAHNje3JFR82Ees/ShmKl5bMA0GCSqG

# SIb3DQEBCwUAMGIxCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMx

# GTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xITAfBgNVBAMTGERpZ2lDZXJ0IFRy

# dXN0ZWQgUm9vdCBHNDAeFw0yMjAzMjMwMDAwMDBaFw0zNzAzMjIyMzU5NTlaMGMx

# CzAJBgNVBAYTAlVTMRcwFQYDVQQKEw5EaWdpQ2VydCwgSW5jLjE7MDkGA1UEAxMy

# RGlnaUNlcnQgVHJ1c3RlZCBHNCBSU0E0MDk2IFNIQTI1NiBUaW1lU3RhbXBpbmcg

# Q0EwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDGhjUGSbPBPXJJUVXH

# JQPE8pE3qZdRodbSg9GeTKJtoLDMg/la9hGhRBVCX6SI82j6ffOciQt/nR+eDzMf

# UBMLJnOWbfhXqAJ9/UO0hNoR8XOxs+4rgISKIhjf69o9xBd/qxkrPkLcZ47qUT3w

# 1lbU5ygt69OxtXXnHwZljZQp09nsad/ZkIdGAHvbREGJ3HxqV3rwN3mfXazL6IRk

# tFLydkf3YYMZ3V+0VAshaG43IbtArF+y3kp9zvU5EmfvDqVjbOSmxR3NNg1c1eYb

# qMFkdECnwHLFuk4fsbVYTXn+149zk6wsOeKlSNbwsDETqVcplicu9Yemj052FVUm

# cJgmf6AaRyBD40NjgHt1biclkJg6OBGz9vae5jtb7IHeIhTZgirHkr+g3uM+onP6

# 5x9abJTyUpURK1h0QCirc0PO30qhHGs4xSnzyqqWc0Jon7ZGs506o9UD4L/wojzK

# QtwYSH8UNM/STKvvmz3+DrhkKvp1KCRB7UK/BZxmSVJQ9FHzNklNiyDSLFc1eSuo

# 80VgvCONWPfcYd6T/jnA+bIwpUzX6ZhKWD7TA4j+s4/TXkt2ElGTyYwMO1uKIqjB

# Jgj5FBASA31fI7tk42PgpuE+9sJ0sj8eCXbsq11GdeJgo1gJASgADoRU7s7pXche

# MBK9Rp6103a50g5rmQzSM7TNsQIDAQABo4IBXTCCAVkwEgYDVR0TAQH/BAgwBgEB

# /wIBADAdBgNVHQ4EFgQUuhbZbU2FL3MpdpovdYxqII+eyG8wHwYDVR0jBBgwFoAU

# 7NfjgtJxXWRM3y5nP+e6mK4cD08wDgYDVR0PAQH/BAQDAgGGMBMGA1UdJQQMMAoG

# CCsGAQUFBwMIMHcGCCsGAQUFBwEBBGswaTAkBggrBgEFBQcwAYYYaHR0cDovL29j

# c3AuZGlnaWNlcnQuY29tMEEGCCsGAQUFBzAChjVodHRwOi8vY2FjZXJ0cy5kaWdp

# Y2VydC5jb20vRGlnaUNlcnRUcnVzdGVkUm9vdEc0LmNydDBDBgNVHR8EPDA6MDig

# NqA0hjJodHRwOi8vY3JsMy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVzdGVkUm9v

# dEc0LmNybDAgBgNVHSAEGTAXMAgGBmeBDAEEAjALBglghkgBhv1sBwEwDQYJKoZI

# hvcNAQELBQADggIBAH1ZjsCTtm+YqUQiAX5m1tghQuGwGC4QTRPPMFPOvxj7x1Bd

# 4ksp+3CKDaopafxpwc8dB+k+YMjYC+VcW9dth/qEICU0MWfNthKWb8RQTGIdDAiC

# qBa9qVbPFXONASIlzpVpP0d3+3J0FNf/q0+KLHqrhc1DX+1gtqpPkWaeLJ7giqzl

# /Yy8ZCaHbJK9nXzQcAp876i8dU+6WvepELJd6f8oVInw1YpxdmXazPByoyP6wCeC

# RK6ZJxurJB4mwbfeKuv2nrF5mYGjVoarCkXJ38SNoOeY+/umnXKvxMfBwWpx2cYT

# gAnEtp/Nh4cku0+jSbl3ZpHxcpzpSwJSpzd+k1OsOx0ISQ+UzTl63f8lY5knLD0/

# a6fxZsNBzU+2QJshIUDQtxMkzdwdeDrknq3lNHGS1yZr5Dhzq6YBT70/O3itTK37

# xJV77QpfMzmHQXh6OOmc4d0j/R0o08f56PGYX/sr2H7yRp11LB4nLCbbbxV7HhmL

# NriT1ObyF5lZynDwN7+YAN8gFk8n+2BnFqFmut1VwDophrCYoCvtlUG3OtUVmDG0

# YgkPCr2B2RP+v6TR81fZvAT6gt4y3wSJ8ADNXcL50CN/AAvkdgIm2fBldkKmKYcJ

# RyvmfxqkhQ/8mJb2VVQrH4D6wPIOK+XW+6kvRBVK5xMOHds3OBqhK/bt1nz8MIIG

# sDCCBJigAwIBAgIQCK1AsmDSnEyfXs2pvZOu2TANBgkqhkiG9w0BAQwFADBiMQsw

# CQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3d3cu

# ZGlnaWNlcnQuY29tMSEwHwYDVQQDExhEaWdpQ2VydCBUcnVzdGVkIFJvb3QgRzQw

# HhcNMjEwNDI5MDAwMDAwWhcNMzYwNDI4MjM1OTU5WjBpMQswCQYDVQQGEwJVUzEX

# MBUGA1UEChMORGlnaUNlcnQsIEluYy4xQTA/BgNVBAMTOERpZ2lDZXJ0IFRydXN0

# ZWQgRzQgQ29kZSBTaWduaW5nIFJTQTQwOTYgU0hBMzg0IDIwMjEgQ0ExMIICIjAN

# BgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1bQvQtAorXi3XdU5WRuxiEL1M4zr

# PYGXcMW7xIUmMJ+kjmjYXPXrNCQH4UtP03hD9BfXHtr50tVnGlJPDqFX/IiZwZHM

# gQM+TXAkZLON4gh9NH1MgFcSa0OamfLFOx/y78tHWhOmTLMBICXzENOLsvsI8Irg

# nQnAZaf6mIBJNYc9URnokCF4RS6hnyzhGMIazMXuk0lwQjKP+8bqHPNlaJGiTUyC

# EUhSaN4QvRRXXegYE2XFf7JPhSxIpFaENdb5LpyqABXRN/4aBpTCfMjqGzLmysL0

# p6MDDnSlrzm2q2AS4+jWufcx4dyt5Big2MEjR0ezoQ9uo6ttmAaDG7dqZy3SvUQa

# khCBj7A7CdfHmzJawv9qYFSLScGT7eG0XOBv6yb5jNWy+TgQ5urOkfW+0/tvk2E0

# XLyTRSiDNipmKF+wc86LJiUGsoPUXPYVGUztYuBeM/Lo6OwKp7ADK5GyNnm+960I

# HnWmZcy740hQ83eRGv7bUKJGyGFYmPV8AhY8gyitOYbs1LcNU9D4R+Z1MI3sMJN2

# FKZbS110YU0/EpF23r9Yy3IQKUHw1cVtJnZoEUETWJrcJisB9IlNWdt4z4FKPkBH

# X8mBUHOFECMhWWCKZFTBzCEa6DgZfGYczXg4RTCZT/9jT0y7qg0IU0F8WD1Hs/q2

# 7IwyCQLMbDwMVhECAwEAAaOCAVkwggFVMBIGA1UdEwEB/wQIMAYBAf8CAQAwHQYD

# VR0OBBYEFGg34Ou2O/hfEYb7/mF7CIhl9E5CMB8GA1UdIwQYMBaAFOzX44LScV1k

# TN8uZz/nupiuHA9PMA4GA1UdDwEB/wQEAwIBhjATBgNVHSUEDDAKBggrBgEFBQcD

# AzB3BggrBgEFBQcBAQRrMGkwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLmRpZ2lj

# ZXJ0LmNvbTBBBggrBgEFBQcwAoY1aHR0cDovL2NhY2VydHMuZGlnaWNlcnQuY29t

# L0RpZ2lDZXJ0VHJ1c3RlZFJvb3RHNC5jcnQwQwYDVR0fBDwwOjA4oDagNIYyaHR0

# cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0VHJ1c3RlZFJvb3RHNC5jcmww

# HAYDVR0gBBUwEzAHBgVngQwBAzAIBgZngQwBBAEwDQYJKoZIhvcNAQEMBQADggIB

# ADojRD2NCHbuj7w6mdNW4AIapfhINPMstuZ0ZveUcrEAyq9sMCcTEp6QRJ9L/Z6j

# fCbVN7w6XUhtldU/SfQnuxaBRVD9nL22heB2fjdxyyL3WqqQz/WTauPrINHVUHmI

# moqKwba9oUgYftzYgBoRGRjNYZmBVvbJ43bnxOQbX0P4PpT/djk9ntSZz0rdKOtf

# JqGVWEjVGv7XJz/9kNF2ht0csGBc8w2o7uCJob054ThO2m67Np375SFTWsPK6Wrx

# oj7bQ7gzyE84FJKZ9d3OVG3ZXQIUH0AzfAPilbLCIXVzUstG2MQ0HKKlS43Nb3Y3

# LIU/Gs4m6Ri+kAewQ3+ViCCCcPDMyu/9KTVcH4k4Vfc3iosJocsL6TEa/y4ZXDlx

# 4b6cpwoG1iZnt5LmTl/eeqxJzy6kdJKt2zyknIYf48FWGysj/4+16oh7cGvmoLr9

# Oj9FpsToFpFSi0HASIRLlk2rREDjjfAVKM7t8RhWByovEMQMCGQ8M4+uKIw8y4+I

# Cw2/O/TOHnuO77Xry7fwdxPm5yg/rBKupS8ibEH5glwVZsxsDsrFhsP2JjMMB0ug

# 0wcCampAMEhLNKhRILutG4UI4lkNbcoFUCvqShyepf2gpx8GdOfy1lKQ/a+FSCH5

# Vzu0nAPthkX0tGFuv2jiJmCG6sivqf6UHedjGzqGVnhOMIIGwDCCBKigAwIBAgIQ

# DE1pckuU+jwqSj0pB4A9WjANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJVUzEX

# MBUGA1UEChMORGlnaUNlcnQsIEluYy4xOzA5BgNVBAMTMkRpZ2lDZXJ0IFRydXN0

# ZWQgRzQgUlNBNDA5NiBTSEEyNTYgVGltZVN0YW1waW5nIENBMB4XDTIyMDkyMTAw

# MDAwMFoXDTMzMTEyMTIzNTk1OVowRjELMAkGA1UEBhMCVVMxETAPBgNVBAoTCERp

# Z2lDZXJ0MSQwIgYDVQQDExtEaWdpQ2VydCBUaW1lc3RhbXAgMjAyMiAtIDIwggIi

# MA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDP7KUmOsap8mu7jcENmtuh6BSF

# dDMaJqzQHFUeHjZtvJJVDGH0nQl3PRWWCC9rZKT9BoMW15GSOBwxApb7crGXOlWv

# M+xhiummKNuQY1y9iVPgOi2Mh0KuJqTku3h4uXoW4VbGwLpkU7sqFudQSLuIaQyI

# xvG+4C99O7HKU41Agx7ny3JJKB5MgB6FVueF7fJhvKo6B332q27lZt3iXPUv7Y3U

# TZWEaOOAy2p50dIQkUYp6z4m8rSMzUy5Zsi7qlA4DeWMlF0ZWr/1e0BubxaompyV

# R4aFeT4MXmaMGgokvpyq0py2909ueMQoP6McD1AGN7oI2TWmtR7aeFgdOej4TJEQ

# ln5N4d3CraV++C0bH+wrRhijGfY59/XBT3EuiQMRoku7mL/6T+R7Nu8GRORV/zbq

# 5Xwx5/PCUsTmFntafqUlc9vAapkhLWPlWfVNL5AfJ7fSqxTlOGaHUQhr+1NDOdBk

# +lbP4PQK5hRtZHi7mP2Uw3Mh8y/CLiDXgazT8QfU4b3ZXUtuMZQpi+ZBpGWUwFjl

# 5S4pkKa3YWT62SBsGFFguqaBDwklU/G/O+mrBw5qBzliGcnWhX8T2Y15z2LF7OF7

# ucxnEweawXjtxojIsG4yeccLWYONxu71LHx7jstkifGxxLjnU15fVdJ9GSlZA076

# XepFcxyEftfO4tQ6dwIDAQABo4IBizCCAYcwDgYDVR0PAQH/BAQDAgeAMAwGA1Ud

# EwEB/wQCMAAwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwgwIAYDVR0gBBkwFzAIBgZn

# gQwBBAIwCwYJYIZIAYb9bAcBMB8GA1UdIwQYMBaAFLoW2W1NhS9zKXaaL3WMaiCP

# nshvMB0GA1UdDgQWBBRiit7QYfyPMRTtlwvNPSqUFN9SnDBaBgNVHR8EUzBRME+g

# TaBLhklodHRwOi8vY3JsMy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVzdGVkRzRS

# U0E0MDk2U0hBMjU2VGltZVN0YW1waW5nQ0EuY3JsMIGQBggrBgEFBQcBAQSBgzCB

# gDAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AuZGlnaWNlcnQuY29tMFgGCCsGAQUF

# BzAChkxodHRwOi8vY2FjZXJ0cy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVzdGVk

# RzRSU0E0MDk2U0hBMjU2VGltZVN0YW1waW5nQ0EuY3J0MA0GCSqGSIb3DQEBCwUA

# A4ICAQBVqioa80bzeFc3MPx140/WhSPx/PmVOZsl5vdyipjDd9Rk/BX7NsJJUSx4

# iGNVCUY5APxp1MqbKfujP8DJAJsTHbCYidx48s18hc1Tna9i4mFmoxQqRYdKmEIr

# UPwbtZ4IMAn65C3XCYl5+QnmiM59G7hqopvBU2AJ6KO4ndetHxy47JhB8PYOgPvk

# /9+dEKfrALpfSo8aOlK06r8JSRU1NlmaD1TSsht/fl4JrXZUinRtytIFZyt26/+Y

# siaVOBmIRBTlClmia+ciPkQh0j8cwJvtfEiy2JIMkU88ZpSvXQJT657inuTTH4YB

# ZJwAwuladHUNPeF5iL8cAZfJGSOA1zZaX5YWsWMMxkZAO85dNdRZPkOaGK7DycvD

# +5sTX2q1x+DzBcNZ3ydiK95ByVO5/zQQZ/YmMph7/lxClIGUgp2sCovGSxVK05iQ

# RWAzgOAj3vgDpPZFR+XOuANCR+hBNnF3rf2i6Jd0Ti7aHh2MWsgemtXC8MYiqE+b

# vdgcmlHEL5r2X6cnl7qWLoVXwGDneFZ/au/ClZpLEQLIgpzJGgV8unG1TnqZbPTo

# ntRamMifv427GFxD9dAq6OJi7ngE273R+1sKqHB+8JeEeOMIA11HLGOoJTiXAdI/

# Otrl5fbmm9x+LMz/F0xNAKLY1gEOuIvu5uByVYksJxlh9ncBjDCCBtEwggS5oAMC

# AQICEALJyJtCgrJIcqJKOHHEJNIwDQYJKoZIhvcNAQELBQAwaTELMAkGA1UEBhMC

# VVMxFzAVBgNVBAoTDkRpZ2lDZXJ0LCBJbmMuMUEwPwYDVQQDEzhEaWdpQ2VydCBU

# cnVzdGVkIEc0IENvZGUgU2lnbmluZyBSU0E0MDk2IFNIQTM4NCAyMDIxIENBMTAe

# Fw0yMjAzMjUwMDAwMDBaFw0yMzA5MDUyMzU5NTlaMFYxCzAJBgNVBAYTAkNaMQ8w

# DQYDVQQHEwZQcmFndWUxGjAYBgNVBAoTEUdyZXlDb3JiZWwgcy5yLm8uMRowGAYD

# VQQDExFHcmV5Q29yYmVsIHMuci5vLjCCAaIwDQYJKoZIhvcNAQEBBQADggGPADCC

# AYoCggGBAMTq3axTav3sMdYp3VziEZs81RtGGJOZcbPcR1+ikq165raa9xv+ZQA2

# mnWa5Wi9zVOAPyi1aS1RgWbKadHBgLKcG5nSVEACOcsK3QuQb334MsVqLoMebzdy

# QOyqyVHpcOfvxkHfggK31A+y4csddAxl3wFBDnfXMX3B0THlB1x0HaFQmx33ewZT

# mNa2ZoVQouxToXxXHOHV4lnFo3NTWoaKSfq0uMgNTGcUfTDka0y1juzWeJLYzEhz

# yYTOlyRhRcVuq6VpAFFo2fORabtGQpv65MbIjopy73kcO6FDwCnh5M3TJSnPUUkX

# /0iWNpjJqz1kyUIshhda6T7NUlyfzmD47+m9ilWM3+A+7zfi2odltoKSQVw8Prcs

# nCc4AuG3tEIYqx3fig5Xo/oFEdplstTU05rYdciiBrUqzLUcqWiQ5RtY5TEkQfMw

# Y3M46AlHSFtuZwbwvt9KjsbrpkynqEbKxJ4ekuv6RPt5z5rIgN5eelLEnSOHbtTI

# HYqdHfXEMQIDAQABo4ICBjCCAgIwHwYDVR0jBBgwFoAUaDfg67Y7+F8Rhvv+YXsI

# iGX0TkIwHQYDVR0OBBYEFEzQTewm/4jkPEqAo2B+zylIxUyvMA4GA1UdDwEB/wQE

# AwIHgDATBgNVHSUEDDAKBggrBgEFBQcDAzCBtQYDVR0fBIGtMIGqMFOgUaBPhk1o

# dHRwOi8vY3JsMy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVzdGVkRzRDb2RlU2ln

# bmluZ1JTQTQwOTZTSEEzODQyMDIxQ0ExLmNybDBToFGgT4ZNaHR0cDovL2NybDQu

# ZGlnaWNlcnQuY29tL0RpZ2lDZXJ0VHJ1c3RlZEc0Q29kZVNpZ25pbmdSU0E0MDk2

# U0hBMzg0MjAyMUNBMS5jcmwwPgYDVR0gBDcwNTAzBgZngQwBBAEwKTAnBggrBgEF

# BQcCARYbaHR0cDovL3d3dy5kaWdpY2VydC5jb20vQ1BTMIGUBggrBgEFBQcBAQSB

# hzCBhDAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AuZGlnaWNlcnQuY29tMFwGCCsG

# AQUFBzAChlBodHRwOi8vY2FjZXJ0cy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVz

# dGVkRzRDb2RlU2lnbmluZ1JTQTQwOTZTSEEzODQyMDIxQ0ExLmNydDAMBgNVHRMB

# Af8EAjAAMA0GCSqGSIb3DQEBCwUAA4ICAQCilggOMD65uoBk0VSHoyArVAPIB382

# oLCagin4YYLi+DYNH0dvvlIlpIsUefE7T43gVK2TkSunGfkEFLWP8IDfYp2D5iD8

# xZfl5AIOAxAExsVXNW8XCEtUIfo3itn0XxtllDxznjtMgyXoI+SrQMR+MFx0e5In

# v+v31yqkasCrynfBNM9G8OAYk0XOKgBgI9mhqZ1FOl82KUsxkGmOW9D2F2em5wpi

# Co+UDnUArIx/YuihkcVvUvMYJqZRKkMFdD75gpmP9W72Jf3jWMdLcV5AW6DX3UGP

# jen1SH5GuFAPCODAMAttJXK7TOInAbK9WY6uiVI7BZ+MaE+l3cX0fSSQK5sxoDUM

# zFoCXXq8uqBRv44m5VbdE1hzt9f96zxbUnluEkOjJ8jVc5xv8yCgxDiOR54z76Vg

# HrbhJVckkunNKdlR6upMo6bT5l/qMDQWPPIAC6tfrB8R+g417XckSdmhKhMrkiTz

# hFvUbFbaD/jH+3xen0ZhpN64mIv5C7mIj17XSZXI4kfvaYcCC72g2ou68PwO5ZHb

# liI75pbBncck3/FNHpLwjpCidET9pWSm+Y/G0jwg068ELN4W0tboplDm1G94ACJz

# Mr4rTC7bOJXoUHKgiHQl4478SyaMAaeJbfCHfdTV8lUthpGubPu2UmxiVXI0AoOG

# Bl1/1lAJOruSnDGCBdMwggXPAgEBMH0waTELMAkGA1UEBhMCVVMxFzAVBgNVBAoT

# DkRpZ2lDZXJ0LCBJbmMuMUEwPwYDVQQDEzhEaWdpQ2VydCBUcnVzdGVkIEc0IENv

# ZGUgU2lnbmluZyBSU0E0MDk2IFNIQTM4NCAyMDIxIENBMQIQAsnIm0KCskhyoko4

# ccQk0jANBglghkgBZQMEAgEFAKCBhDAYBgorBgEEAYI3AgEMMQowCKACgAChAoAA

# MBkGCSqGSIb3DQEJAzEMBgorBgEEAYI3AgEEMBwGCisGAQQBgjcCAQsxDjAMBgor

# BgEEAYI3AgEVMC8GCSqGSIb3DQEJBDEiBCDWhbGZeBvwFwiz868KLwz+L5yVEvzB

# 8UH5T+bf2/dCYDANBgkqhkiG9w0BAQEFAASCAYBJYvfmFB5zB/SCo7yUjbVzn/a1

# OKd/YlkEoccNAyHl+M2NwWIVPO8QikPmuZmhXjaycdU2Yok2flTQBe/wxhTRj51I

# rxsq9+MFDFAe82S9mTw1SfsKp74i/KIDbx+9XCLnZkNuPHv27QyvuFZZLg1TcbAw

# 9clCRbxhk4IRhrvQb2cwNJuPqllhzO+4rennRGeDyX4/qmc9OMtJ1pl0sv4CmqIr

# TEojAxHpOTWYJ1x5FXBFes/Yma/y/nbQYSNAimR4tDJ7fGcyAsHd0NcPQ1c66jui

# uG3XMp0GdASi0qleXYgEQdBcuwjJkozgABivaIGjm/0YEmv16OtAu1qMlvna4lj+

# 3HinmkBNCyssQtJdU0YSxPAeetHpWtni+3OoWPwW8KWKA+Vc/CeXvu/HcpTiXS8t

# QrI4mD0Dcntyxx921eACR5ltp5zh36O7hGc57XA3CbrB790yCtsaoIPjBfojYBZC

# T0t3t4frZTgHLTfvqBsl4L9e4hF5sGvnuVECBTuhggMgMIIDHAYJKoZIhvcNAQkG

# MYIDDTCCAwkCAQEwdzBjMQswCQYDVQQGEwJVUzEXMBUGA1UEChMORGlnaUNlcnQs

# IEluYy4xOzA5BgNVBAMTMkRpZ2lDZXJ0IFRydXN0ZWQgRzQgUlNBNDA5NiBTSEEy

# NTYgVGltZVN0YW1waW5nIENBAhAMTWlyS5T6PCpKPSkHgD1aMA0GCWCGSAFlAwQC

# AQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcN

# MjIxMjA0MTkyODA2WjAvBgkqhkiG9w0BCQQxIgQgLAdGe4LAnPdlvau+VFct1HIf

# rAid5AnlaLdq54w2prwwDQYJKoZIhvcNAQEBBQAEggIAG7tbN4veFINzEo10OzQN

# 9xUdQN0ceYIIrlHNkxrEx8Hse8aL//PoTxvUUVDtPKl+BLxFCryXSCzsn9OaHGrW

# MuNwUDoMhmg7KvT3feCT6mX1Oc82qxhmT9MPezn5e00FIBGrJmzHQiqDcK5UVBLF

# a8vx65qCw2ysjxqpUF76OXqDChfbj6jhCJYorK70pb63H4pmWZFEjbyXu0s7lDca

# tYbUxExs1c0dBqiD3bl4+R1sCbx0aT2HXSxn4DJUHebfrr3Vry8Xyf7jiXEiUeP6

# 6znup1uWJalLWAurf4ZcknNNqTYc/O0moZ8RCYuteV/gMy9AHnFqp0b7LN5ikNKR

# UG8uWXlXcBjZ4fZTFqnqRw7jiNo6bscxQ8LTqYKtp1VgKRKo38O3CgIhtRwJgCsS

# W9Cq+xt/2IEQ08XI6jNOZVmDFeEiCNpd/pgojGE1rue2h1iZqaCOZ6GZhuR9e5bQ

# tGLZNcEANsyETfHJAdfJtcIHMiLFEs8N+6vgnXMKu0cETgW/ozEf28M6+qJHzbtB

# zu8y5qU4VOKmaOQ+naxZLphYRaegtSF7XnVNy0BMyEfVgghuzCkGFO0VbSQ782Ch

# 56Dfotb7+EzaB0LFcajwbmq76mj3mSqnb0HNvTwrGig6ZQtCuJJmOTat0UtcHeOi

# seRAPU3banFP8vdNRGlwTmM=

# SIG # End signature block