Use PowerShell to install the Global Secure Access Windows client as a proof of concept

To test the Global Secure Access Windows client as a proof of concept, use this script to automate the installation of the Global Secure Access client for Windows for proof-of-concept deployments. This script performs the following actions:

Detects whether the Global Secure Access client is already installed. If not, the script installs the correct Global Secure Access client (Arm vs x86) depending on the detected Windows architecture.
Sets several registry keys that configure the following settings:
- Sets IPv4Preferred to prefer IPv4 over IPv6 traffic.
- Sets FarKdcTimeout to 0 to avoid Kerberos Negative Caching.
- Increases the Transmission Control Protocol (TCP) connection timeout threshold to 60 seconds to allow time to complete MFA during Remote Desktop Protocol (RDP) connection attempts.
- Unhides several buttons in the Global Secure Access client.
- Disables Domain Name System (DNS) over HTTPS in Microsoft Edge and Chrome browsers (if the corresponding browser is present).
- Disables QUIC in Microsoft Edge and Chrome browsers (if the corresponding browser is present).
Creates a policy.json file in the Firefox folder to disable DNS over HTTPS and QUIC if Firefox is present.
Prompts for a device reboot if the script changes the registry key for IPv4Preferred (the registry change doesn't take effect until the device reboots).

# --- Helper: Admin check ---
function Test-IsAdmin {
    $id = [Security.Principal.WindowsIdentity]::GetCurrent()
    $pr = New-Object Security.Principal.WindowsPrincipal($id)
    return $pr.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
}
if (-not (Test-IsAdmin)) {
    Write-Host "This script must be run as Administrator. Please right-click and select 'Run as Administrator' before trying again." -ForegroundColor Red
    exit 1
}
# --- Config ---
$ReleaseHistoryUrl = "https://learn.microsoft.com/entra/global-secure-access/reference-windows-client-release-history"
$DownloadUrlX64    = "https://aka.ms/GlobalSecureAccess-Windows"
$DownloadUrlARM    = "https://aka.ms/GlobalSecureAccess-WindowsOnArm"
$InstallerPath     = Join-Path $env:TEMP "GSAClient.exe"
$ExePath           = "C:\Program Files\Global Secure Access Client\GlobalSecureAccessEngineService.exe"
# Registry settings for Global Secure Access client, Edge DoH/QUIC, Chrome DoH/QUIC
$RegistrySettings = @(
    # Global Secure Access-related keys
    @{ Key="HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters"; Name="DisabledComponents"; Type="DWord"; Value=0x20 },
    @{ Key="HKLM:\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters"; Name="FarKdcTimeout"; Type="DWord"; Value=0 },
    @{ Key="HKLM:\Software\Microsoft\Terminal Server Client"; Name="TimeoutTcpDirectConnection"; Type="DWord"; Value=60 },
    @{ Key="HKLM:\Software\Microsoft\Global Secure Access Client"; Name="HideDisablePrivateAccessButton"; Type="DWord"; Value=0 },
    @{ Key="HKLM:\Software\Microsoft\Global Secure Access Client"; Name="HideDisableButton"; Type="DWord"; Value=0 },
    @{ Key="HKLM:\Software\Microsoft\Global Secure Access Client"; Name="HideSignOutButton"; Type="DWord"; Value=0 },
    # Edge DoH and QUIC settings
    @{ Key="HKLM:\SOFTWARE\Policies\Microsoft\Edge"; Name="BuiltInDnsClientEnabled"; Type="DWord"; Value=0 },
    @{ Key="HKLM:\SOFTWARE\Policies\Microsoft\Edge"; Name="QuicAllowed"; Type="DWord"; Value=0 },
    # Chrome DoH and QUIC settings
    @{ Key="HKLM:\SOFTWARE\Policies\Google\Chrome"; Name="DnsOverHttpsMode"; Type="String"; Value="off" },
    @{ Key="HKLM:\SOFTWARE\Policies\Google\Chrome"; Name="QuicAllowed"; Type="DWord"; Value=0 }
)
# --- Track whether the IPv4-preferred setting was already correct ---
# We will only prompt for reboot if this value needed to change.
$Ipv6ParamsKey                 = "HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters"
$Ipv4PrefValueName             = "DisabledComponents"
$Ipv4PrefDesired               = 0x20
$WasIpv4PreferredAlreadyCorrect = $false
try {
    $prop = Get-ItemProperty -Path $Ipv6ParamsKey -Name $Ipv4PrefValueName -ErrorAction Stop
    $WasIpv4PreferredAlreadyCorrect = ([int64]$prop.$Ipv4PrefValueName -eq [int64]$Ipv4PrefDesired)
} catch {
    $WasIpv4PreferredAlreadyCorrect = $false
}
if (-not (Test-IsAdmin)) {
    Write-Error "This script must be run as Administrator."
    exit 1
}
# --- Helper: Enforce registry key value ---
function Ensure-RegistryValue {
    param(
        [Parameter(Mandatory)] [string] $Key,
        [Parameter(Mandatory)] [string] $Name,
        [Parameter(Mandatory)] [ValidateSet('String','ExpandString','Binary','DWord','MultiString','QWord')]
        [string] $Type,
        [Parameter(Mandatory)] $Value
    )
    if (-not (Test-Path -Path $Key)) {
        New-Item -Path $Key -Force | Out-Null
        Write-Host "Created key: $Key" -ForegroundColor DarkCyan
    }
    $hasValue = $false
    $current = $null
    try {
        $prop = Get-ItemProperty -Path $Key -Name $Name -ErrorAction Stop
        $current = $prop.$Name
        $hasValue = $true
    } catch { }
    $needsSet = $true
    if ($hasValue) {
        if ($Type -in @('DWord','QWord')) {
            $needsSet = ([int64]$Value -ne [int64]$current)
        } else {
            $needsSet = ($Value -ne $current)
        }
    }
    if (-not $hasValue) {
        New-ItemProperty -Path $Key -Name $Name -PropertyType $Type -Value $Value -Force | Out-Null
        Write-Host "Created value: $Key\$Name = $Value ($Type)" -ForegroundColor Green
    } elseif ($needsSet) {
        Set-ItemProperty -Path $Key -Name $Name -Value $Value
        Write-Host "Updated value: $Key\$Name from '$current' to '$Value'" -ForegroundColor Yellow
    } else {
        Write-Host "Already correct: $Key\$Name = $Value" -ForegroundColor Gray
    }
}
# --- Check for installed browsers (Edge, Chrome, Firefox) ---
function Get-InstalledApp {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Name
    )
    $registryPaths = @(
        'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*',
        'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*',
        'HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*'
    )
    $results = @()
    foreach ($path in $registryPaths) {
        try {
            $items = Get-ItemProperty -Path $path -ErrorAction SilentlyContinue |
                Where-Object { $_.DisplayName -and ($_.DisplayName -like "*$Name*" -or $_.DisplayName -eq $Name) } |
                Select-Object DisplayName, DisplayVersion, Publisher, InstallDate, InstallLocation
            if ($items) { $results += $items }
        } catch { }
    }
    return $results
}
# --- Check if Global Secure Access client already installed and install if not present ---
if (Test-Path $ExePath) {
    Write-Host "GSA Client executable is present." -ForegroundColor Green
    try {
        $fileVersion = (Get-Item $ExePath).VersionInfo.ProductVersion
        Write-Host "Current version is $fileVersion. Please check $ReleaseHistoryUrl to make sure your client is the most up-to-date." -ForegroundColor Cyan
    } catch {
        Write-Host "Could not retrieve version info. Please check $ReleaseHistoryUrl manually to make sure your client is the most up-to-date." -ForegroundColor Yellow
    }
} else {
    Write-Host "GSA Client executable is NOT found. Proceeding with installation..." -ForegroundColor Yellow
    $isArm = $env:PROCESSOR_ARCHITECTURE -match 'ARM'
    $downloadUrl = if ($isArm) { $DownloadUrlARM } else { $DownloadUrlX64 }
    $archLabel   = if ($isArm) { 'ARM64' } else { 'x64' }
    try {
        Write-Host "Downloading GSA client for $archLabel..." -ForegroundColor Green
        Invoke-WebRequest -Uri $downloadUrl -OutFile $InstallerPath -UseBasicParsing
        Write-Host "Installing GSA client..." -ForegroundColor Green
        Start-Process -FilePath $InstallerPath -ArgumentList @('/quiet','/norestart') -Wait -WindowStyle Hidden
        Write-Host "Installation complete." -ForegroundColor Green
    }
    catch {
        Write-Error "Failed to download or install the GSA client. $_"
        if (Test-Path $InstallerPath) { Remove-Item $InstallerPath -Force }
        exit 1
    }
    finally {
        if (Test-Path $InstallerPath) { Remove-Item $InstallerPath -Force }
    }
    if (Test-Path $ExePath) {
        $fileVersion = (Get-Item $ExePath).VersionInfo.ProductVersion
        Write-Host "Installed version is $fileVersion." -ForegroundColor Cyan
    }
}
# --- Enforce registry keys ---
Write-Host "`nEnforcing required registry values..." -ForegroundColor Magenta
# 1) Always apply NON-browser (Global Secure Access) keys exactly as before
$nonBrowserSettings = $RegistrySettings | Where-Object {
    $_.Key -notmatch '\\Policies\\Microsoft\\Edge' -and $_.Key -notmatch '\\Policies\\Google\\Chrome'
}
foreach ($rk in $nonBrowserSettings) {
    Ensure-RegistryValue -Key $rk.Key -Name $rk.Name -Type $rk.Type -Value $rk.Value
}
# 2) Detect browsers via registry only 
$edgeFound    = Get-InstalledApp -Name 'Microsoft Edge'
$chromeFound  = Get-InstalledApp -Name 'Google Chrome'
$firefoxFound = Get-InstalledApp -Name 'Firefox'  # also catches "Mozilla Firefox"
Write-Host ""
Write-Host "Browser detection:" -ForegroundColor Cyan
Write-Host (" - Microsoft Edge : {0}"  -f ($(if ($edgeFound)   {'FOUND'} else {'Not installed'})))  -ForegroundColor $(if ($edgeFound) {'Green'} else {'Yellow'})
Write-Host (" - Google Chrome  : {0}"  -f ($(if ($chromeFound) {'FOUND'} else {'Not installed'})))  -ForegroundColor $(if ($chromeFound){'Green'} else {'Yellow'})
Write-Host (" - Firefox        : {0}"  -f ($(if ($firefoxFound){'FOUND'} else {'Not installed'})))  -ForegroundColor $(if ($firefoxFound){'Green'} else {'Yellow'})
# 3) Apply Edge policy keys only if Edge present
$edgeSettings = $RegistrySettings | Where-Object { $_.Key -match '\\Policies\\Microsoft\\Edge' }
if ($edgeFound) {
    Write-Host "`nApplying Microsoft Edge policy keys (DoH/QUIC)..." -ForegroundColor Cyan
    foreach ($rk in $edgeSettings) {
        Ensure-RegistryValue -Key $rk.Key -Name $rk.Name -Type $rk.Type -Value $rk.Value
    }
} else {
    Write-Host "Skipping Edge policy keys (Edge not detected)." -ForegroundColor DarkYellow
}
# 4) Apply Chrome policy keys only if Chrome present
$chromeSettings = $RegistrySettings | Where-Object { $_.Key -match '\\Policies\\Google\\Chrome' }
if ($chromeFound) {
    Write-Host "`nApplying Google Chrome policy keys (DoH/QUIC)..." -ForegroundColor Cyan
    foreach ($rk in $chromeSettings) {
        Ensure-RegistryValue -Key $rk.Key -Name $rk.Name -Type $rk.Type -Value $rk.Value
    }
} else {
    Write-Host "Skipping Chrome policy keys (Chrome not detected)." -ForegroundColor DarkYellow
}
Write-Host "`nGSA keys applied. Edge and Chrome browser policy keys applied only when detected." -ForegroundColor Cyan
# Firefox policies.json: disable QUIC (HTTP/3) and DoH only if Firefox present
if ($firefoxFound) {
    # Prefer existing Firefox install path; fall back to Program Files
    $ffBaseDirs = @(
        "C:\Program Files\Mozilla Firefox",
        "C:\Program Files (x86)\Mozilla Firefox"
    )
    $ffBaseDir = $ffBaseDirs | Where-Object { Test-Path $_ } | Select-Object -First 1
    if (-not $ffBaseDir) { $ffBaseDir = "C:\Program Files\Mozilla Firefox" }
    $distributionDir = Join-Path $ffBaseDir "distribution"
    $destination     = Join-Path $distributionDir "policies.json"
    $backup          = "$destination.bak"
    # Ensure distribution directory exists
    if (-not (Test-Path $distributionDir)) {
        New-Item -ItemType Directory -Path $distributionDir -Force | Out-Null
    }
    # Load existing JSON if present
    $existingJson = $null
    if (Test-Path $destination) {
        $fileContent = Get-Content $destination -Raw -ErrorAction SilentlyContinue
        if ($fileContent -and $fileContent.Trim().Length -gt 0) {
            try {
                $existingJson = $fileContent | ConvertFrom-Json -ErrorAction Stop
            } catch {
                Write-Warning "Existing policies.json is malformed at '$destination'. Starting fresh."
            }
        }
    }
    # Create base structure if needed
    if (-not $existingJson) {
        $existingJson = [PSCustomObject]@{
            policies = [PSCustomObject]@{
                Preferences = @{}
            }
        }
    }
    # Ensure nodes exist
    if (-not $existingJson.policies) {
        $existingJson | Add-Member -MemberType NoteProperty -Name policies -Value ([PSCustomObject]@{}) -Force
    }
    if (-not $existingJson.policies.Preferences) {
        $existingJson.policies | Add-Member -MemberType NoteProperty -Name Preferences -Value @{} -Force
    }
    # Normalize Preferences to hashtable for safe merging
    if ($existingJson.policies.Preferences -isnot [hashtable]) {
        $prefs = @{}
        $existingJson.policies.Preferences.psobject.Properties | ForEach-Object {
            $prefs[$_.Name] = $_.Value
        }
        $existingJson.policies.Preferences = $prefs
    }
    $prefs   = $existingJson.policies.Preferences
    $updated = $false
    # Disable QUIC (HTTP/3)
    if (-not $prefs.ContainsKey("network.http.http3.enable") -or
        $prefs["network.http.http3.enable"].Value  -ne $false) {
        $prefs["network.http.http3.enable"] = @{
            Value  = $false
        }
        $updated = $true
    }
    # Disable DNS-over-HTTPS (TRR mode 0 per your baseline)
    if (-not $prefs.ContainsKey("network.trr.mode") -or
        $prefs["network.trr.mode"].Value  -ne 0) {
        $prefs["network.trr.mode"] = @{
            Value  = 0
        }
        $updated = $true
    }
    # Write if updated (backup existing first)
    if ($updated) {
        if (Test-Path $destination) {
            Copy-Item -Path $destination -Destination $backup -Force
        }
        $jsonOut  = $existingJson | ConvertTo-Json -Depth 10 -Compress
        $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
        [System.IO.File]::WriteAllText($destination, $jsonOut, $utf8NoBom)
        Write-Host "QUIC and DoH disabled in Firefox. Firefox policies.json updated at '$destination'." -ForegroundColor Green
    } else {
        Write-Host "Firefox policies.json already contains required settings at '$destination'." -ForegroundColor Gray
    }
} else {
    Write-Host "Skipping Firefox policies.json (Firefox not detected)." -ForegroundColor DarkYellow
}
# --- Decide whether to prompt for reboot based on DisabledComponents change (IPv4Preferred) ---
$NowIpv4PreferredCorrect = $false
try {
    $prop = Get-ItemProperty -Path $Ipv6ParamsKey -Name $Ipv4PrefValueName -ErrorAction Stop
    $NowIpv4PreferredCorrect = ([int64]$prop.$Ipv4PrefValueName -eq [int64]$Ipv4PrefDesired)
} catch {
    $NowIpv4PreferredCorrect = $false
}
$PromptForReboot = (-not $WasIpv4PreferredAlreadyCorrect) -and $NowIpv4PreferredCorrect
if ($PromptForReboot) {
    # Prompt for reboot at the end ONLY if the DisabledComponents value was changed by this script
    $choice = Read-Host "Change of the IPv4Preffered registry key won't take effect until device reboot. Do you want to reboot now? (Y/N)"
    if ($choice -match '^[Yy]$') {
        Write-Host "Rebooting system..."
        Restart-Computer -Force
    } else {
        Write-Host "Reboot skipped by user."
    }
} else {
    # If the value was already correct before, don't prompt—just inform
    Write-Host "IPv4Preferred is already configured correctly. No reboot is required." -ForegroundColor Green
}

Install the Global Secure Access client for Microsoft Windows

Feedback

Was this page helpful?

Last updated on 2025-11-19

Use PowerShell to install the Global Secure Access Windows client as a proof of concept

Related content

Feedback

Additional resources