Preparing CertBasedAuth

lusassl-msft · lusassl-msft · commit d5915a937452 · 2023-03-27T20:32:28.000+02:00
diff --git a/.build/cspell-words.txt b/.build/cspell-words.txt
@@ -58,6 +58,7 @@ hostnames
 HRESULT
 hsts
 httperr
+ietf
 imap
 Infoworker
 INSUFF
@@ -105,11 +106,12 @@ ntlm
 NTFS
 NUMA
 nupkg
+onmicrosoft
 onprem
 OutlookiOS
 Perflib
 perfmon
-PKCS
+Pkcs
 Prelicensing
 PROCMON
 QWORD
diff --git a/Hybrid/Test-HMAEAS.ps1 b/Hybrid/Test-HMAEAS.ps1
@@ -256,7 +256,7 @@ process {
                 $uri = New-Object "System.Uri" -ArgumentList $easUrl
                 $resource = "$($uri.Scheme)://$($uri.Host)"
                 $applicationClientId = "27922004-5251-4030-b22d-91ecd9a37ea4"
-                $redirectUri = [System.Uri]("urn:ieTf:wg:oauth:2.0:oob").ToLower()
+                $redirectUri = [System.Uri]("urn:ietf:wg:oauth:2.0:oob").ToLower()
                 $authenticationContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList $authority
                 $PromptBehavior = [Microsoft.IdentityModel.Clients.ActiveDirectory.PromptBehavior]::RefreshSession
                 $platformParam = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.PlatformParameters" -ArgumentList $PromptBehavior, $NULL
diff --git a/Security/src/CVE-2023-23397/CVE-2023-23397.ps1 b/Security/src/CVE-2023-23397/CVE-2023-23397.ps1
@@ -43,6 +43,12 @@
     This optional parameter allows you to provide Azure environment
 .PARAMETER AzureApplicationName
     This optional parameter allows you to provide Azure application name
+.PARAMETER CertificateThumbprint
+    This optional parameter allows you to provide a certificate thumbprint to use the Azure application created by the script
+.PARAMETER AppId
+    This optional parameter allows you to provide the AppId of the Azure application created by the script
+.PARAMETER Organization
+    This optional parameter allows you to provide the organization name e.g., contoso.onmicrosoft.com
 .PARAMETER EWSOnlineURL
     This optional parameter allows you to provide EWS online url
 .PARAMETER EWSOnlineScope
@@ -130,6 +136,18 @@ param(
     [Parameter(Mandatory = $false, ParameterSetName = "Cleanup")]
     [String]$AzureApplicationName = "CVE-2023-23397Application",
 
+    [Parameter(Mandatory = $false, ParameterSetName = "Audit")]
+    [Parameter(Mandatory = $false, ParameterSetName = "Cleanup")]
+    [String]$CertificateThumbprint,
+
+    [Parameter(Mandatory = $false, ParameterSetName = "Audit")]
+    [Parameter(Mandatory = $false, ParameterSetName = "Cleanup")]
+    [String]$AppId,
+
+    [Parameter(Mandatory = $false, ParameterSetName = "Audit")]
+    [Parameter(Mandatory = $false, ParameterSetName = "Cleanup")]
+    [String]$Organization,
+
     [Parameter(Mandatory = $false, ParameterSetName = "Audit")]
     [Parameter(Mandatory = $false, ParameterSetName = "Cleanup")]
     [Uri]$EWSOnlineURL = "https://outlook.office365.com/EWS/Exchange.asmx",
@@ -227,6 +245,7 @@ begin {
     . $PSScriptRoot\..\..\..\Shared\Get-NuGetPackage.ps1
     . $PSScriptRoot\..\..\..\Shared\Invoke-ExtractArchive.ps1
     . $PSScriptRoot\..\..\..\Shared\LoggerFunctions.ps1
+    . $PSScriptRoot\..\..\..\Shared\AzureFunctions\Get-NewJsonWebToken.ps1
     . $PSScriptRoot\..\..\..\Shared\Show-Disclaimer.ps1
 
     $loggerParams = @{
@@ -400,15 +419,22 @@ begin {
             [string]$ClientID,
             [string]$AppSecret,
             [string]$AzureADEndpoint,
+            [bool]$UseCertificateToAuthenticate = $false,
             [string]$Scope
         )
 
         try {
             $body = @{
-                scope         = $Scope
-                client_id     = $ClientID
-                client_secret = $AppSecret
-                grant_type    = "client_credentials"
+                scope      = $Scope
+                client_id  = $ClientID
+                grant_type = "client_credentials"
+            }
+
+            if ($UseCertificateToAuthenticate) {
+                $body.Add("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
+                $body.Add("client_assertion", $AppSecret)
+            } else {
+                $body.Add("client_secret", $AppSecret)
             }
 
             $PostSplat = @{
@@ -456,7 +482,8 @@ begin {
     function GetApplicationDetails {
         param (
             $AzureApplicationName,
-            $AzureEnvironmentName
+            $AzureEnvironmentName,
+            $UseCertificateToAuthenticate = $false
         )
 
         ConnectAzureAD -AzureEnvironmentName $AzureEnvironmentName
@@ -473,18 +500,22 @@ begin {
             exit
         }
 
-        #Assign App Password, make it valid for 7 days
-        $appPassword = New-AzureADApplicationPasswordCredential -ObjectId $aadApplication.ObjectId -CustomKeyIdentifier "AppAccessKey" -EndDate (Get-Date).AddDays(7) -ErrorAction Stop
+        $returnObject = @{
+            TenantID = (Get-AzureADTenantDetail).ObjectId
+            ClientID = $aadApplication.AppId
+        }
 
-        Write-Host "`nWaiting 60 seconds for app credentials to register.."
-        Start-Sleep -Seconds 60
-        Write-Host "`nContinuing..."
+        if ($UseCertificateToAuthenticate -ne $true) {
+            #Assign App Password, make it valid for 7 days
+            $appPassword = New-AzureADApplicationPasswordCredential -ObjectId $aadApplication.ObjectId -CustomKeyIdentifier "AppAccessKey" -EndDate (Get-Date).AddDays(7) -ErrorAction Stop
 
-        return @{
-            "TenantID"  = (Get-AzureADTenantDetail).ObjectId
-            "ClientID"  = $aadApplication.AppId
-            "AppSecret" = $appPassword.Value
+            Write-Host "`nWaiting 60 seconds for app credentials to register..."
+            Start-Sleep -Seconds 60
+            Write-Host "`nContinuing..."
+            $returnObject.Add("AppSecret", $appPassword.Value)
         }
+
+        return $returnObject
     }
 
     ## function to delete Azure AD application
@@ -628,7 +659,36 @@ begin {
 
         # if token is going to expire in next 5 min then refresh it
         if ($null -eq $script:tokenLastRefreshTime -or $script:tokenLastRefreshTime.AddMinutes(55) -lt (Get-Date)) {
-            $token.Value = CreateOAUTHToken -TenantID $applicationInfo.TenantID -ClientID $applicationInfo.ClientID -AppSecret $applicationInfo.AppSecret -AzureADEndpoint $AzureADEndpoint -Scope $EWSOnlineScope
+            $createOAuthTokenParams = @{
+                TenantID                     = $applicationInfo.TenantID
+                ClientID                     = $applicationInfo.ClientID
+                AzureADEndpoint              = $AzureADEndpoint
+                UseCertificateToAuthenticate = (-not([System.String]::IsNullOrEmpty($applicationInfo.CertificateThumbprint)))
+                Scope                        = $EWSOnlineScope
+            }
+
+            # Check if we use an app secret or certificate by using regex to match Json Web Token (JWT)
+            if ($applicationInfo.AppSecret -match "^([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_=]+)\.([a-zA-Z0-9_\-\+\/=]*)") {
+                $jwtParams = @{
+                    CertificateThumbprint = $applicationInfo.CertificateThumbprint
+                    CertificateStore      = "CurrentUser"
+                    Issuer                = $applicationInfo.ClientID
+                    Audience              = ("{0}{1}/oauth2/v2.0/token" -f $AzureADEndpoint, $applicationInfo.TenantID)
+                    Subject               = $applicationInfo.ClientID
+                }
+                $jwt = Get-NewJsonWebToken @jwtParams
+
+                if ($null -eq $jwt) {
+                    Write-Host "Unable to sign a new Json Web Token by using certificate: $($applicationInfo.CertificateThumbprint)" -ForegroundColor Red
+                    exit
+                }
+
+                $createOAuthTokenParams.Add("AppSecret", $jwt)
+            } else {
+                $createOAuthTokenParams.Add("AppSecret", $applicationInfo.AppSecret)
+            }
+
+            $token.Value = CreateOAUTHToken @createOAuthTokenParams
             $ewsService.Value = EWSAuth -Environment $Environment -token $token.Value -EWSOnlineURL $EWSOnlineURL
         }
     }
@@ -806,16 +866,61 @@ begin {
     }
 
     if ($Environment -eq "Online") {
-        $application = GetApplicationDetails -AzureApplicationName $AzureApplicationName -AzureEnvironmentName $AzureEnvironmentName
+        $getApplicationDetailsParams = @{
+            AzureApplicationName         = $AzureApplicationName
+            AzureEnvironmentName         = $AzureEnvironmentName
+            UseCertificateToAuthenticate = (-not([System.String]::IsNullOrEmpty($CertificateThumbprint)))
+        }
+
+        if (([System.String]::IsNullOrEmpty($AppId)) -or
+            ([System.String]::IsNullOrEmpty($Organization)) -or
+            ([System.String]::IsNullOrEmpty($CertificateThumbprint))) {
+            $application = GetApplicationDetails @getApplicationDetailsParams
+
+            $TenantID = $application.Tenant.Id
+            $ClientID = $application.ClientID
+        } else {
+            $TenantID = $Organization
+            $ClientID = $AppId
+        }
 
         $applicationInfo = @{
-            "TenantID"  = $application.Tenant.Id
-            "ClientID"  = $application.ClientID
-            "AppSecret" = $application.AppSecret
+            "TenantID" = $TenantID
+            "ClientID" = $ClientID
+        }
+
+        if ($null -ne $application.AppSecret) {
+            $applicationInfo.Add("AppSecret", $application.AppSecret)
+        } else {
+            $jwtParams = @{
+                CertificateThumbprint = $CertificateThumbprint
+                CertificateStore      = "CurrentUser"
+                Issuer                = $ClientID
+                Audience              = ("{0}{1}/oauth2/v2.0/token" -f $AzureADEndpoint, $TenantID)
+                Subject               = $ClientID
+            }
+            $jwt = Get-NewJsonWebToken @jwtParams
+
+            if ($null -eq $jwt) {
+                Write-Host "Unable to generate Json Web Token by using certificate: $CertificateThumbprint" -ForegroundColor Red
+                exit
+            }
+
+            $applicationInfo.Add("AppSecret", $jwt)
+            $applicationInfo.Add("CertificateThumbprint", $CertificateThumbprint)
+        }
+
+        $createOAuthTokenParams = @{
+            TenantID                     = $TenantID
+            ClientID                     = $ClientID
+            AppSecret                    = $applicationInfo.AppSecret
+            Scope                        = $EWSOnlineScope
+            AzureADEndpoint              = $AzureADEndpoint
+            UseCertificateToAuthenticate = (-not([System.String]::IsNullOrEmpty($CertificateThumbprint)))
         }
 
         #Create OAUTH token
-        $EWSToken = CreateOAUTHToken -TenantID $applicationInfo.TenantID -ClientID $applicationInfo.ClientID -AppSecret $applicationInfo.AppSecret -Scope $EWSOnlineScope -AzureADEndpoint $AzureADEndpoint
+        $EWSToken = CreateOAUTHToken @createOAuthTokenParams
 
         $ewsService = EWSAuth -Environment $Environment -Token $EWSToken -EWSOnlineURL $EWSOnlineURL
     } else {
diff --git a/Shared/AzureFunctions/Get-NewJsonWebToken.ps1 b/Shared/AzureFunctions/Get-NewJsonWebToken.ps1
@@ -0,0 +1,122 @@
+﻿# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+function Get-NewJsonWebToken {
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory = $true)]
+        [string]$CertificateThumbprint,
+
+        [ValidateSet("CurrentUser", "LocalMachine")]
+        [Parameter(Mandatory = $false)]
+        [string]$CertificateStore = "CurrentUser",
+
+        [Parameter(Mandatory = $false)]
+        [string]$Issuer,
+
+        [Parameter(Mandatory = $false)]
+        [string]$Audience,
+
+        [Parameter(Mandatory = $false)]
+        [string]$Subject,
+
+        [Parameter(Mandatory = $false)]
+        [int]$TokenLifetimeInSeconds = 3600,
+
+        [ValidateSet("RS256", "RS384", "RS512")]
+        [Parameter(Mandatory = $false)]
+        [string]$SigningAlgorithm = "RS256"
+    )
+
+    <#
+        Shared function to create a signed Json Web Token (JWT) by using a certificate.
+        It is also possible to use a secret key to sign the token, but that is not supported in this function.
+        The function returns the token as a string if successful, otherwise it returns $null.
+        https://www.rfc-editor.org/rfc/rfc7519
+        https://learn.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials
+        https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
+    #>
+
+    begin {
+        Write-Verbose "Calling $($MyInvocation.MyCommand)"
+    }
+    process {
+        try {
+            $certificate = Get-ChildItem Cert:\$CertificateStore\My\$CertificateThumbprint
+            if ($certificate.HasPrivateKey) {
+                $privateKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($certificate)
+                # Base64url-encoded SHA-1 thumbprint of the X.509 certificate's DER encoding
+                $x5t = [System.Convert]::ToBase64String($certificate.GetCertHash())
+                $x5t = ((($x5t).Replace("\+", "-")).Replace("/", "_")).Replace("=", "")
+                Write-Verbose "x5t is: $x5t"
+            } else {
+                Write-Verbose "We don't have a private key for certificate: $CertificateThumbprint and so cannot sign the token"
+                return
+            }
+        } catch {
+            Write-Verbose "Unable to import the certificate - Exception: $($Error[0].Exception.Message)"
+            return
+        }
+
+        $header = [ordered]@{
+            alg = $SigningAlgorithm
+            typ = "JWT"
+            x5t = $x5t
+        }
+
+        # "iat" (issued at) and "exp" (expiration time) must be UTC and in UNIX time format
+        $payload = @{
+            iat = [Math]::Round((Get-Date).ToUniversalTime().Subtract((Get-Date -Date "01/01/1970")).TotalSeconds)
+            exp = [Math]::Round((Get-Date).ToUniversalTime().Subtract((Get-Date -Date "01/01/1970")).TotalSeconds) + $TokenLifetimeInSeconds
+        }
+
+        # Issuer, Audience and Subject are optional as per RFC 7519
+        if (-not([System.String]::IsNullOrEmpty($Issuer))) {
+            Write-Verbose "Issuer: $Issuer will be added to payload"
+            $payload.Add("iss", $Issuer)
+        }
+
+        if (-not([System.String]::IsNullOrEmpty($Audience))) {
+            Write-Verbose "Audience: $Audience will be added to payload"
+            $payload.Add("aud", $Audience)
+        }
+
+        if (-not([System.String]::IsNullOrEmpty($Subject))) {
+            Write-Verbose "Subject: $Subject will be added to payload"
+            $payload.Add("sub", $Subject)
+        }
+
+        $headerJson = $header | ConvertTo-Json -Compress
+        $payloadJson = $payload | ConvertTo-Json -Compress
+
+        $headerBase64 = [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($headerJson)).Split("=")[0].Replace("+", "-").Replace("/", "_")
+        $payloadBase64 = [Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($payloadJson)).Split("=")[0].Replace("+", "-").Replace("/", "_")
+
+        $signatureInput = [System.Text.Encoding]::ASCII.GetBytes("$headerBase64.$payloadBase64")
+
+        Write-Verbose "Header (Base64) is: $headerBase64"
+        Write-Verbose "Payload (Base64) is: $payloadBase64"
+        Write-Verbose "Signature input is: $signatureInput"
+
+        $signingAlgorithmToUse = switch ($SigningAlgorithm) {
+            ("RS384") { [Security.Cryptography.HashAlgorithmName]::SHA384 }
+            ("RS512") { [Security.Cryptography.HashAlgorithmName]::SHA512 }
+            default { [Security.Cryptography.HashAlgorithmName]::SHA256 }
+        }
+        Write-Verbose "Signing the Json Web Token using: $SigningAlgorithm"
+
+        $signature = $privateKey.SignData($signatureInput, $signingAlgorithmToUse, [Security.Cryptography.RSASignaturePadding]::Pkcs1)
+        $signature = [Convert]::ToBase64String($signature).Split("=")[0].Replace("+", "-").Replace("/", "_")
+    }
+    end {
+        if ((-not([System.String]::IsNullOrEmpty($headerBase64))) -and
+            (-not([System.String]::IsNullOrEmpty($payloadBase64))) -and
+            (-not([System.String]::IsNullOrEmpty($signature)))) {
+            Write-Verbose "Returning Json Web Token"
+            return ("$headerBase64.$payloadBase64.$signature")
+        } else {
+            Write-Verbose "Unable to create Json Web Token"
+            return
+        }
+    }
+}
diff --git a/docs/Security/CVE-2023-23397/FAQ.md b/docs/Security/CVE-2023-23397/FAQ.md
@@ -96,3 +96,25 @@ It will only export individual items that contain the PidLidReminderFileParamete
 ## Why does my output file contain multiple entries for the same mailbox?
 
 For each individual item that does contain the PidLidReminderFileParameter property, it will be exported out with a item ID that is needed to possibly take action against.
+
+## What are the required steps to prepare the 'CVE-2023-23397Application' application to support Certificate Based Authentication (CBA)
+
+Step 1: Create the Azure application by running the script with the `CreateAzureApplication`. This step must be performed by someone who is `Global Administrator` or an `Application Administrator`.
+
+Step 2: Generate a new self-signed certificate and export the public part:
+
+```powershell
+$cert = New-SelfSignedCertificate -Subject $env:COMPUTERNAME -CertStoreLocation "Cert:\CurrentUser\My"
+$cert | Export-Certificate -FilePath MySelfSignedCertificate.cer
+$cert.Thumbprint
+```
+
+!!! warning "Important"
+
+    The certificate must be kept confidential as it allows the owner to access the Azure application without further authentication.
+
+Step 3: Upload the certificate to the `CVE-2023-23397Application` Azure application
+
+Go to the Azure Active Directory and search for `App registrations`. Select the `CVE-2023-23397Application` application and go to `Certificates & secrets`. From here, select `Certificates` and click on `Upload certificate`. Select the `MySelfSignedCertificate.cer` file which was created in Step 2, add a descriptive description. Complete the process by clicking on `Add`.
+
+The application is now ready for CBA.
diff --git a/docs/Security/CVE-2023-23397/index.md b/docs/Security/CVE-2023-23397/index.md
