<#
.TITLE
    Restore Intune Configuration

.SYNOPSIS
    Restores Intune configuration profiles, compliance policies, ADMX policies, and platform scripts from a JSON backup created by backup-intune-configuration.

.DESCRIPTION
    This script reads a backup folder produced by backup-intune-configuration.ps1 and
    recreates the exported objects in the target tenant: device configuration profiles,
    settings catalog policies, compliance policies, administrative template (ADMX)
    policies with their definition values, and platform scripts. Objects are always
    created as new entries (no in-place overwrite), read-only properties are stripped
    from the payloads, and every create supports -WhatIf preview. Assignment restore is
    optional and off by default because group IDs from the source tenant may not exist
    in the target tenant.

.TAGS
    Configuration

.MINROLE
    Intune Administrator

.PERMISSIONS
    DeviceManagementConfiguration.ReadWrite.All

.EXECUTION
    LocalOnly

.AUTHOR
    Ugur Koc

.VERSION
    1.2

.CHANGELOG
    1.2 - Added Azure Automation contract validation, portal-safe boolean parameters, beta Graph endpoints, and terminating paging errors
    1.1 - Azure Automation now records script progress, outcomes, and summaries in job history
    1.0 - Initial release

.LASTUPDATE
    2026-07-30

.EXAMPLE
    .\restore-intune-configuration.ps1 -BackupPath ".\IntuneConfigBackup_2026-07-20_10-00-00" -WhatIf
    Previews everything that would be created without writing to the tenant

.EXAMPLE
    .\restore-intune-configuration.ps1 -BackupPath ".\IntuneConfigBackup_2026-07-20_10-00-00" -Areas CompliancePolicies
    Restores only the compliance policies from the backup

.EXAMPLE
    .\restore-intune-configuration.ps1 -BackupPath ".\IntuneConfigBackup_2026-07-20_10-00-00" -RestoreAssignments "true"
    Restores all areas including group assignments (same-tenant restore)

.NOTES
    - Requires Microsoft.Graph.Authentication module
    - Uses beta Graph endpoints because the full Intune configuration surface is not exposed on v1.0
    - Objects are created as new entries; existing policies with the same name are not touched, so a re-run creates duplicates
    - Compliance policies are created with their exported scheduledActionsForRule; if a backup predates that field, a default block rule is added because Graph rejects policies without one
    - Secret values (encrypted OMA-URI settings, passwords, certificates) are never present in Graph exports and must be re-entered manually after restore
    - ADMX presentation values referencing definitions that do not exist in the target tenant are skipped with a warning
    - Assignment restore requires the original group IDs to exist in the target tenant; failures are reported per policy and do not stop the restore
    - Local interactive sign-in uses the MgGraphCommunity module to avoid the Graph SDK's mandatory WAM broker on Windows
#>

[CmdletBinding(SupportsShouldProcess = $true)]
param(
    [Parameter(Mandatory = $true, HelpMessage = "Path to a folder created by backup-intune-configuration.ps1")]
    [ValidateNotNullOrEmpty()]
    [string]$BackupPath,

    [Parameter(Mandatory = $false, HelpMessage = "Configuration areas to restore")]
    [ValidateSet("DeviceConfigurations", "SettingsCatalog", "CompliancePolicies", "AdmxPolicies", "PlatformScripts")]
    [string[]]$Areas = @("DeviceConfigurations", "SettingsCatalog", "CompliancePolicies", "AdmxPolicies", "PlatformScripts"),

    [Parameter(Mandatory = $false, HelpMessage = "Also restore group assignments (requires source group IDs to exist)")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$RestoreAssignments,

    [Parameter(Mandatory = $false, HelpMessage = "Prefix added to restored object names, e.g. 'Restored - '")]
    [string]$NamePrefix = "",

    [Parameter(Mandatory = $false, HelpMessage = "Force module installation without prompting")]
    [ValidateSet("true", "false", "1", "0", '$true', '$false')]
    [string]$ForceModuleInstall
)

# Normalize the local module-install override for Azure Automation parameter binding.
$forceModuleInstallRaw = [string]$ForceModuleInstall
Remove-Variable -Name ForceModuleInstall
if ([string]::IsNullOrWhiteSpace($forceModuleInstallRaw)) {
    $ForceModuleInstall = $false
}
elseif ($forceModuleInstallRaw.Trim().ToLowerInvariant() -in @("true", "1", '$true')) {
    $ForceModuleInstall = $true
}
elseif ($forceModuleInstallRaw.Trim().ToLowerInvariant() -in @("false", "0", '$false')) {
    $ForceModuleInstall = $false
}
else {
    throw "Parameter 'ForceModuleInstall' accepts only true, false, 1, 0, $true, or $false."
}

# Azure Automation supplies portal parameter values as strings. Normalize the
# public boolean parameters once so local and runbook execution use real booleans.
foreach ($runbookBooleanParameter in @('RestoreAssignments')) {
    $runbookBooleanRaw = [string](Get-Variable -Name $runbookBooleanParameter -ValueOnly)
    Remove-Variable -Name $runbookBooleanParameter

    if ([string]::IsNullOrWhiteSpace($runbookBooleanRaw)) {
        Set-Variable -Name $runbookBooleanParameter -Value $false
        continue
    }

    switch ($runbookBooleanRaw.Trim().ToLowerInvariant()) {
        { $_ -in @("true", "1", '$true') } {
            Set-Variable -Name $runbookBooleanParameter -Value $true
        }
        { $_ -in @("false", "0", '$false') } {
            Set-Variable -Name $runbookBooleanParameter -Value $false
        }
        default {
            throw "Parameter '$runbookBooleanParameter' accepts only true, false, 1, 0, $true, or $false."
        }
    }
}

# ============================================================================
# ENVIRONMENT DETECTION AND SETUP
# ============================================================================

function Initialize-RequiredModule {
    param(
        [string[]]$ModuleNames,
        [bool]$IsAutomationEnvironment,
        [bool]$ForceInstall = $false
    )

    foreach ($ModuleName in $ModuleNames) {
        Write-Verbose "Checking module: $ModuleName"

        $module = Get-Module -ListAvailable -Name $ModuleName | Select-Object -First 1

        if (-not $module) {
            if ($IsAutomationEnvironment) {
                throw "Module '$ModuleName' is not available in Azure Automation"
            }
            else {
                Write-Information "Module '$ModuleName' not found. Installing..." -InformationAction Continue

                if (-not $ForceInstall) {
                    $response = Read-Host "Install module '$ModuleName'? (Y/N)"
                    if ($response -notmatch '^[Yy]') {
                        throw "Module '$ModuleName' is required but installation was declined."
                    }
                }

                try {
                    $isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] "Administrator")
                    $scope = if ($isAdmin) { "AllUsers" } else { "CurrentUser" }

                    Install-Module -Name $ModuleName -Scope $scope -Force -AllowClobber -Repository PSGallery
                    Write-Information "✓ Successfully installed '$ModuleName'" -InformationAction Continue
                }
                catch {
                    throw "Failed to install module '$ModuleName': $($_.Exception.Message)"
                }
            }
        }

        Import-Module -Name $ModuleName -Force -ErrorAction Stop
    }
}

# Detect execution environment
$IsAzureAutomation = $null -ne $PSPrivateMetadata.JobId.Guid

# Initialize required modules
$RequiredModules = @("Microsoft.Graph.Authentication")

# MgGraphCommunity gives WAM-free interactive sign-in for local runs
if (-not $IsAzureAutomation) {
    $RequiredModules += "MgGraphCommunity"
}

try {
    Initialize-RequiredModule -ModuleNames $RequiredModules -IsAutomationEnvironment $IsAzureAutomation -ForceInstall $ForceModuleInstall
    Write-Verbose "✓ All required modules are available"
}
catch {
    Write-Error "Module initialization failed: $_"
    exit 1
}

# ============================================================================
# AUTHENTICATION
# ============================================================================

try {
    if ($IsAzureAutomation) {
        Write-Output "Connecting to Microsoft Graph using Managed Identity..."
        Connect-MgGraph -Identity -NoWelcome -ErrorAction Stop
    }
    else {
        Write-Output "Connecting to Microsoft Graph..."
        $Scopes = @(
            "DeviceManagementConfiguration.ReadWrite.All"
        )
        Connect-MgGraphCommunity -Scopes $Scopes -NoWelcome -ErrorAction Stop
    }
    Write-Output "✓ Successfully connected to Microsoft Graph"
}
catch {
    Write-Error "Failed to connect to Microsoft Graph: $($_.Exception.Message)"
    exit 1
}

# ============================================================================
# HELPER FUNCTIONS
# ============================================================================

function ConvertTo-Hashtable {
    param([object]$InputObject)

    # ConvertFrom-Json gives PSCustomObjects; Graph payloads are easier to
    # sanitize as nested hashtables
    if ($null -eq $InputObject) { return $null }

    if ($InputObject -is [System.Collections.IEnumerable] -and $InputObject -isnot [string]) {
        return @($InputObject | ForEach-Object { ConvertTo-Hashtable -InputObject $_ })
    }

    if ($InputObject -is [PSCustomObject]) {
        $hash = [ordered]@{}
        foreach ($property in $InputObject.PSObject.Properties) {
            $hash[$property.Name] = ConvertTo-Hashtable -InputObject $property.Value
        }
        return $hash
    }

    return $InputObject
}

function Remove-ReadOnlyProperty {
    param(
        [hashtable]$Payload,
        [string[]]$ExtraProperties = @()
    )

    $readOnly = @(
        "id", "createdDateTime", "lastModifiedDateTime", "version",
        "assignments", "assignments@odata.context", "@odata.context",
        "settingCount", "priorityMetaData", "supportsScopeTags",
        "creationSource", "policyConfigurationIngestionType",
        "scriptSurface", "definitionValues", "settings@odata.context"
    ) + $ExtraProperties

    foreach ($property in $readOnly) {
        $Payload.Remove($property)
    }

    # Expanded navigation annotations (xyz@odata.context) are metadata, not payload
    foreach ($key in @($Payload.Keys)) {
        if ($key -like "*@odata.context" -or $key -like "*@odata.count") {
            $Payload.Remove($key)
        }
    }

    return $Payload
}

function Invoke-AssignmentRestore {
    param(
        [string]$AssignUri,
        [string]$AssignmentsPropertyName,
        [object[]]$Assignments,
        [string]$DisplayName
    )

    if (-not $Assignments -or @($Assignments).Count -eq 0) {
        return
    }

    $cleanAssignments = foreach ($assignment in $Assignments) {
        $a = ConvertTo-Hashtable -InputObject $assignment
        $a.Remove("id")
        $a.Remove("sourceId")
        $a
    }

    $body = @{ $AssignmentsPropertyName = @($cleanAssignments) }

    try {
        $null = Invoke-MgGraphRequest -Uri $AssignUri -Method POST -Body ($body | ConvertTo-Json -Depth 15) -ContentType "application/json"
        Write-Information "  ✓ Restored $(@($cleanAssignments).Count) assignments for '$DisplayName'" -InformationAction Continue
    }
    catch {
        Write-Warning "  Could not restore assignments for '$DisplayName' (groups may not exist in this tenant): $($_.Exception.Message)"
    }
}

function Get-BackupFile {
    param([string]$AreaFolder)

    $folder = Join-Path $BackupPath $AreaFolder
    if (-not (Test-Path $folder)) {
        Write-Warning "Backup folder '$AreaFolder' not found in $BackupPath - skipping"
        return @()
    }

    return @(Get-ChildItem -Path $folder -Filter "*.json" -File)
}

# ============================================================================
# MAIN SCRIPT LOGIC
# ============================================================================

try {
    if (-not (Test-Path $BackupPath)) {
        throw "Backup path '$BackupPath' does not exist"
    }

    Write-Output "Starting Intune configuration restore from: $BackupPath"

    $restored = 0
    $failed = 0

    # ----- Classic device configuration profiles -----
    if ($Areas -contains "DeviceConfigurations") {
        foreach ($file in (Get-BackupFile -AreaFolder "DeviceConfigurations")) {
            $source = Get-Content -Path $file.FullName -Raw | ConvertFrom-Json
            $displayName = "$NamePrefix$($source.displayName)"
            $assignments = $source.assignments

            $payload = Remove-ReadOnlyProperty -Payload (ConvertTo-Hashtable -InputObject $source)
            $payload.displayName = $displayName

            if ($PSCmdlet.ShouldProcess($displayName, "Create device configuration profile")) {
                try {
                    $created = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/deviceConfigurations" -Method POST -Body ($payload | ConvertTo-Json -Depth 25) -ContentType "application/json"
                    Write-Output "✓ Created profile: $displayName"
                    $restored++

                    if ($RestoreAssignments) {
                        Invoke-AssignmentRestore -AssignUri "https://graph.microsoft.com/beta/deviceManagement/deviceConfigurations/$($created.id)/assign" -AssignmentsPropertyName "assignments" -Assignments $assignments -DisplayName $displayName
                    }
                }
                catch {
                    Write-Warning "Failed to create profile '$displayName': $($_.Exception.Message)"
                    $failed++
                }
            }
        }
    }

    # ----- Settings catalog policies -----
    if ($Areas -contains "SettingsCatalog") {
        foreach ($file in (Get-BackupFile -AreaFolder "SettingsCatalog")) {
            $source = Get-Content -Path $file.FullName -Raw | ConvertFrom-Json
            $displayName = "$NamePrefix$($source.name)"
            $assignments = $source.assignments

            $settings = foreach ($setting in @($source.settings)) {
                $s = ConvertTo-Hashtable -InputObject $setting
                $s.Remove("id")
                $s
            }

            $payload = @{
                name         = $displayName
                description  = [string]$source.description
                platforms    = $source.platforms
                technologies = $source.technologies
                settings     = @($settings)
            }
            if ($source.roleScopeTagIds) { $payload.roleScopeTagIds = @($source.roleScopeTagIds) }
            if ($source.templateReference -and $source.templateReference.templateId) {
                $payload.templateReference = @{ templateId = $source.templateReference.templateId }
            }

            if ($PSCmdlet.ShouldProcess($displayName, "Create settings catalog policy")) {
                try {
                    $created = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/configurationPolicies" -Method POST -Body ($payload | ConvertTo-Json -Depth 30) -ContentType "application/json"
                    Write-Output "✓ Created settings catalog policy: $displayName"
                    $restored++

                    if ($RestoreAssignments) {
                        Invoke-AssignmentRestore -AssignUri "https://graph.microsoft.com/beta/deviceManagement/configurationPolicies/$($created.id)/assign" -AssignmentsPropertyName "assignments" -Assignments $assignments -DisplayName $displayName
                    }
                }
                catch {
                    Write-Warning "Failed to create settings catalog policy '$displayName': $($_.Exception.Message)"
                    $failed++
                }
            }
        }
    }

    # ----- Compliance policies -----
    if ($Areas -contains "CompliancePolicies") {
        foreach ($file in (Get-BackupFile -AreaFolder "CompliancePolicies")) {
            $source = Get-Content -Path $file.FullName -Raw | ConvertFrom-Json
            $displayName = "$NamePrefix$($source.displayName)"
            $assignments = $source.assignments

            $payload = Remove-ReadOnlyProperty -Payload (ConvertTo-Hashtable -InputObject $source) -ExtraProperties @("deviceCompliancePolicyScript")
            $payload.displayName = $displayName

            # Graph rejects compliance policies created without a scheduled action rule
            if ($payload.scheduledActionsForRule) {
                $payload.scheduledActionsForRule = @(foreach ($rule in @($payload.scheduledActionsForRule)) {
                        $rule.Remove("id")
                        if ($rule.scheduledActionConfigurations) {
                            $rule.scheduledActionConfigurations = @(foreach ($config in @($rule.scheduledActionConfigurations)) {
                                    $config.Remove("id")
                                    $config
                                })
                        }
                        $rule
                    })
            }
            else {
                $payload.scheduledActionsForRule = @(
                    @{
                        ruleName                      = "PasswordRequired"
                        scheduledActionConfigurations = @(
                            @{ actionType = "block"; gracePeriodHours = 0; notificationTemplateId = ""; notificationMessageCCList = @() }
                        )
                    }
                )
            }

            if ($PSCmdlet.ShouldProcess($displayName, "Create compliance policy")) {
                try {
                    $created = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies" -Method POST -Body ($payload | ConvertTo-Json -Depth 25) -ContentType "application/json"
                    Write-Output "✓ Created compliance policy: $displayName"
                    $restored++

                    if ($RestoreAssignments) {
                        Invoke-AssignmentRestore -AssignUri "https://graph.microsoft.com/beta/deviceManagement/deviceCompliancePolicies/$($created.id)/assign" -AssignmentsPropertyName "assignments" -Assignments $assignments -DisplayName $displayName
                    }
                }
                catch {
                    Write-Warning "Failed to create compliance policy '$displayName': $($_.Exception.Message)"
                    $failed++
                }
            }
        }
    }

    # ----- Administrative template (ADMX) policies -----
    if ($Areas -contains "AdmxPolicies") {
        foreach ($file in (Get-BackupFile -AreaFolder "AdmxPolicies")) {
            $source = Get-Content -Path $file.FullName -Raw | ConvertFrom-Json
            $displayName = "$NamePrefix$($source.displayName)"
            $assignments = $source.assignments

            $payload = @{
                displayName = $displayName
                description = [string]$source.description
            }

            if ($PSCmdlet.ShouldProcess($displayName, "Create administrative template policy")) {
                try {
                    $created = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/groupPolicyConfigurations" -Method POST -Body ($payload | ConvertTo-Json) -ContentType "application/json"
                    Write-Output "✓ Created administrative template policy: $displayName"
                    $restored++

                    # Definition values are created one by one against the new policy
                    foreach ($definitionValue in @($source.definitionValues)) {
                        if (-not $definitionValue.definition -or -not $definitionValue.definition.id) {
                            Write-Warning "  Skipping a definition value without definition reference in '$displayName'"
                            continue
                        }

                        $dvPayload = @{
                            enabled                 = [bool]$definitionValue.enabled
                            "definition@odata.bind" = "https://graph.microsoft.com/beta/deviceManagement/groupPolicyDefinitions('$($definitionValue.definition.id)')"
                        }

                        if ($definitionValue.presentationValues) {
                            $dvPayload.presentationValues = @(foreach ($presentationValue in @($definitionValue.presentationValues)) {
                                    $pv = ConvertTo-Hashtable -InputObject $presentationValue
                                    $presentationId = $null
                                    if ($presentationValue.presentation -and $presentationValue.presentation.id) {
                                        $presentationId = $presentationValue.presentation.id
                                    }
                                    $pv.Remove("id")
                                    $pv.Remove("createdDateTime")
                                    $pv.Remove("lastModifiedDateTime")
                                    $pv.Remove("presentation")
                                    if ($presentationId) {
                                        $pv["presentation@odata.bind"] = "https://graph.microsoft.com/beta/deviceManagement/groupPolicyDefinitions('$($definitionValue.definition.id)')/presentations('$presentationId')"
                                    }
                                    $pv
                                })
                        }

                        try {
                            $null = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/groupPolicyConfigurations/$($created.id)/definitionValues" -Method POST -Body ($dvPayload | ConvertTo-Json -Depth 15) -ContentType "application/json"
                        }
                        catch {
                            Write-Warning "  Could not restore setting '$($definitionValue.definition.displayName)' in '$displayName': $($_.Exception.Message)"
                        }
                    }

                    if ($RestoreAssignments) {
                        Invoke-AssignmentRestore -AssignUri "https://graph.microsoft.com/beta/deviceManagement/groupPolicyConfigurations/$($created.id)/assign" -AssignmentsPropertyName "assignments" -Assignments $assignments -DisplayName $displayName
                    }
                }
                catch {
                    Write-Warning "Failed to create administrative template policy '$displayName': $($_.Exception.Message)"
                    $failed++
                }
            }
        }
    }

    # ----- Platform scripts -----
    if ($Areas -contains "PlatformScripts") {
        foreach ($file in (Get-BackupFile -AreaFolder "PlatformScripts")) {
            $source = Get-Content -Path $file.FullName -Raw | ConvertFrom-Json
            $displayName = "$NamePrefix$($source.displayName)"
            $assignments = $source.assignments
            $surface = if ($source.scriptSurface) { $source.scriptSurface } else { "deviceManagementScripts" }

            if (-not $source.scriptContent) {
                Write-Warning "Skipping platform script '$displayName': backup contains no script content (was -SkipScriptContent used?)"
                continue
            }

            $payload = Remove-ReadOnlyProperty -Payload (ConvertTo-Hashtable -InputObject $source)
            $payload.displayName = $displayName

            if ($PSCmdlet.ShouldProcess($displayName, "Create platform script ($surface)")) {
                try {
                    $created = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/deviceManagement/$surface" -Method POST -Body ($payload | ConvertTo-Json -Depth 10) -ContentType "application/json"
                    Write-Output "✓ Created platform script: $displayName"
                    $restored++

                    if ($RestoreAssignments) {
                        # Both script surfaces use the same assign action property name
                        Invoke-AssignmentRestore -AssignUri "https://graph.microsoft.com/beta/deviceManagement/$surface/$($created.id)/assign" -AssignmentsPropertyName "deviceManagementScriptAssignments" -Assignments $assignments -DisplayName $displayName
                    }
                }
                catch {
                    Write-Warning "Failed to create platform script '$displayName': $($_.Exception.Message)"
                    $failed++
                }
            }
        }
    }

    # ----- Summary -----
    Write-Output "`n========================================"
    Write-Output "Restore Summary"
    Write-Output "========================================"
    Write-Output "Objects created: $restored"
    Write-Output "Objects failed:  $failed"
    Write-Output "========================================"

    if ($failed -gt 0) {
        Write-Warning "Some objects failed to restore - review the warnings above"
    }
}
catch {
    Write-Error "Script execution failed: $($_.Exception.Message)"
    exit 1
}
finally {
    try {
        $null = Disconnect-MgGraph
        Write-Output "✓ Disconnected from Microsoft Graph"
    }
    catch {
        Write-Verbose "Graph disconnection completed"
    }
}

# Copia sin cambios de https://github.com/ugurkocde/IntuneAutomation (commit 797bb2e).
# MIT License
#
# Copyright (c) 2025 Ugur Koc | Microsoft MVP
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.