Verify HMAC signature of incoming Azure Automation webhook requests.

PSFunction1_Test-HmacAuthorization.ps1

function Test-HmacAuthorization {
    <#
    .SYNOPSIS
        Verifies HMAC signature of incoming Azure Automation webhook requests.

    .DESCRIPTION
        Validates HMAC signature based on signed request headers (timestamp, nonce, content hash) and a shared secret.
        Supports both HMACSHA256 and HMACSHA512 algorithms.

        The shared secret is passed securely as a SecureString, converted as late as possible, and cleared from memory immediately after use.
        Signature verification includes:
        - Timestamp freshness validation (anti-replay window configurable via AllowedTimeDriftMinutes)
        - Host
        - Body content hash integrity check
        - Nonce inclusion for replay protection (future extension to store/check nonce is left open)

    .EXAMPLE
        # ✅ Example 1: Production (Azure Automation)

        # Retrieve encrypted variable securely
        $sharedSecret = (Get-AutomationVariable -Name "SharedSecret") | ConvertTo-SecureString -AsPlainText -Force

        # Verify signature
        if (-not (Test-HmacAuthorization -SharedSecret $sharedSecret -WebhookData $WebhookData)) {
            [void]$sharedSecret.Dispose()
            throw "Unauthorized: Signature verification failed."
        }

        # Dispose secret after use
        [void]$sharedSecret.Dispose()

    .EXAMPLE
        # ✅ Example 2: Local Development / Testing

        # Use test shared secret (DO NOT use hardcoded secrets in production)
        $sharedSecret = ConvertTo-SecureString -String "MyTestSecretKey" -AsPlainText -Force

        # Verify signature
        if (-not (Test-HmacAuthorization -SharedSecret $sharedSecret -WebhookData $WebhookData)) {
            Write-Output "❌ Signature invalid."
        } else {
            Write-Output "✅ Signature valid."
        }

        # Dispose secret
        [void]$sharedSecret.Dispose()

    .FUNCTIONALITY
        Security, HMAC Authentication

    .NOTES
        Author: Julian Pawlowski
        Company Name: Workoho GmbH
        Created: 2025-03-17
        Updated: 2025-03-18
    #>

    param(
        # The shared secret key used for HMAC calculation (SecureString)
        [Parameter(Mandatory)][securestring]$SharedSecret,

        # The full webhook request data object passed by Azure Automation (includes headers and body)
        [Parameter(Mandatory)][object]$WebhookData,

        # Allowed time difference in minutes for timestamp validation (default: 5 minutes)
        [int]$AllowedTimeDriftMinutes = 5,

        # Expected request path (used in canonical message construction)
        [string]$ExpectedPath = '/webhooks'
    )

    $allowedAlgorithms = @('HMACSHA256', 'HMACSHA512')
    $headers = $WebhookData.RequestHeader
    $authHeader = $headers.'x-authorization'

    if (-not $authHeader) {
        Write-Error 'Missing x-authorization header'
        return $false
    }

    if ($authHeader -notmatch '^HMAC-(?<Algorithm>[A-Z0-9]+)\s+SignedHeaders=(?<SignedHeaders>[^&]+)&Signature=(?<Signature>.+)$') {
        Write-Error 'Invalid x-authorization header format'
        return $false
    }

    $algorithm = "HMAC$($matches['Algorithm'])"
    if ($allowedAlgorithms -notcontains $algorithm) {
        Write-Error "Algorithm $algorithm not allowed"
        return $false
    }

    $signedHeaders = $matches['SignedHeaders'].Split(';')
    $receivedHmac = $matches['Signature']

    foreach ($header in $signedHeaders) {
        if ([string]::IsNullOrEmpty($headers.$header)) {
            Write-Error "Missing signed header: $header"
            return $false
        }
    }

    # Host header check
    if ([string]::IsNullOrEmpty($headers.'Host')) {
        Write-Error 'Host header required'
        return $false
    }

    # Timestamp freshness check
    if ([string]::IsNullOrEmpty($headers.'x-ms-date')) {
        Write-Error 'x-ms-date header required'
        return $false
    }
    else {
        try {
            $requestTime = [datetime]::Parse($headers.'x-ms-date').ToUniversalTime()
            $currentTime = (Get-Date).ToUniversalTime()
            if ([math]::Abs(($currentTime - $requestTime).TotalMinutes) -gt $AllowedTimeDriftMinutes) {
                Write-Error 'Request timestamp expired'
                return $false
            }
        }
        catch {
            Write-Error 'Invalid timestamp format'
            return $false
        }
    }

    # Body hash check
    if ([string]::IsNullOrEmpty($headers.'x-ms-content-sha256')) {
        Write-Error "x-ms-content-sha256 header required"
        return $false
    }
    else {
        $bodyBytes = [Text.Encoding]::UTF8.GetBytes($WebhookData.RequestBody)
        $computedBodyHash = [Convert]::ToBase64String(([System.Security.Cryptography.SHA256]::Create()).ComputeHash($bodyBytes))
        if ($headers.'x-ms-content-sha256' -ne $computedBodyHash) {
            Write-Error "Content hash mismatch"
            return $false
        }
    }

    # Nonce check
    if ([string]::IsNullOrEmpty($headers.'x-ms-nonce')) {
        Write-Error "x-ms-nonce header required"
        return $false
    }
    # Optional future: Implement nonce storage to prevent re-use attacks

    # Canonical message construction
    $method = 'POST'
    $path = $ExpectedPath
    $headerValues = foreach ($header in $signedHeaders) { $headers.$header }
    $canonicalMessage = "$method`n$path`n" + ($headerValues -join ';')

    $unsecureSecret = $null
    try {
        $hmac = New-Object ("System.Security.Cryptography.$algorithm")

        # SecureString → plaintext
        $unsecureSecret = [System.Net.NetworkCredential]::New("", $SharedSecret).Password

        $hmac.Key = [Text.Encoding]::UTF8.GetBytes($unsecureSecret)
        $computedHmac = [Convert]::ToBase64String($hmac.ComputeHash([Text.Encoding]::UTF8.GetBytes($canonicalMessage)))

        # Cleanup HMAC key
        [Array]::Clear($hmac.Key, 0, $hmac.Key.Length)
        $hmac = $null
    }
    finally {
        if ($unsecureSecret) {
            [Array]::Clear($unsecureSecret.ToCharArray(), 0, $unsecureSecret.Length)
            $unsecureSecret = $null
        }
    }

    # Final comparison (constant-time)
    return [System.Security.Cryptography.CryptographicOperations]::FixedTimeEquals(
        [Text.Encoding]::UTF8.GetBytes($computedHmac),
        [Text.Encoding]::UTF8.GetBytes($receivedHmac)
    )
}

PSFunction2_Get-HmacSignedHeaders.ps1

function Get-HmacSignedHeaders {
    <#
    .SYNOPSIS
        Generates signed headers for HMAC authentication for Azure Automation webhook requests.

    .DESCRIPTION
        Generates signed headers for HMAC authentication based on a shared secret (provided as SecureString), webhook URL, and request body content.
        Includes timestamp, nonce, and content hash, all covered in the HMAC signature.
        SecureString is converted as late as possible and securely cleared after use.
        
        This function is intended to be used when calling Azure Automation webhooks or other APIs requiring signed requests for enhanced security.

        ------------------------------------------
        🔐 Secure Shared Secret Retrieval Options:
        ------------------------------------------

        Always retrieve secrets securely from encrypted sources, ensuring they are stored and used as SecureStrings:

        1️⃣ Azure Key Vault (Recommended for cloud/hybrid environments)
            Connect-AzAccount -Identity
            $sharedSecret = (Get-AzKeyVaultSecret -VaultName "<YourVaultName>" -Name "HmacSharedSecret").SecretValue

        2️⃣ Azure Automation Encrypted Variable (inside Automation Account only)
            $sharedSecret = (Get-AutomationVariable -Name "SharedSecret") | ConvertTo-SecureString -AsPlainText -Force

        3️⃣ Windows Credential Manager (if running on Windows, via SecretManagement module)
            Import-Module Microsoft.PowerShell.SecretManagement
            $sharedSecret = (Get-StoredCredential -Target "HmacSharedSecret").Password

        4️⃣ Encrypted local file (protected by ACLs; not recommended for cloud, acceptable in controlled environments)
            $sharedSecret = (Get-Content -Path "C:\Secrets\HmacSecret.txt" -Raw) | ConvertTo-SecureString -AsPlainText -Force

        ❌ For demonstration purposes only (NEVER hardcode secrets in production):
            $sharedSecret = ConvertTo-SecureString -String "MySuperSecretKey" -AsPlainText -Force

    .EXAMPLE
        # Example usage:
        $sharedSecret = (Get-AutomationVariable -Name "SharedSecret") | ConvertTo-SecureString -AsPlainText -Force
        $webhookUrl = "https://<your-webhook-url>/webhooks"
        $body = '{"param1":"value1"}'

        $headers = Get-HmacSignedHeaders -SharedSecret $sharedSecret `
            -WebhookUrl $webhookUrl `
            -Body $body

        [void]$sharedSecret.Dispose()

        Invoke-RestMethod -Method POST `
            -Uri $webhookUrl `
            -Headers $headers `
            -Body $body `
            -ContentType 'application/json; charset=utf-8'

    .FUNCTIONALITY
        Security, HMAC Authentication

    .NOTES
        Author: Julian Pawlowski
        Company Name: Workoho GmbH
        Created: 2025-03-17
        Updated: 2025-03-18
    #>

    param(
        # Shared secret used for HMAC signature (SecureString)
        [Parameter(Mandatory)][securestring]$SharedSecret,

        # Full webhook URL to which the request will be sent
        [Parameter(Mandatory)][string]$WebhookUrl,

        # Request body content as a string (usually JSON or similar)
        [Parameter(Mandatory)][string]$Body,

        # Algorithm to use for HMAC signature (default: HMACSHA256)
        [string]$Algorithm = "HMACSHA256",

        # Optional: Provide custom nonce (for testing/debugging); defaults to a new random GUID if omitted
        [string]$Nonce
    )

    if ($Algorithm -notin @('HMACSHA256', 'HMACSHA512')) {
        throw "Unsupported algorithm: $Algorithm"
    }

    # Parse URL components
    $uri = [System.Uri]$WebhookUrl
    $method = "POST"
    $path = $uri.AbsolutePath
    $webHost = $uri.Host

    # Timestamp header (RFC1123 format)
    $date = (Get-Date).ToUniversalTime().ToString("R")

    # Compute body hash (SHA256)
    $bodyBytes = [Text.Encoding]::UTF8.GetBytes($Body)
    $contentHash = [Convert]::ToBase64String(([System.Security.Cryptography.SHA256]::Create()).ComputeHash($bodyBytes))

    # Generate nonce if not provided
    if (-not $Nonce) {
        $Nonce = [Guid]::NewGuid().ToString()
    }

    # Define signed headers and order
    $signedHeadersList = @('x-ms-date', 'Host', 'x-ms-content-sha256', 'x-ms-nonce')
    $signedHeaders = ($signedHeadersList -join ';')

    # Build canonical message
    $canonicalMessage = "$method`n$path`n$date;$webHost;$contentHash;$Nonce"

    $unsecureSecret = $null
    try {
        $hmac = New-Object ("System.Security.Cryptography.$Algorithm")

        # SecureString → plaintext
        $unsecureSecret = [System.Net.NetworkCredential]::New("", $SharedSecret).Password

        # Set key and compute signature
        $hmac.Key = [Text.Encoding]::UTF8.GetBytes($unsecureSecret)
        $signature = [Convert]::ToBase64String($hmac.ComputeHash([Text.Encoding]::UTF8.GetBytes($canonicalMessage)))

        # Cleanup HMAC key
        [Array]::Clear($hmac.Key, 0, $hmac.Key.Length)
        $hmac = $null
    }
    finally {
        if ($unsecureSecret) {
            [Array]::Clear($unsecureSecret.ToCharArray(), 0, $unsecureSecret.Length)
            $unsecureSecret = $null
        }
    }

    # Prepare headers (Host excluded intentionally)
    $headers = @{
        'x-ms-date'           = $date
        'x-ms-content-sha256' = $contentHash
        'x-ms-nonce'          = $Nonce
        'x-authorization'     = "HMAC-$($Algorithm.Replace('HMAC','')) SignedHeaders=$signedHeaders&Signature=$signature"
    }

    return $headers
}