BcContainerHelper

6.0.24

Auth/New-BcAuthContext.ps1

                                <# 

 .Synopsis

  Function for creating a new Business Central Authorization Context

 .Description

  Function for creating a new Business Central Authorization Context

  The Authorization Context can be used to authenticate to a Business Central online tenant/environment in various function from ContainerHelper.

  The Authorization Context contains an AccessToken and you can renew the accesstoken (if necessary) by calling Renew-BcAuthContext

  Order of priority of OAuth2 flows: client_credentials, password, refresh_token, devicecode

 .Parameter clientID

  ClientID of AAD app to use for authentication. Default is a well known PowerShell AAD App ID (1950a258-227b-4e31-a9cf-717495945fc2)

 .Parameter Resource

  Resource used for OAuth2 flow. This parameter is obsolete, use scopes instead.

 .Parameter tenantID

  TenantID to use for OAuth2 flow. Default is Common

 .Parameter authority

  Authority to use for OAuth2 login. Default is https://login.microsoftonline.com/$TenantID

 .Parameter scopes

  Scopes to use for OAuth2 flow. Default is https://api.businesscentral.dynamics.com/.default

 .Parameter refreshToken

  If Refresh token is specified, the refresh_token flow will be included in the list of OAuth2 flows to try

 .Parameter clientSecret

  If ClientSecret is specified, the client_credentials flow will be included in the list of OAuth2 flows to try

 .Parameter clientAssertion

  If ClientAssertion is specified, the client_credentials flow (with ClientAssertion instead of ClientSecret) will be included in the list of OAuth2 flows to try

 .Parameter credential

  If Credential is specified, the password flow will be included in the list of OAuth2 flows to try

 .Parameter includeDeviceLogin

  Include this switch if you want to include a device login prompt if no other way to authenticate succeeds

 .Parameter deviceLoginTimeout

  Timespan indicating the timeout while waiting for user to perform devicelogin. Default is 5 minutes.

 .Parameter deviceCode

  When deviceLogin expires, the deviceCode will be returned. You can use this to re-authenticate using the deviceCode and wait for the user to authenticate.

 .Parameter silent

  Include silent to avoid unnecessary output from the function

 .Example

  $authContext = New-BcAuthContext -refreshToken $refreshTokenSecret.SecretValueText

 .Example

  $authContext = New-BcAuthContext -clientID $clientID -clientSecret $clientSecret

 .Example

  $authContext = New-BcAuthContext -includeDeviceLogin -deviceLoginTimeout ([TimeSpan]::FromHours(1))

#>

function New-BcAuthContext {

    Param(

        [string] $clientID = "1950a258-227b-4e31-a9cf-717495945fc2",

        [string] $Resource = "",

        [string] $tenantID = "Common",

        [string] $authority = "https://login.microsoftonline.com/$TenantID",

        [string] $refreshToken,

        [string] $scopes = "$($bcContainerHelperConfig.apiBaseUrl.TrimEnd('/'))/",

        $clientSecret,

        $clientAssertion,

        [PSCredential] $credential,

        [switch] $includeDeviceLogin,

        [Timespan] $deviceLoginTimeout = [TimeSpan]::FromMinutes(15),

        [string] $deviceCode = "",

        [switch] $silent

    )

$telemetryScope = InitTelemetryScope -name $MyInvocation.InvocationName -parameterValues $PSBoundParameters -includeParameters @()

try {

    if ($clientSecret -and ($clientSecret -isnot [SecureString])) {

        $clientSecret = ConvertTo-SecureString -String "$clientSecret" -AsPlainText -Force

    }

    if ($clientAssertion -and ($clientAssertion -isnot [SecureString])) {

        $clientAssertion = ConvertTo-SecureString -String "$clientAssertion" -AsPlainText -Force

    }

    if ($deviceCode) {

        $includeDeviceLogin = $true

    }

    if ($resource) {

        Write-Host -ForegroundColor Yellow "Resource parameter on New-BcAuthContext is obsolete, please use scopes parameter instead"

        $scopes = "$($resource.TrimEnd('/'))/"

    }

    $authContext = @{

        "clientID"           = $clientID

        "scopes"             = $scopes

        "tenantID"           = $tenantID

        "authority"          = $authority

        "includeDeviceLogin" = $includeDeviceLogin

        "deviceLoginTimeout" = $deviceLoginTimeout

        "deviceCode"         = $deviceCode

    }

    $accessToken = $null

    if ($clientSecret -or $clientAssertion) {

        if ($scopes.EndsWith('/')) {

            $scopes += ".default"

        }

        $TokenRequestParams = @{

            Method = 'POST'

            Uri    = "$($authority.TrimEnd('/'))/oauth2/v2.0/token"

            Body   = @{

                "grant_type"    = "client_credentials"

                "scope"         = $scopes

                "client_id"     = $clientId

            }

            Headers = @{ "Content-Type" = "application/x-www-form-urlencoded" }

        }

        if ($clientSecret) {

            $TokenRequestParams.Body += @{

                "client_secret" = ($clientSecret | Get-PlainText)

            }

        }

        else {

            $TokenRequestParams.Body += @{

                "client_assertion_type" = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'

                "client_assertion" = ($clientAssertion | Get-PlainText)

            }

        }

        try {

            if (!$silent) { Write-Host "Attempting authentication to $scopes using clientCredentials..." }

            $TokenRequest = Invoke-RestMethod @TokenRequestParams -UseBasicParsing

            $accessToken = $TokenRequest.access_token

            $jwtToken = Parse-JWTtoken -token $accessToken

            if (!$silent) { Write-Host -ForegroundColor Green "Authenticated as app $($jwtToken.appid)" }

            try {

                $expiresOn = [Datetime]::new(1970,1,1).AddSeconds($jwtToken.exp)

            }

            catch {

                $expiresOn = [DateTime]::now.AddSeconds($TokenRequest)

            }

            $authContext += @{

                "AccessToken"     = $accessToken

                "UtcExpiresOn"    = $expiresOn

                "RefreshToken"    = $null

                "Credential"      = $null

                "ClientSecret"    = $clientSecret

                "ClientAssertion" = $clientAssertion

                "appid"           = $jwtToken.appid

                "name"            = ""

                "upn"             = ""

        }

            if ($tenantID -eq "Common") {

                if (!$silent) { Write-Host "Authenticated to common, using tenant id $($jwtToken.tid)" }

                $authContext.TenantId = $jwtToken.tid

            }

        }

        catch {

            Write-Host -ForegroundColor Red (GetExtendedErrorMessage $_)

            $accessToken = $null

        }

    }

    else {

        if ($scopes.EndsWith('/')) {

            $scopes += "user_impersonation offline_access"

        }

        if ($credential) {

            $TokenRequestParams = @{

                Method = 'POST'

                Uri    = "$($authority.TrimEnd('/'))/oauth2/v2.0/token"

                Body   = @{

                    "grant_type" = "password"

                    "client_id"  = $ClientId

                    "username"   = $credential.UserName

                    "password"   = ($credential.Password | Get-PlainText)

                    "scope"      = $scopes

                }

                Headers = @{ "Content-Type" = "application/x-www-form-urlencoded" }

            }

            try {

                if (!$silent) { Write-Host "Attempting authentication to $Scopes using username/password..." }

                $TokenRequest = Invoke-RestMethod @TokenRequestParams -UseBasicParsing

                $accessToken = $TokenRequest.access_token

                $jwtToken = Parse-JWTtoken -token $accessToken

                if (!$silent) { Write-Host -ForegroundColor Green "Authenticated from $($jwtToken.ipaddr) as user $($jwtToken.name) ($($jwtToken.unique_name))" }

                $authContext += @{

                    "AccessToken"     = $accessToken

                    "UtcExpiresOn"    = [Datetime]::UtcNow.AddSeconds($TokenRequest.expires_in)

                    "RefreshToken"    = $null

                    "Credential"      = $credential

                    "ClientSecret"    = $null

                    "ClientAssertion" = $null

                    "appid"           = ""

                    "name"            = $jwtToken.name

                    "upn"             = $jwtToken.unique_name

                }

                if ($TokenRequest.PSObject.Properties.Name -eq 'refresh_token') {

                    $authContext.RefreshToken = $TokenRequest.refresh_token

                }

                if ($tenantID -eq "Common") {

                    if (!$silent) { Write-Host "Authenticated to common, using tenant id $($jwtToken.tid)" }

                    $authContext.TenantId = $jwtToken.tid

                }

            }

            catch {

                Write-Host -ForegroundColor Yellow (GetExtendedErrorMessage $_).Replace('{EmailHidden}',$credential.UserName)

                $accessToken = $null

            }

        }

        if (!$accessToken -and $refreshToken) {

            $TokenRequestParams = @{

                Method = 'POST'

                Uri    = "$($authority.TrimEnd('/'))/oauth2/v2.0/token"

                Body   = @{

                    "grant_type"    = "refresh_token"

                    "client_id"     = $ClientId

                    "refresh_token" = $refreshToken

                    "scope"         = $scopes

                }

                Headers = @{ "Content-Type" = "application/x-www-form-urlencoded" }

            }

            try

            {

                if (!$silent) { Write-Host "Attempting authentication to $Scopes using refresh token..." }

                $TokenRequest = Invoke-RestMethod @TokenRequestParams -UseBasicParsing

                $accessToken = $TokenRequest.access_token

                try {

                    $jwtToken = Parse-JWTtoken -token $accessToken

                    if (!$silent) { Write-Host -ForegroundColor Green "Authenticated using refresh token as user $($jwtToken.name) ($($jwtToken.unique_name))" }

                }

                catch {

                    $accessToken = $null

                    throw "Invalid Access token"

                }

                $authContext += @{

                    "AccessToken"     = $accessToken

                    "UtcExpiresOn"    = [Datetime]::UtcNow.AddSeconds($TokenRequest.expires_in)

                    "RefreshToken"    = $TokenRequest.refresh_token

                    "Credential"      = $null

                    "ClientSecret"    = $null

                    "ClientAssertion" = $null

                    "appid"           = ""

                    "name"            = $jwtToken.name

                    "upn"             = $jwtToken.unique_name

                    }

                if ($tenantID -eq "Common") {

                    if (!$silent) { Write-Host "Authenticated to common, using tenant id $($jwtToken.tid)" }

                    $authContext.TenantId = $jwtToken.tid

                }

            }

            catch {

                Write-Host -ForegroundColor Yellow "Refresh token not valid"

            }

        }

        if (!$accessToken -and $includeDeviceLogin) {

            $deviceLoginStart = [DateTime]::Now

            $accessToken = ""

            $userCode = ""

            $message = ""

            $interval = 5

            if ($deviceCode -eq "") {

                $DeviceCodeRequestParams = @{

                    Method = 'POST'

                    Uri    = "$($authority.TrimEnd('/'))/oauth2/v2.0/devicecode"

                    Body   = @{

                        "client_id" = $ClientId

                        "scope"     = $Scopes

                    }

                    Headers = @{ "Content-Type" = "application/x-www-form-urlencoded" }

                }

                Write-Host "Attempting authentication to $Scopes using device login..."

                $DeviceCodeRequest = Invoke-RestMethod @DeviceCodeRequestParams -UseBasicParsing

                Write-Host $DeviceCodeRequest.message -ForegroundColor Yellow

                $deviceCode = $DeviceCodeRequest.device_code

                $userCode = $DeviceCodeRequest.user_code

                $interval = $DeviceCodeRequest.interval

                $message = $DeviceCodeRequest.message

                Write-Host -NoNewline "Waiting for authentication (interval=$interval)"

            }

            $TokenRequestParams = @{

                Method = 'POST'

                Uri    = "$($authority.TrimEnd('/'))/oauth2/v2.0/token"

                Body   = @{

                    "grant_type"  = "urn:ietf:params:oauth:grant-type:device_code"

                    "device_code" = $deviceCode

                    "client_id"   = $ClientId

                }

                Headers = @{ "Content-Type" = "application/x-www-form-urlencoded" }

            }

            while ($accessToken -eq "" -and ([DateTime]::Now.Subtract($deviceLoginStart) -lt $deviceLoginTimeout)) {

                Start-Sleep -Seconds $interval

                try {

                    $TokenRequest = Invoke-RestMethod @TokenRequestParams -UseBasicParsing

                    $accessToken = $TokenRequest.access_token

                }

                catch {

                    $tokenRequest = $null

                    $errorRecord = $_

                    try {

                        $err = ($errorRecord.ErrorDetails.Message | ConvertFrom-Json).error

                        if ($err -eq "code_expired") {

                            Write-Host

                            Write-Host -ForegroundColor Red "Authentication request expired."

                            $deviceCode = ""

                        }

                        elseif ($err -eq "expired_token") {

                            Write-Host

                            Write-Host -ForegroundColor Red "Authentication token expired!"

                            $errorRecord = "Authentication token expired!"

                            throw $errorRecord

                        }

                        elseif ($err -eq "authorization_declined") {

                            Write-Host

                            Write-Host -ForegroundColor Red "Authentication request declined!"

                            $errorRecord = "Authentication request declined!"

                            throw $errorRecord

                        }

                        elseif ($err -eq "authorization_pending") {

                            Write-Host -NoNewline "."

                        }

                        else {

                            Write-Host

                            throw $errorRecord

                        }

                    }

                    catch {

                        Write-Host 

                        throw $errorRecord

                    }

                }

            }

            if ($accessToken) {

                try {

                    $jwtToken = Parse-JWTtoken -token $accessToken

                    Write-Host

                    Write-Host -ForegroundColor Green "Authenticated from $($jwtToken.ipaddr) as user $($jwtToken.name) ($($jwtToken.unique_name))"

                }

                catch {

                    $accessToken = $null

                    throw "Invalid Access token"

                }

                $authContext += @{

                    "AccessToken"     = $accessToken

                    "UtcExpiresOn"    = [Datetime]::UtcNow.AddSeconds($TokenRequest.expires_in)

                    "RefreshToken"    = $null

                    "Credential"      = $null

                    "ClientSecret"    = $null

                    "ClientAssertion" = $null

                    "appid"           = ""

                    "name"            = $jwtToken.name

                    "upn"             = $jwtToken.unique_name

                }

                if ($TokenRequest.PSObject.Properties.Name -eq 'refresh_token') {

                    $authContext.RefreshToken = $TokenRequest.refresh_token

                }

                if ($tenantID -eq "Common") {

                    Write-Host "Authenticated to common, using tenant id $($jwtToken.tid)"

                    $authContext.TenantId = $jwtToken.tid

                }

            }

            else {

                Write-Host

                $accessToken = "N/A"

                $authContext.deviceCode = $deviceCode

                $authContext += @{

                    "AccessToken"     = $accessToken

                    "UtcExpiresOn"    = [Datetime]::Now

                    "RefreshToken"    = ""

                    "Credential"      = $null

                    "ClientSecret"    = $null

                    "ClientAssertion" = $null

                    "appid"           = ""

                    "name"            = ""

                    "upn"             = ""

                    "userCode"        = $userCode

                    "message"         = $message

                }

            }

        }

    }

    if (!$accessToken) {

        Write-Host

        Write-Host -ForegroundColor Yellow "Authentication failed"

        return $null

    }

    return $authContext

}

catch {

    TrackException -telemetryScope $telemetryScope -errorRecord $_

    throw

}

finally {

    TrackTrace -telemetryScope $telemetryScope

}

}

Export-ModuleMember -Function New-BcAuthContext

# SIG # Begin signature block

# MIImbAYJKoZIhvcNAQcCoIImXTCCJlkCAQExDzANBglghkgBZQMEAgEFADB5Bgor

# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG

# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCDNsiOf6PIfqGcu

# 8VnmM4XJJk3nfDmsb3kk43wB4uW4IKCCH4QwggWNMIIEdaADAgECAhAOmxiO+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

# twGpn1eqXijiuZQwggYaMIIEAqADAgECAhBiHW0MUgGeO5B5FSCJIRwKMA0GCSqG

# SIb3DQEBDAUAMFYxCzAJBgNVBAYTAkdCMRgwFgYDVQQKEw9TZWN0aWdvIExpbWl0

# ZWQxLTArBgNVBAMTJFNlY3RpZ28gUHVibGljIENvZGUgU2lnbmluZyBSb290IFI0

# NjAeFw0yMTAzMjIwMDAwMDBaFw0zNjAzMjEyMzU5NTlaMFQxCzAJBgNVBAYTAkdC

# MRgwFgYDVQQKEw9TZWN0aWdvIExpbWl0ZWQxKzApBgNVBAMTIlNlY3RpZ28gUHVi

# bGljIENvZGUgU2lnbmluZyBDQSBSMzYwggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAw

# ggGKAoIBgQCbK51T+jU/jmAGQ2rAz/V/9shTUxjIztNsfvxYB5UXeWUzCxEeAEZG

# bEN4QMgCsJLZUKhWThj/yPqy0iSZhXkZ6Pg2A2NVDgFigOMYzB2OKhdqfWGVoYW3

# haT29PSTahYkwmMv0b/83nbeECbiMXhSOtbam+/36F09fy1tsB8je/RV0mIk8XL/

# tfCK6cPuYHE215wzrK0h1SWHTxPbPuYkRdkP05ZwmRmTnAO5/arnY83jeNzhP06S

# hdnRqtZlV59+8yv+KIhE5ILMqgOZYAENHNX9SJDm+qxp4VqpB3MV/h53yl41aHU5

# pledi9lCBbH9JeIkNFICiVHNkRmq4TpxtwfvjsUedyz8rNyfQJy/aOs5b4s+ac7I

# H60B+Ja7TVM+EKv1WuTGwcLmoU3FpOFMbmPj8pz44MPZ1f9+YEQIQty/NQd/2yGg

# W+ufflcZ/ZE9o1M7a5Jnqf2i2/uMSWymR8r2oQBMdlyh2n5HirY4jKnFH/9gRvd+

# QOfdRrJZb1sCAwEAAaOCAWQwggFgMB8GA1UdIwQYMBaAFDLrkpr/NZZILyhAQnAg

# NpFcF4XmMB0GA1UdDgQWBBQPKssghyi47G9IritUpimqF6TNDDAOBgNVHQ8BAf8E

# BAMCAYYwEgYDVR0TAQH/BAgwBgEB/wIBADATBgNVHSUEDDAKBggrBgEFBQcDAzAb

# BgNVHSAEFDASMAYGBFUdIAAwCAYGZ4EMAQQBMEsGA1UdHwREMEIwQKA+oDyGOmh0

# dHA6Ly9jcmwuc2VjdGlnby5jb20vU2VjdGlnb1B1YmxpY0NvZGVTaWduaW5nUm9v

# dFI0Ni5jcmwwewYIKwYBBQUHAQEEbzBtMEYGCCsGAQUFBzAChjpodHRwOi8vY3J0

# LnNlY3RpZ28uY29tL1NlY3RpZ29QdWJsaWNDb2RlU2lnbmluZ1Jvb3RSNDYucDdj

# MCMGCCsGAQUFBzABhhdodHRwOi8vb2NzcC5zZWN0aWdvLmNvbTANBgkqhkiG9w0B

# AQwFAAOCAgEABv+C4XdjNm57oRUgmxP/BP6YdURhw1aVcdGRP4Wh60BAscjW4HL9

# hcpkOTz5jUug2oeunbYAowbFC2AKK+cMcXIBD0ZdOaWTsyNyBBsMLHqafvIhrCym

# laS98+QpoBCyKppP0OcxYEdU0hpsaqBBIZOtBajjcw5+w/KeFvPYfLF/ldYpmlG+

# vd0xqlqd099iChnyIMvY5HexjO2AmtsbpVn0OhNcWbWDRF/3sBp6fWXhz7DcML4i

# TAWS+MVXeNLj1lJziVKEoroGs9Mlizg0bUMbOalOhOfCipnx8CaLZeVme5yELg09

# Jlo8BMe80jO37PU8ejfkP9/uPak7VLwELKxAMcJszkyeiaerlphwoKx1uHRzNyE6

# bxuSKcutisqmKL5OTunAvtONEoteSiabkPVSZ2z76mKnzAfZxCl/3dq3dUNw4rg3

# sTCggkHSRqTqlLMS7gjrhTqBmzu1L90Y1KWN/Y5JKdGvspbOrTfOXyXvmPL6E52z

# 1NZJ6ctuMFBQZH3pwWvqURR8AgQdULUvrxjUYbHHj95Ejza63zdrEcxWLDX6xWls

# /GDnVNueKjWUH3fTv1Y8Wdho698YADR7TNx8X8z2Bev6SivBBOHY+uqiirZtg0y9

# ShQoPzmCcn63Syatatvx157YK9hlcPmVoa1oDE5/L9Uo2bC5a4CH2RwwggZZMIIE

# waADAgECAhANIM3qwHRbWKHw+Zq6JhzlMA0GCSqGSIb3DQEBDAUAMFQxCzAJBgNV

# BAYTAkdCMRgwFgYDVQQKEw9TZWN0aWdvIExpbWl0ZWQxKzApBgNVBAMTIlNlY3Rp

# Z28gUHVibGljIENvZGUgU2lnbmluZyBDQSBSMzYwHhcNMjExMDIyMDAwMDAwWhcN

# MjQxMDIxMjM1OTU5WjBdMQswCQYDVQQGEwJESzEUMBIGA1UECAwLSG92ZWRzdGFk

# ZW4xGzAZBgNVBAoMEkZyZWRkeSBLcmlzdGlhbnNlbjEbMBkGA1UEAwwSRnJlZGR5

# IEtyaXN0aWFuc2VuMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAgYC5

# tlg+VRktRRkahxxaV8+DAd6vHoDpcO6w7yT24lnSoMuA6nR7kgy90Y/sHIwKE9Ww

# t/px/GAY8eBePWjJrFpG8fBtJbXadRTVd/470Hs/q9t+kh6A/0ELj7wYsKSNOyuF

# Poy4rtClOv9ZmrRpoDVnh8Epwg2DpklX2BNzykzBQxIbkpp+xVo2mhPNWDIesntc

# 4/BnSebLGw1Vkxmu2acKkIjYrne/7lsuyL9ue0vk8TGk9JBPNPbGKJvHu9szP9oG

# oH36fU1sEZ+AacXrp+onsyPf/hkkpAMHAhzQHl+5Ikvcus/cDm06twm7VywmZcas

# 2rFAV5MyE6WMEaYAolwAHiPz9WAs2GDhFtZZg1tzbRjJIIgPpR+doTIcpcDBcHnN

# dSdgWKrTkr2f339oT5bnJfo7oVzc/2HGWvb8Fom6LQAqSC11vWmznHYsCm72g+fo

# TKqW8lLDfLF0+aFvToLosrtW9l6Z+l+RQ8MtJ9EHOm2Ny8cFLzZCDZYw32BydwcL

# V5rKdy4Ica9on5xZvyMOLiFwuL4v2V4pjEgKJaGSS/IVSMEGjrM9DHT6YS4/oq9q

# 20rQUmMZZQmGmEyyKQ8t11si8VHtScN5m0Li8peoWfCU9mRFxSESwTWow8d462+o

# 9/SzmDxCACdFwzvfKx4JqDMm55cL+beunIvc0NsCAwEAAaOCAZwwggGYMB8GA1Ud

# IwQYMBaAFA8qyyCHKLjsb0iuK1SmKaoXpM0MMB0GA1UdDgQWBBTZD6uy9ZWIIqQh

# 3srYu1FlUhdM0TAOBgNVHQ8BAf8EBAMCB4AwDAYDVR0TAQH/BAIwADATBgNVHSUE

# DDAKBggrBgEFBQcDAzARBglghkgBhvhCAQEEBAMCBBAwSgYDVR0gBEMwQTA1Bgwr

# BgEEAbIxAQIBAwIwJTAjBggrBgEFBQcCARYXaHR0cHM6Ly9zZWN0aWdvLmNvbS9D

# UFMwCAYGZ4EMAQQBMEkGA1UdHwRCMEAwPqA8oDqGOGh0dHA6Ly9jcmwuc2VjdGln

# by5jb20vU2VjdGlnb1B1YmxpY0NvZGVTaWduaW5nQ0FSMzYuY3JsMHkGCCsGAQUF

# BwEBBG0wazBEBggrBgEFBQcwAoY4aHR0cDovL2NydC5zZWN0aWdvLmNvbS9TZWN0

# aWdvUHVibGljQ29kZVNpZ25pbmdDQVIzNi5jcnQwIwYIKwYBBQUHMAGGF2h0dHA6

# Ly9vY3NwLnNlY3RpZ28uY29tMA0GCSqGSIb3DQEBDAUAA4IBgQASEbZACurQeQN8

# WDTR+YyNpoQ29YAbbdBRhhzHkT/1ao7LE0QIOgGR4GwKRzufCAwu8pCBiMOUTDHT

# ezkh0rQrG6khxBX2nSTBL5i4LwKMR08HgZBsbECciABy15yexYWoB/D0H8WuGe63

# PhGWueR4IFPbIz+jEVxfW0Nyyr7bXTecpKd1iprm+TOmzc2E6ab95dkcXdJVx6Zy

# s++QrrOfQ+a57qEXkS/wnjjbN9hukL0zg+g8L4DHLKTodzfiQOampvV8QzbnB7Y8

# YjNcxR9s/nptnlQH3jorNFhktiBXvD62jc8pAIg6wyH6NxSMjtTsn7QhkIp2kusw

# IQwD8hN/fZ/m6gkXZhRJWFr2WRZOz+edZ62Jf25C/NYWscwfBwn2hzRZf1HgyxkX

# Al88dvvUA3kw1T6uo8aAB9IcL6Owiy7q4T+RLRF7oqx0vcw0193Yhq/gPOaUFlqz

# ExP6TQ5TR9XWVPQk+a1B1ATKMLi1JShO6KWTmNkFkgkgpkW69BEwggauMIIElqAD

# AgECAhAHNje3JFR82Ees/ShmKl5bMA0GCSqGSIb3DQEBCwUAMGIxCzAJBgNVBAYT

# AlVTMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2Vy

# dC5jb20xITAfBgNVBAMTGERpZ2lDZXJ0IFRydXN0ZWQgUm9vdCBHNDAeFw0yMjAz

# MjMwMDAwMDBaFw0zNzAzMjIyMzU5NTlaMGMxCzAJBgNVBAYTAlVTMRcwFQYDVQQK

# Ew5EaWdpQ2VydCwgSW5jLjE7MDkGA1UEAxMyRGlnaUNlcnQgVHJ1c3RlZCBHNCBS

# U0E0MDk2IFNIQTI1NiBUaW1lU3RhbXBpbmcgQ0EwggIiMA0GCSqGSIb3DQEBAQUA

# A4ICDwAwggIKAoICAQDGhjUGSbPBPXJJUVXHJQPE8pE3qZdRodbSg9GeTKJtoLDM

# g/la9hGhRBVCX6SI82j6ffOciQt/nR+eDzMfUBMLJnOWbfhXqAJ9/UO0hNoR8XOx

# s+4rgISKIhjf69o9xBd/qxkrPkLcZ47qUT3w1lbU5ygt69OxtXXnHwZljZQp09ns

# ad/ZkIdGAHvbREGJ3HxqV3rwN3mfXazL6IRktFLydkf3YYMZ3V+0VAshaG43IbtA

# rF+y3kp9zvU5EmfvDqVjbOSmxR3NNg1c1eYbqMFkdECnwHLFuk4fsbVYTXn+149z

# k6wsOeKlSNbwsDETqVcplicu9Yemj052FVUmcJgmf6AaRyBD40NjgHt1biclkJg6

# OBGz9vae5jtb7IHeIhTZgirHkr+g3uM+onP65x9abJTyUpURK1h0QCirc0PO30qh

# HGs4xSnzyqqWc0Jon7ZGs506o9UD4L/wojzKQtwYSH8UNM/STKvvmz3+DrhkKvp1

# KCRB7UK/BZxmSVJQ9FHzNklNiyDSLFc1eSuo80VgvCONWPfcYd6T/jnA+bIwpUzX

# 6ZhKWD7TA4j+s4/TXkt2ElGTyYwMO1uKIqjBJgj5FBASA31fI7tk42PgpuE+9sJ0

# sj8eCXbsq11GdeJgo1gJASgADoRU7s7pXcheMBK9Rp6103a50g5rmQzSM7TNsQID

# AQABo4IBXTCCAVkwEgYDVR0TAQH/BAgwBgEB/wIBADAdBgNVHQ4EFgQUuhbZbU2F

# L3MpdpovdYxqII+eyG8wHwYDVR0jBBgwFoAU7NfjgtJxXWRM3y5nP+e6mK4cD08w

# DgYDVR0PAQH/BAQDAgGGMBMGA1UdJQQMMAoGCCsGAQUFBwMIMHcGCCsGAQUFBwEB

# BGswaTAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AuZGlnaWNlcnQuY29tMEEGCCsG

# AQUFBzAChjVodHRwOi8vY2FjZXJ0cy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVz

# dGVkUm9vdEc0LmNydDBDBgNVHR8EPDA6MDigNqA0hjJodHRwOi8vY3JsMy5kaWdp

# Y2VydC5jb20vRGlnaUNlcnRUcnVzdGVkUm9vdEc0LmNybDAgBgNVHSAEGTAXMAgG

# BmeBDAEEAjALBglghkgBhv1sBwEwDQYJKoZIhvcNAQELBQADggIBAH1ZjsCTtm+Y

# qUQiAX5m1tghQuGwGC4QTRPPMFPOvxj7x1Bd4ksp+3CKDaopafxpwc8dB+k+YMjY

# C+VcW9dth/qEICU0MWfNthKWb8RQTGIdDAiCqBa9qVbPFXONASIlzpVpP0d3+3J0

# FNf/q0+KLHqrhc1DX+1gtqpPkWaeLJ7giqzl/Yy8ZCaHbJK9nXzQcAp876i8dU+6

# WvepELJd6f8oVInw1YpxdmXazPByoyP6wCeCRK6ZJxurJB4mwbfeKuv2nrF5mYGj

# VoarCkXJ38SNoOeY+/umnXKvxMfBwWpx2cYTgAnEtp/Nh4cku0+jSbl3ZpHxcpzp

# SwJSpzd+k1OsOx0ISQ+UzTl63f8lY5knLD0/a6fxZsNBzU+2QJshIUDQtxMkzdwd

# eDrknq3lNHGS1yZr5Dhzq6YBT70/O3itTK37xJV77QpfMzmHQXh6OOmc4d0j/R0o

# 08f56PGYX/sr2H7yRp11LB4nLCbbbxV7HhmLNriT1ObyF5lZynDwN7+YAN8gFk8n

# +2BnFqFmut1VwDophrCYoCvtlUG3OtUVmDG0YgkPCr2B2RP+v6TR81fZvAT6gt4y

# 3wSJ8ADNXcL50CN/AAvkdgIm2fBldkKmKYcJRyvmfxqkhQ/8mJb2VVQrH4D6wPIO

# K+XW+6kvRBVK5xMOHds3OBqhK/bt1nz8MIIGwjCCBKqgAwIBAgIQBUSv85SdCDmm

# v9s/X+VhFjANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJVUzEXMBUGA1UEChMO

# RGlnaUNlcnQsIEluYy4xOzA5BgNVBAMTMkRpZ2lDZXJ0IFRydXN0ZWQgRzQgUlNB

# NDA5NiBTSEEyNTYgVGltZVN0YW1waW5nIENBMB4XDTIzMDcxNDAwMDAwMFoXDTM0

# MTAxMzIzNTk1OVowSDELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDkRpZ2lDZXJ0LCBJ

# bmMuMSAwHgYDVQQDExdEaWdpQ2VydCBUaW1lc3RhbXAgMjAyMzCCAiIwDQYJKoZI

# hvcNAQEBBQADggIPADCCAgoCggIBAKNTRYcdg45brD5UsyPgz5/X5dLnXaEOCdwv

# SKOXejsqnGfcYhVYwamTEafNqrJq3RApih5iY2nTWJw1cb86l+uUUI8cIOrHmjsv

# lmbjaedp/lvD1isgHMGXlLSlUIHyz8sHpjBoyoNC2vx/CSSUpIIa2mq62DvKXd4Z

# GIX7ReoNYWyd/nFexAaaPPDFLnkPG2ZS48jWPl/aQ9OE9dDH9kgtXkV1lnX+3RCh

# G4PBuOZSlbVH13gpOWvgeFmX40QrStWVzu8IF+qCZE3/I+PKhu60pCFkcOvV5aDa

# Y7Mu6QXuqvYk9R28mxyyt1/f8O52fTGZZUdVnUokL6wrl76f5P17cz4y7lI0+9S7

# 69SgLDSb495uZBkHNwGRDxy1Uc2qTGaDiGhiu7xBG3gZbeTZD+BYQfvYsSzhUa+0

# rRUGFOpiCBPTaR58ZE2dD9/O0V6MqqtQFcmzyrzXxDtoRKOlO0L9c33u3Qr/eTQQ

# fqZcClhMAD6FaXXHg2TWdc2PEnZWpST618RrIbroHzSYLzrqawGw9/sqhux7Ujip

# mAmhcbJsca8+uG+W1eEQE/5hRwqM/vC2x9XH3mwk8L9CgsqgcT2ckpMEtGlwJw1P

# t7U20clfCKRwo+wK8REuZODLIivK8SgTIUlRfgZm0zu++uuRONhRB8qUt+JQofM6

# 04qDy0B7AgMBAAGjggGLMIIBhzAOBgNVHQ8BAf8EBAMCB4AwDAYDVR0TAQH/BAIw

# ADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDCDAgBgNVHSAEGTAXMAgGBmeBDAEEAjAL

# BglghkgBhv1sBwEwHwYDVR0jBBgwFoAUuhbZbU2FL3MpdpovdYxqII+eyG8wHQYD

# VR0OBBYEFKW27xPn783QZKHVVqllMaPe1eNJMFoGA1UdHwRTMFEwT6BNoEuGSWh0

# dHA6Ly9jcmwzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRydXN0ZWRHNFJTQTQwOTZT

# SEEyNTZUaW1lU3RhbXBpbmdDQS5jcmwwgZAGCCsGAQUFBwEBBIGDMIGAMCQGCCsG

# AQUFBzABhhhodHRwOi8vb2NzcC5kaWdpY2VydC5jb20wWAYIKwYBBQUHMAKGTGh0

# dHA6Ly9jYWNlcnRzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRydXN0ZWRHNFJTQTQw

# OTZTSEEyNTZUaW1lU3RhbXBpbmdDQS5jcnQwDQYJKoZIhvcNAQELBQADggIBAIEa

# 1t6gqbWYF7xwjU+KPGic2CX/yyzkzepdIpLsjCICqbjPgKjZ5+PF7SaCinEvGN1O

# tt5s1+FgnCvt7T1IjrhrunxdvcJhN2hJd6PrkKoS1yeF844ektrCQDifXcigLiV4

# JZ0qBXqEKZi2V3mP2yZWK7Dzp703DNiYdk9WuVLCtp04qYHnbUFcjGnRuSvExnvP

# nPp44pMadqJpddNQ5EQSviANnqlE0PjlSXcIWiHFtM+YlRpUurm8wWkZus8W8oM3

# NG6wQSbd3lqXTzON1I13fXVFoaVYJmoDRd7ZULVQjK9WvUzF4UbFKNOt50MAcN7M

# mJ4ZiQPq1JE3701S88lgIcRWR+3aEUuMMsOI5ljitts++V+wQtaP4xeR0arAVeOG

# v6wnLEHQmjNKqDbUuXKWfpd5OEhfysLcPTLfddY2Z1qJ+Panx+VPNTwAvb6cKmx5

# AdzaROY63jg7B145WPR8czFVoIARyxQMfq68/qTreWWqaNYiyjvrmoI1VygWy2ny

# Mpqy0tg6uLFGhmu6F/3Ed2wVbK6rr3M66ElGt9V/zLY4wNjsHPW2obhDLN9OTH0e

# aHDAdwrUAuBcYLso/zjlUlrWrBciI0707NMX+1Br/wd3H3GXREHJuEbTbDJ8WC9n

# R2XlG3O2mflrLAZG70Ee8PBf4NvZrZCARK+AEEGKMYIGPjCCBjoCAQEwaDBUMQsw

# CQYDVQQGEwJHQjEYMBYGA1UEChMPU2VjdGlnbyBMaW1pdGVkMSswKQYDVQQDEyJT

# ZWN0aWdvIFB1YmxpYyBDb2RlIFNpZ25pbmcgQ0EgUjM2AhANIM3qwHRbWKHw+Zq6

# JhzlMA0GCWCGSAFlAwQCAQUAoIGEMBgGCisGAQQBgjcCAQwxCjAIoAKAAKECgAAw

# GQYJKoZIhvcNAQkDMQwGCisGAQQBgjcCAQQwHAYKKwYBBAGCNwIBCzEOMAwGCisG

# AQQBgjcCARUwLwYJKoZIhvcNAQkEMSIEIGMNVKDbZ9o40CcOXc3YJRzOOO73EExn

# fkQm4KWkTep3MA0GCSqGSIb3DQEBAQUABIICAD2bC5GAotJ8fXB3ncF0TKqj2BdR

# zG3N12eFh4PPxvjMNnF6HjaX3ujWBY2YayMmRPOmcx48HDz5WQ6e54ZPYSINu/2C

# +dSgquu5qwilwOrmMuXCjpKy0CvhH+a2Cm4IZp0rCltVmFXAv4z6z/hTdux0bhmo

# qM+UXl89bINcRAp0s+SHt7BMuKRCsH5A4JYelzwIrfRiLi88lyTPdaYcvxVRS4gj

# o0kMUlohEL/1FImU76A5zKkQBJmhqNTjmEckfMSiE/6+bbSevoFkcGpfQzf+C0dV

# tx0pgei0pQpHKh6jtQnbpmhZrlJPw0IG29ufiWXmJ3pFfhEBbzavpESy5bejkfyb

# qiz1UnpafLHslCfuuKYD/LUcm3y8eI4rFGM9DShgBwHIlY4B9MrTyklJ2Nr2SYvw

# AU1dMcUKZJH7ehvfsu5w99qISRIqPE9oxUtlFzTkJnna2SK+sVIJht9PoI4mt+bY

# IZVfaBe+NvDZV3C+nMIRfdlAW9EoEI9yUDS8S3ihjIZRPH7fHjM+i+EI1lx9zIZF

# x58vQtFruci5/P+seyCrxfIZDiraHxG47Z1Bqqy21MClnSw+eAsVyVcwuHL7eYTe

# vKve0ldCRrJZj9LBr4XODUXdKuY9zJPiPyr/SKUPOQxio88CdvVhjp8hmbyBhD/P

# 7qgCVkZQKpXzxRTCoYIDIDCCAxwGCSqGSIb3DQEJBjGCAw0wggMJAgEBMHcwYzEL

# MAkGA1UEBhMCVVMxFzAVBgNVBAoTDkRpZ2lDZXJ0LCBJbmMuMTswOQYDVQQDEzJE

# aWdpQ2VydCBUcnVzdGVkIEc0IFJTQTQwOTYgU0hBMjU2IFRpbWVTdGFtcGluZyBD

# QQIQBUSv85SdCDmmv9s/X+VhFjANBglghkgBZQMEAgEFAKBpMBgGCSqGSIb3DQEJ

# AzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTI0MDkyNTA2MDc1MFowLwYJ

# KoZIhvcNAQkEMSIEIH7bfK7oZ2uVqNS6bDjzTJRUvTKA99py4hGu2xJ3EN/uMA0G

# CSqGSIb3DQEBAQUABIICAAhTc2CVgqVxHv5i1MHIirCrIBH4mzwoOOCAKtUZc00K

# 27dRh8ws5PbvJE2RGoxzo442y3mvbaL5kwEKcNwb9Qk/RN/mhKZtwXLlUo7RvZ8z

# DIvgactGrgvK9QOIpnK/PhMXaieknuqUEXPyf07rlcpxJeYu/B2X0vmep3HfghLK

# mxMDhTxCjUSMok8Ie0amr7ApnQM5Q57QBZGINn5j2hGzVMQG51dGJDxV2NmNasuE

# tLwnFUmTTiKFa3+XqA5tn69QlM5QcN5lAkqGoq+RZPtuE+hNDzg42ehfXv82sh5D

# nw8qOU2UhrfkMKGaW0f6H+SXNtvG7tq4gRGeSAeEHgb28LfrhCOH1fqdCsyA+xQQ

# Q0kj1oaQFonJYt+IwUnAtg/6SN2Fo4NSQyVbmOB9U1dX+ZJan3ysuxm+Ks6gyJTM

# ds6iQ8RwBm8f/iTnC/0AQSwIvBm8P3L/Yg0sleZvl9Pa15DOOc7F6nnZvqPe7X0n

# RFjN/DtiIiKemZF6fjWn+RCI6cUsAR2IJB0G8yep7JQVV5c84Zi+oCUZh88RyH7E

# PWe0cbRD1oSDip6ZM9tUKz8LlBdDRPEzbH4l/XKYhu9hT0ixA27mpF5FSl2sR8Zd

# Dlg5s/Jc6zwAWbG93lM0B5qrsJa5YaOVYBEg/fvvnGWObeaaK3NnUj+NteCwO0TJ

# SIG # End signature block