GSA Windows client prerequisites and installation
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/entra-docs · commit 65f0d24 · +87 −86 lines · also on GitHub
⋯ 40 unchanged lines
4141
1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as a [Global Secure Access Administrator](/azure/active-directory/roles/permissions-reference#global-secure-access-administrator).
4242
1. Browse to **Global Secure Access** > **Connect** > **Client download**.
4343
1. Select **Download Client**.
44
−:::image type="content" source="media/how-to-install-windows-client/client-download-screen.png" alt-text="Screenshot of the Client download screen with the Download Client button highlighted.":::
44
+
45
+ :::image type="content" source="media/how-to-install-windows-client/client-download-screen.png" alt-text="Screenshot of the Client download screen with the Download Client button highlighted.":::
4546
4647
## Install the Global Secure Access client
4748
### Automated installation
⋯ 13 unchanged lines
6162
6263
1. Save the following PowerShell script to your device. Put the PowerShell script and the Global Secure Access `.exe` installer into a folder.
6364
64
−> [!NOTE]
65
−> The name of the `.exe` file must be `GlobalSecureAccessClient.exe` for the PowerShell installation script to work properly. If you modify the name of the `.exe` file to something else, you must also modify the $installerPath in the PowerShell script.
65
+ > [!NOTE]
66
+ > The name of the `.exe` file must be `GlobalSecureAccessClient.exe` for the PowerShell installation script to work properly. If you modify the name of the `.exe` file to something else, you must also modify the $installerPath in the PowerShell script.
6667
67
−> [!NOTE]
68
−> The PowerShell installation script installs the Global Secure Access client, sets the `IPv4Preferred` registry key to prefer IPv4 over IPv6 traffic, and prompts for a reboot for the registry key change to take effect.
68
+ > [!NOTE]
69
+ > The PowerShell installation script installs the Global Secure Access client, sets the `IPv4Preferred` registry key to prefer IPv4 over IPv6 traffic, and prompts for a reboot for the registry key change to take effect.
6970
70
−```powershell
71
−# Create log directory and log helper
72
−$logFile = "$env:ProgramData\GSAInstall\install.log"
73
−New-Item -ItemType Directory -Path (Split-Path $logFile) -Force | Out-Null
71
+ ```powershell
72
+ # Create log directory and log helper
73
+ $logFile = "$env:ProgramData\GSAInstall\install.log"
74
+ New-Item -ItemType Directory -Path (Split-Path $logFile) -Force | Out-Null
7475
75
−function Write-Log {
76
− param([string]$message)
77
− $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
78
− Add-Content -Path $logFile -Value "$timestamp - $message"
79
−}
76
+ function Write-Log {
77
+ param([string]$message)
78
+ $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
79
+ Add-Content -Path $logFile -Value "$timestamp - $message"
80
+ }
8081
81
−try {
82
− $ErrorActionPreference = 'Stop'
83
− Write-Log "Starting Global Secure Access client installation."
82
+ try {
83
+ $ErrorActionPreference = 'Stop'
84
+ Write-Log "Starting Global Secure Access client installation."
8485
85
− # IPv4 preferred via DisabledComponents registry value
86
− $ipv4RegPath = "HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters"
87
− $ipv4RegName = "DisabledComponents"
88
− $ipv4RegValue = 0x20 # Prefer IPv4 over IPv6
89
− $rebootRequired = $false
86
+ # IPv4 preferred via DisabledComponents registry value
87
+ $ipv4RegPath = "HKLM:\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters"
88
+ $ipv4RegName = "DisabledComponents"
89
+ $ipv4RegValue = 0x20 # Prefer IPv4 over IPv6
90
+ $rebootRequired = $false
9091
91
− # Ensure the key exists
92
− if (-not (Test-Path $ipv4RegPath)) {
93
− New-Item -Path $ipv4RegPath -Force | Out-Null
94
− Write-Log "Created registry key: $ipv4RegPath"
95
− }
92
+ # Ensure the key exists
93
+ if (-not (Test-Path $ipv4RegPath)) {
94
+ New-Item -Path $ipv4RegPath -Force | Out-Null
95
+ Write-Log "Created registry key: $ipv4RegPath"
96
+ }
9697
97
− # Get current value if present
98
− $existingValue = $null
99
− $valueExists = $false
100
− try {
101
− $existingValue = Get-ItemPropertyValue -Path $ipv4RegPath -Name $ipv4RegName -ErrorAction Stop
102
− $valueExists = $true
103
− } catch {
104
− $valueExists = $false
105
− }
98
+ # Get current value if present
99
+ $existingValue = $null
100
+ $valueExists = $false
101
+ try {
102
+ $existingValue = Get-ItemPropertyValue -Path $ipv4RegPath -Name $ipv4RegName -ErrorAction Stop
103
+ $valueExists = $true
104
+ } catch {
105
+ $valueExists = $false
106
+ }
106107
107
− # Determine if we must change it
108
− $expected = [int]$ipv4RegValue
109
− $needsChange = -not $valueExists -or ([int]$existingValue -ne $expected)
108
+ # Determine if we must change it
109
+ $expected = [int]$ipv4RegValue
110
+ $needsChange = -not $valueExists -or ([int]$existingValue -ne $expected)
110111
111
− if ($needsChange) {
112
− if (-not $valueExists) {
113
− # Create as DWORD when missing
114
− New-ItemProperty -Path $ipv4RegPath -Name $ipv4RegName -PropertyType DWord -Value $expected -Force | Out-Null
115
− Write-Log ("IPv4Preferred value missing. Created '{0}' with value 0x{1} (dec {2})." -f $ipv4RegName, ([Convert]::ToString($expected,16)), $expected)
116
− } else {
117
− # Update if different
118
− Set-ItemProperty -Path $ipv4RegPath -Name $ipv4RegName -Value $expected
119
− Write-Log ("IPv4Preferred value differed. Updated '{0}' from 0x{1} (dec {2}) to 0x{3} (dec {4})." -f `
120
− $ipv4RegName, ([Convert]::ToString([int]$existingValue,16)), [int]$existingValue, ([Convert]::ToString($expected,16)), $expected)
121
− }
122
− $rebootRequired = $true
123
− } else {
124
− Write-Log ("IPv4Preferred already set correctly: {0}=0x{1} (dec {2}). No change." -f `
125
− $ipv4RegName, ([Convert]::ToString($expected,16)), $expected)
126
− }
112
+ if ($needsChange) {
113
+ if (-not $valueExists) {
114
+ # Create as DWORD when missing
115
+ New-ItemProperty -Path $ipv4RegPath -Name $ipv4RegName -PropertyType DWord -Value $expected -Force | Out-Null
116
+ Write-Log ("IPv4Preferred value missing. Created '{0}' with value 0x{1} (dec {2})." -f $ipv4RegName, ([Convert]::ToString($expected,16)), $expected)
117
+ } else {
118
+ # Update if different
119
+ Set-ItemProperty -Path $ipv4RegPath -Name $ipv4RegName -Value $expected
120
+ Write-Log ("IPv4Preferred value differed. Updated '{0}' from 0x{1} (dec {2}) to 0x{3} (dec {4})." -f `
121
+ $ipv4RegName, ([Convert]::ToString([int]$existingValue,16)), [int]$existingValue, ([Convert]::ToString($expected,16)), $expected)
122
+ }
123
+ $rebootRequired = $true
124
+ } else {
125
+ Write-Log ("IPv4Preferred already set correctly: {0}=0x{1} (dec {2}). No change." -f `
126
+ $ipv4RegName, ([Convert]::ToString($expected,16)), $expected)
127
+ }
127128
128
− # Resolve installer path
129
− $ScriptRoot = if ($PSScriptRoot) { $PSScriptRoot } else { Split-Path -Parent $MyInvocation.MyCommand.Path }
130
− $installerPath = Join-Path -Path $ScriptRoot -ChildPath "GlobalSecureAccessClient.exe"
131
− Write-Log "Running installer from $installerPath"
129
+ # Resolve installer path
130
+ $ScriptRoot = if ($PSScriptRoot) { $PSScriptRoot } else { Split-Path -Parent $MyInvocation.MyCommand.Path }
131
+ $installerPath = Join-Path -Path $ScriptRoot -ChildPath "GlobalSecureAccessClient.exe"
132
+ Write-Log "Running installer from $installerPath"
132133
133
− if (Test-Path $installerPath) {
134
− $installProcess = Start-Process -FilePath $installerPath -ArgumentList "/quiet" -Wait -PassThru
134
+ if (Test-Path $installerPath) {
135
+ $installProcess = Start-Process -FilePath $installerPath -ArgumentList "/quiet" -Wait -PassThru
135136
136
− if ($installProcess.ExitCode -eq 1618) {
137
− Write-Log "Another installation is in progress. Exiting with code 1618."
138
− exit 1618
139
− } elseif ($installProcess.ExitCode -ne 0) {
140
− Write-Log "Installer exited with code $($installProcess.ExitCode)."
141
− exit $installProcess.ExitCode
142
− }
137
+ if ($installProcess.ExitCode -eq 1618) {
138
+ Write-Log "Another installation is in progress. Exiting with code 1618."
139
+ exit 1618
140
+ } elseif ($installProcess.ExitCode -ne 0) {
141
+ Write-Log "Installer exited with code $($installProcess.ExitCode)."
142
+ exit $installProcess.ExitCode
143
+ }
143144
144
− Write-Log "Installer completed successfully."
145
− } else {
146
− Write-Log "Installer not found at $installerPath"
147
− exit 1
148
− }
145
+ Write-Log "Installer completed successfully."
146
+ } else {
147
+ Write-Log "Installer not found at $installerPath"
148
+ exit 1
149
+ }
149150
150
− if ($rebootRequired) {
151
− Write-Log "Reboot required due to registry value creation or update."
152
− exit 3010 # Soft reboot required
153
− } else {
154
− Write-Log "Installation complete. No reboot required."
155
− exit 0
156
− }
157
−}
158
−catch {
159
− Write-Log "Fatal error: $_"
160
− exit 1603
161
−}
162
−```
151
+ if ($rebootRequired) {
152
+ Write-Log "Reboot required due to registry value creation or update."
153
+ exit 3010 # Soft reboot required
154
+ } else {
155
+ Write-Log "Installation complete. No reboot required."
156
+ exit 0
157
+ }
158
+ }
159
+ catch {
160
+ Write-Log "Fatal error: $_"
161
+ exit 1603
162
+ }
163
+ ```
163164
164165
2. Go to the [Microsoft Win32 Content Prep Tool](https://github.com/Microsoft/Microsoft-Win32-Content-Prep-Tool). Select **IntuneWinAppUtil.exe**.
165166
⋯ 557 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 10 Oct 03:31 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.