GSA Windows client prerequisites and installation

This page's changes and edits · All guidance changes

Microsoft's edit · 6 Nov 18:34 UTC

Use Custom Acquire and cloud firewall instead of disabling browser QUIC (#14776)

Microsoft's commit message in MicrosoftDocs/entra-docs · commit 866f302 · +59 ~~−46~~ lines · also on GitHub

Inline diff Before After

⋯ 1 unchanged line

22 title: Install the Global Secure Access Client for Windows

33 description: The Global Secure Access client helps secure network traffic at the user device. This article describes how to download and install the Windows client.

44 ms.topic: how-to

5 −ms.date: 02/02/2026

5 +ms.date: 11/03/2026

66 ms.reviewer: lirazbarak

77 ai-usage: ai-assisted

88 ms.custom: sfi-image-nochange

⋯ 410 unchanged lines

419419

420420 </details>

421421

422 +### Control QUIC with cloud firewall

423 +

424 +Keep QUIC enabled in users' browsers. To prevent QUIC connections from bypassing Microsoft Entra Internet Access inspection, use **Custom Acquire** to acquire UDP traffic on destination port `443` for the intended destinations, and use a cloud firewall **Block** rule for the same traffic. Keep **Default Acquire** enabled for TCP ports `80` and `443` so that applications that support fallback can connect over HTTPS using TCP.

425 +

426 +> [!NOTE]

427 +> This example acquires and blocks UDP port `443`, commonly used for HTTP/3 over QUIC. [RFC 9114, section 3.1](https://www.rfc-editor.org/rfc/rfc9114.html#section-3.1) permits HTTP/3 on any UDP port. If applications or servers use other destination ports, configure corresponding traffic acquisition and cloud firewall block rules. Blocking UDP port `443` alone doesn't block QUIC on other ports.

428 +

429 +Link the cloud firewall policy to a security profile, enable the policy link, and apply the profile to the intended users through Conditional Access. Creating a firewall rule alone doesn't configure traffic acquisition. For configuration and verification steps, see [Control QUIC traffic on UDP port 443](how-to-configure-cloud-firewall-clients.md#control-quic-traffic-on-udp-port-443).

430 +

431 +If you previously disabled browser QUIC specifically for Global Secure Access, remove that browser configuration after you verify Custom Acquire and cloud firewall blocking. Review other organizational requirements before changing existing browser policies.

432 +

433 +> [!IMPORTANT]

434 +> Cloud firewall for clients supports QUIC acquisition and blocking in preview, not end-to-end QUIC forwarding. An **Allow** rule for UDP port `443` doesn't enable supported end-to-end QUIC connectivity.

435 +

422436 ### Configure settings for Microsoft Entra Internet Access by using Intune

423437

424 −Microsoft Entra Internet Access doesn't support DNS over HTTPS or Quick UDP Internet Connections (QUIC) traffic. To mitigate this limitation, disable these protocols in users' browsers. The following instructions provide guidance on how to enforce these controls by using Intune.

438 +The Global Secure Access Windows client requires DNS over HTTPS to be disabled for FQDN-based traffic acquisition. Use the following Intune instructions to configure DNS over HTTPS separately from QUIC. Don't disable QUIC in the browser for this configuration.

425439

426 −#### Disable QUIC in Microsoft Edge and Chrome by using Intune

440 +#### Disable DNS over HTTPS in Microsoft Edge and Chrome by using Intune

427441

428442 1. In the Microsoft Intune admin center, select **Devices** > **Manage devices** > **Configuration**.

429443

⋯ 12 unchanged lines

442456 1. On the **Configuration settings** tab:

443457

444458 1. Select **+ Add settings**.

445 − 1. In **Settings picker**, search for **QUIC**.

446 − 1. From the search results:

447 − 1. Select **Microsoft Edge**, and then select the **Allow QUIC protocol** setting.

448 − 1. Select **Google Chrome**, and then select the **Allow QUIC protocol** setting.

449459 1. In **Settings picker**, search for **DNS-over-HTTPS**.

450460 1. From the search results:

451461 1. Select **Microsoft Edge**, and then select the **Control the mode of DNS-over-HTTPS** setting.

452462 1. Select **Google Chrome**, and then select the **Control the mode of DNS-over-HTTPS** setting.

453463 1. Close **Settings picker**.

454464

455 −1. For **Google Chrome**, set both toggles to **Disabled**.

456 −

457 −1. For **Microsoft Edge**, set both toggles to **Disabled**.

465 +1. For **Google Chrome**, set **Control the mode of DNS-over-HTTPS** to **Disabled**.

458466

459 − :::image type="content" source="media/how-to-install-windows-client/edge-chrome-profile.png" alt-text="Screenshot of the tab for configuring Microsoft Edge and Chrome settings." lightbox="media/how-to-install-windows-client/edge-chrome-profile.png":::

467 +1. For **Microsoft Edge**, set **Control the mode of DNS-over-HTTPS** to **Disabled**.

460468

461469 1. Select **Next** twice.

462470

⋯ 9 unchanged lines

472480

473481 ### Configure Firefox browser settings

474482

475 −Admins can use [remediation scripts](/intune/intune-service/fundamentals/remediations) in Intune to disable DNS over HTTPS and QUIC protocols in the Firefox browser.

483 +Admins can use [remediation scripts](/intune/intune-service/fundamentals/remediations) in Intune to disable DNS over HTTPS in the Firefox browser.

476484

477485 Make sure to configure these scripts to run in 64-bit PowerShell.

478486

⋯ 9 unchanged lines

488496 ```powershell

489497 # Define the path to the Firefox policies.json file

490498

491 −$destination = "C:\Program Files\Mozilla Firefox\distribution\policies.json" $compliant = $false

499 +$destination = "C:\Program Files\Mozilla Firefox\distribution\policies.json"

500 +$compliant = $false

492501

493502 # Check if the file exists

494503

495 −if (Test-Path $destination) { try { # Read the file content $fileContent = Get-Content $destination -Raw if ($fileContent -and $fileContent.Trim().Length -gt 0) { # Parse JSON content $json = $fileContent | ConvertFrom-Json

504 +if (Test-Path $destination) {

505 + try {

506 + $fileContent = Get-Content $destination -Raw -ErrorAction Stop

507 + if ($fileContent -and $fileContent.Trim().Length -gt 0) {

508 + $json = $fileContent | ConvertFrom-Json -ErrorAction Stop

496509

497510 # Check if Preferences exist under policies

498511 if ($json.policies -and $json.policies.Preferences) {

⋯ 8 unchanged lines

507520 $prefs = $temp

508521 }

509522

510 − # Initialize compliance flags

511 − $quicCompliant = $false

523 + # Initialize compliance flag

512524 $dohCompliant = $false

513525

514 − # Check if QUIC is disabled and locked

515 − if ($prefs.ContainsKey("network.http.http3.enable")) {

516 − $val = $prefs["network.http.http3.enable"]

517 − if ($val.Value -eq $false -and $val.Status -eq "locked") {

518 − $quicCompliant = $true

519 − }

520 − }

521 −

522526 # Check if DNS over HTTPS is disabled and locked

523527 if ($prefs.ContainsKey("network.trr.mode")) {

524528 $val = $prefs["network.trr.mode"]

⋯ 2 unchanged lines

527531 }

528532 }

529533

530 − # Set overall compliance if both settings are correct

531 − if ($quicCompliant -and $dohCompliant) {

534 + if ($dohCompliant) {

532535 $compliant = $true

533536 }

534537 }

⋯ 7 unchanged lines

542545

543546 # Output compliance result

544547

545 −if ($compliant) { Write-Output "Compliant" Exit 0 } else { Write-Output "Non-compliant" Exit 1 }

548 +if ($compliant) {

549 + Write-Output "Compliant"

550 + exit 0

551 +} else {

552 + Write-Output "Non-compliant"

553 + exit 1

554 +}

546555 ```

547556

548557 </details>

⋯ 6 unchanged lines

555564 ```powershell

556565 # Define paths

557566

558 −$distributionDir = "C:\Program Files\Mozilla Firefox\distribution" $destination = Join-Path $distributionDir "policies.json" $backup = "$destination.bak"

567 +$ErrorActionPreference = 'Stop'

568 +$distributionDir = "C:\Program Files\Mozilla Firefox\distribution"

569 +$destination = Join-Path $distributionDir "policies.json"

570 +$backup = "$destination.bak"

559571

560572 # Initialize variable for existing JSON

561573

⋯ 1 unchanged line

563575

564576 # Try to read and parse existing policies.json

565577

566 −if (Test-Path $destination) { $fileContent = Get-Content $destination -Raw if ($fileContent -and $fileContent.Trim().Length -gt 0) { try { $existingJson = $fileContent | ConvertFrom-Json } catch { Write-Warning "Existing policies.json is malformed. Starting fresh." } } }

578 +if (Test-Path $destination) {

579 + $fileContent = Get-Content $destination -Raw

580 + if ($fileContent -and $fileContent.Trim().Length -gt 0) {

581 + try {

582 + $existingJson = $fileContent | ConvertFrom-Json

583 + } catch {

584 + Write-Warning "Failed to parse existing policies.json. No browser settings were changed: $_"

585 + exit 1

586 + }

587 + }

588 +}

567589

568590 #Create a new JSON structure if none exists

569591

⋯ 1 unchanged line

571593

572594 # Ensure policies and Preferences nodes exist

573595

574 −if (-not $existingJson.policies) { $existingJson | Add-Member -MemberType NoteProperty -Name policies -Value ([PSCustomObject]@{}) } if (-not $existingJson.policies.Preferences) { $existingJson.policies | Add-Member -MemberType NoteProperty -Name Preferences -Value @{} }

596 +if (-not $existingJson.policies) { $existingJson | Add-Member -MemberType NoteProperty -Name policies -Value ([PSCustomObject]@{}) }

597 +if (-not $existingJson.policies.Preferences) { $existingJson.policies | Add-Member -MemberType NoteProperty -Name Preferences -Value @{} }

575598

576599 # Convert Preferences to hashtable if needed

577600

578 −if ($existingJson.policies.Preferences -isnot [hashtable]) { $prefs = @{} $existingJson.policies.Preferences.psobject.Properties | ForEach-Object { $prefs[$.Name] = $.Value } $existingJson.policies.Preferences = $prefs }

579 −

580 −$prefObj = $existingJson.policies.Preferences $updated = $false

581 −

582 −# Ensure QUIC is disabled and locked

583 −

584 −if (-not $prefObj.ContainsKey("network.http.http3.enable") -or $prefObj["network.http.http3.enable"].Value -ne $false -or $prefObj["network.http.http3.enable"].Status -ne "locked") {

585 −

586 −$prefObj["network.http.http3.enable"] = @{

587 − Value = $false

588 − Status = "locked"

589 −}

590 −$updated = $true

591 −

601 +if ($existingJson.policies.Preferences -isnot [hashtable]) { $prefs = @{}; $existingJson.policies.Preferences.psobject.Properties | ForEach-Object { $prefs[$_.Name] = $_.Value }; $existingJson.policies.Preferences = $prefs }

592602

593 −}

603 +$prefObj = $existingJson.policies.Preferences

604 +$updated = $false

594605

595606 # Ensure DNS over HTTPS is disabled and locked

596607

⋯ 8 unchanged lines

605616

606617 # If any updates were made, back up and write the new JSON

607618

608 −if ($updated) { if (Test-Path $destination) { Copy-Item $destination $backup -Force }

619 +if ($updated) {

620 + New-Item -ItemType Directory -Path $distributionDir -Force | Out-Null

621 + if (Test-Path $destination) { Copy-Item $destination $backup -Force }

609622

610623 $jsonOut = $existingJson | ConvertTo-Json -Depth 10 -Compress

611624 $utf8NoBomEncoding = New-Object System.Text.UTF8Encoding($false)

⋯ 183 unchanged lines

Microsoft's Markdown source from MicrosoftDocs/entra-docs, © Microsoft Corporation, under MIT. Changed lines with up to 3 unchanged lines around each; ChangeIntel kept this copy 7 Nov 06:39 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.