GSA Windows client prerequisites and installation
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/entra-docs · commit 363c793 · +47 −44 lines · also on GitHub
⋯ 12 unchanged lines
1313
---
1414
# Install the Global Secure Access client for Windows
1515
16
−The Global Secure Access client is an essential part of Global Secure Access. It helps organizations manage and secure network traffic on user devices. The client routes traffic that needs to be secured by Global Secure Access to the cloud service. All other traffic goes directly to the network. The [forwarding profiles](concept-traffic-forwarding.md) that you set up in the portal decide which traffic the Global Secure Access client routes to the cloud service.
16
+The Global Secure Access client is an essential part of Global Secure Access. It helps organizations manage and secure network traffic on user devices. The client routes traffic that needs to be secured by Global Secure Access to the cloud service. All other traffic goes directly to the network. The [forwarding profiles](concept-traffic-forwarding.md) that you set up in the portal determine which traffic the Global Secure Access client routes to the cloud service.
1717
1818
This article describes how to download and install the Global Secure Access client for Windows. The Global Secure Access client is also available for [macOS](how-to-install-macos-client.md), [Android](how-to-install-android-client.md), and [iOS](how-to-install-ios-client.md).
1919
⋯ 19 unchanged lines
3939
4040
- A license. For details, see the licensing section of [What is Global Secure Access?](overview-what-is-global-secure-access.md). If necessary, you can [buy licenses or get trial licenses](https://aka.ms/azureadlicense).
4141
42
−## Steps for downloading the client
42
+## Download the client
4343
4444
The most current version of the Global Secure Access client is available to download from the Microsoft Entra admin center:
4545
⋯ 5 unchanged lines
5151
5252
:::image type="content" source="media/how-to-install-windows-client/client-download-screen.png" alt-text="Screenshot of the pane for client download with the Download Client button highlighted.":::
5353
54
−## Steps for installing the client
54
+## Install the client
5555
5656
### Automated installation
5757
58
−Organizations can install the Global Secure Access client silently by using the `/quiet` switch. Or they can use solutions for mobile device management, such as [Microsoft Intune](/mem/intune/apps/apps-win32-app-management), to deploy the client to their devices.
58
+Organizations can install the Global Secure Access client silently by using the `/quiet` switch. Or they can use mobile device management (MDM) solutions, such as [Microsoft Intune](/mem/intune/apps/apps-win32-app-management), to deploy the client to their devices.
5959
6060
### Use Microsoft Intune to deploy the Global Secure Access client
6161
⋯ 112 unchanged lines
174174
175175
:::image type="content" source="media/how-to-install-windows-client/install-content-prep-tool.png" alt-text="Screenshot of selecting the installation file in the prep tool.":::
176176
177
−1. In the upper-right corner, select **More file actions** and then select **Download**.
177
+1. In the upper-right corner, select **More file actions** > **Download**.
178178
179179
:::image type="content" source="media/how-to-install-windows-client/raw-file-download.png" alt-text="Screenshot of the Download command on the menu for more file actions.":::
180180
181
−1. Go to and run `IntuneWinAppUtil.exe`. A command prompt opens.
181
+1. Browse to and run `IntuneWinAppUtil.exe`. A command prompt opens.
182182
183183
1. Enter the folder path location of the Global Secure Access `.exe` file. Select **Enter**.
184184
⋯ 36 unchanged lines
221221
222222
1. Use the default values in the remaining fields.
223223
224
− :::image type="content" source="media/how-to-install-windows-client/add-app.png" alt-text="Screenshot of Add App to install client." lightbox="media/how-to-install-windows-client/add-app.png":::
224
+ :::image type="content" source="media/how-to-install-windows-client/add-app.png" alt-text="Screenshot of adding app information to install a client." lightbox="media/how-to-install-windows-client/add-app.png":::
225225
226226
1. Select **Next**.
227227
⋯ 5 unchanged lines
233233
- **Install behavior**: Select **System**.
234234
- **Device restart behavior**: Select **Determine behavior based on return codes**. Specify the following return codes.
235235
236
− |Return code|Code type|
237
− |-----------|---------|
238
− |0|**Success**|
239
− |3010|**Soft reboot**|
240
− |1618|**Retry**|
236
+ |Return code|Code type|
237
+ |-----------|---------|
238
+ |0|**Success**|
239
+ |3010|**Soft reboot**|
240
+ |1618|**Retry**|
241241
242242
:::image type="content" source="media/how-to-install-windows-client/program-install-parameters.png" alt-text="Screenshot of the Program tab for configuring installation parameters." lightbox="media/how-to-install-windows-client/program-install-parameters.png":::
243243
⋯ 34 unchanged lines
278278
279279
1. Select **Next** twice to go to **Assignments**.
280280
281
−1. Under **Required**, select **+Add group**. Select a group of users or devices. Choose **Select**.
281
+1. Under **Required**, select **+Add group**. Select a group of users or devices, and then choose **Select**.
282282
283283
1. Set the **Restart grace period** to **Enabled** to avoid disrupting users with an abrupt device reboot.
284284
⋯ 4 unchanged lines
289289
> [!NOTE]
290290
> Deploying the Global Secure Access client to a virtual machine might suppress the prompt to restart the device.
291291
292
−#### Update the client to a newer version
292
+#### Update the client version
293293
294294
To update to the newest client version, follow the [Update a line-of-business app](/mem/intune/apps/lob-apps-windows#update-a-line-of-business-app) steps. Be sure to update the following settings in addition to uploading the new `.intunewin` file:
295295
⋯ 12 unchanged lines
308308
309309
1. Delete the app with the old client version.
310310
311
−### Configure Global Secure Access client settings with Intune
311
+### Configure Global Secure Access client settings by using Intune
312312
313313
Administrators can use [remediation scripts](/intune/intune-service/fundamentals/remediations) in Intune to enforce client-side controls, such as preventing general users from disabling the client or hiding specific buttons.
314314
315315
> [!IMPORTANT]
316
−> Set the `$gsaSettings` to the values that your organization requires in both the detection and remediation scripts.
317
−>
318
−> Make sure to configure these scripts to run in 64-bit PowerShell.
316
+> Set `$gsaSettings` to the values that your organization requires in both the detection and remediation scripts.
319317
318
+Make sure to configure these scripts to run in 64-bit PowerShell.
319
+
320320
:::image type="content" source="media/how-to-install-windows-client/run-script-64-bit.png" alt-text="Screenshot of the tab for creating custom script settings, with the option for running the script in 64-bit PowerShell set to Yes.":::
321321
322322
Select the PowerShell scripts to expand them.
⋯ 100 unchanged lines
423423
424424
### Configure settings for Microsoft Entra Internet Access by using Intune
425425
426
−Microsoft Entra Internet Access doesn't yet 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.
426
+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.
427427
428428
#### Disable QUIC in Microsoft Edge and Chrome by using Intune
429429
⋯ 14 unchanged lines
444444
1. On the **Configuration settings** tab:
445445
446446
1. Select **+ Add settings**.
447
− 1. In the **Settings picker**, search for **QUIC**.
447
+ 1. In **Settings picker**, search for **QUIC**.
448448
1. From the search results:
449449
1. Select **Microsoft Edge**, and then select the **Allow QUIC protocol** setting.
450450
1. Select **Google Chrome**, and then select the **Allow QUIC protocol** setting.
451
− 1. In the **Settings picker**, search for **DNS-over-HTTPS**.
451
+ 1. In **Settings picker**, search for **DNS-over-HTTPS**.
452452
1. From the search results:
453453
1. Select **Microsoft Edge**, and then select the **Control the mode of DNS-over-HTTPS** setting.
454454
1. Select **Google Chrome**, and then select the **Control the mode of DNS-over-HTTPS** setting.
455
− 1. Close the **Settings picker**.
455
+ 1. Close **Settings picker**.
456456
457457
1. For **Google Chrome**, set both toggles to **Disabled**.
458458
459459
1. For **Microsoft Edge**, set both toggles to **Disabled**.
460460
461
− :::image type="content" source="media/how-to-install-windows-client/edge-chrome-profile.png" alt-text="Screenshot of the tab for configuration settings that shows the Microsoft Edge and Chrome settings." lightbox="media/how-to-install-windows-client/edge-chrome-profile.png":::
461
+ :::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":::
462462
463463
1. Select **Next** twice.
464464
⋯ 9 unchanged lines
474474
475475
### Configure Firefox browser settings
476476
477
−Admins can use [remediation scripts](/intune/intune-service/fundamentals/remediations) in Intune to disable DNS over HTTPS and QUIC protocols in Firefox browser.
477
+Admins can use [remediation scripts](/intune/intune-service/fundamentals/remediations) in Intune to disable DNS over HTTPS and QUIC protocols in the Firefox browser.
478478
479
−> [!NOTE]
480
−> Make sure to configure these scripts to run in 64-bit PowerShell.
479
+Make sure to configure these scripts to run in 64-bit PowerShell.
481480
482481
:::image type="content" source="media/how-to-install-windows-client/run-script-64-bit.png" alt-text="Screenshot of the tab for creating custom script settings, with the option for running the script in 64-bit PowerShell set to Yes.":::
483482
⋯ 136 unchanged lines
620619
621620
1. Run the `GlobalSecureAccessClient.exe` setup file. Accept the software license terms.
622621
623
−1. The client installs and silently signs you in with your Microsoft Entra credentials. If the silent sign-in fails, the installer prompts you to sign in manually.
622
+1. The client is installed and silently signs you in with your Microsoft Entra credentials. If the silent sign-in fails, the installer prompts you to sign in manually.
624623
625624
1. The connection icon turns green. Hover over it to open the client status notification, which should show as **Connected**.
626625
⋯ 5 unchanged lines
632631
633632
### Connections view
634633
635
−In the **Connections** view, you can see the client status and the channels configured for the client.
634
+The **Connections** view shows the client status and the channels configured for the client.
636635
637636
To disable the client, select the **Disable** button. You can use the information in the **Additional details** section to troubleshoot the client connection. Select **Show more details** to expand the section and view more information.
638637
⋯ 1 unchanged line
640639
641640
### Troubleshooting view
642641
643
−In the **Troubleshooting** view, you can perform various diagnostic tasks. You can export and share logs with your IT admin. You can also access the **Advanced diagnostics** tool, which provides an assortment of troubleshooting tools. (You can also open the **Advanced diagnostics** tool from the icon menu in the client's system tray.)
642
+In the **Troubleshooting** view, you can:
644643
644
+- Perform various diagnostic tasks.
645
+- Export and share logs with your IT admin.
646
+- Access the **Advanced diagnostics** tool, which provides an assortment of troubleshooting tools. (You can also open the **Advanced diagnostics** tool from the icon menu in the client's system tray.)
647
+
645648
:::image type="content" source="media/how-to-install-windows-client/client-interface-troubleshooting.png" alt-text="Screenshot of the Troubleshooting view of the Global Secure Access client interface.":::
646649
647650
### Settings view
⋯ 9 unchanged lines
657660
:::image type="content" source="media/how-to-install-windows-client/client-install-all-actions.png" alt-text="Screenshot that shows the complete list of Global Secure Access client actions.":::
658661
659662
> [!TIP]
660
−> The Global Secure Access actions on the client menu depend on your [client registry keys](#client-registry-keys) configuration.
663
+> The Global Secure Access actions on the client menu depend on your configuration of [client registry keys](#client-registry-keys).
661664
662665
|Action |Description |
663666
|---------|-------------|
⋯ 23 unchanged lines
687690
|:::image type="icon" source="media/how-to-install-windows-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access - Some channels are unreachable |The client is partially connected to Global Secure Access. That is, the connection to at least one channel failed: Microsoft Entra, Microsoft 365, Private Access, Internet Access. |
688691
|:::image type="icon" source="media/how-to-install-windows-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access - Disabled by your organization |Your organization disabled the client. That is, all traffic forwarding profiles are disabled. |
689692
|:::image type="icon" source="media/how-to-install-windows-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access - Private Access is disabled |The user disabled Private Access on this device. |
690
−|:::image type="icon" source="media/how-to-install-windows-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access - could not connect to the Internet |The client couldn't detect an internet connection. The device is either connected to a network that doesn't have an Internet connection or connected to a network that requires captive portal sign in. |
693
+|:::image type="icon" source="media/how-to-install-windows-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access - could not connect to the Internet |The client couldn't detect an internet connection. The device is either connected to a network that doesn't have an internet connection or connected to a network that requires captive portal sign-in. |
691694
692695
## Known limitations
693696
⋯ 1 unchanged line
695698
696699
## Troubleshooting
697700
698
−To troubleshoot the Global Secure Access client, select the client icon on the taskbar and select one of the troubleshooting options: **Export logs** or **Advanced diagnostics tool**.
701
+To troubleshoot the Global Secure Access client, select the client icon on the taskbar and then select one of the troubleshooting options: **Export logs** or **Advanced diagnostics tool**.
699702
700703
> [!TIP]
701
−> Administrators can modify the Global Secure Access client menu options by revising the [Client registry keys](#client-registry-keys).
704
+> Administrators can modify the options on the Global Secure Access client menu by revising the [Client registry keys](#client-registry-keys).
702705
703706
For more information on troubleshooting the Global Secure Access client, see the following articles:
704707
705
−- [Troubleshoot the Global Secure Access client: advanced diagnostics](troubleshoot-global-secure-access-client-advanced-diagnostics.md)
706
−- [Troubleshoot the Global Secure Access client: Health check tab](troubleshoot-global-secure-access-client-diagnostics-health-check.md)
708
+- [Troubleshoot the Global Secure Access client for Windows: Advanced diagnostics](troubleshoot-global-secure-access-client-advanced-diagnostics.md)
709
+- [Troubleshoot the Global Secure Access client for Windows: Health check tab](troubleshoot-global-secure-access-client-diagnostics-health-check.md)
707710
708711
## Security recommendations
709712
⋯ 1 unchanged line
711714
712715
### Upgrade to the latest client version
713716
714
−Regularly test and deploy the latest Global Secure Access client release to take advantage of new features, performance improvements, and security fixes. Download the latest version of the [Global Secure Access client](#steps-for-downloading-the-client) from the Microsoft Entra admin center.
717
+Regularly test and deploy the latest Global Secure Access client release to take advantage of new features, performance improvements, and security fixes. Download the latest version of the [Global Secure Access client](#download-the-client) from the Microsoft Entra admin center.
715718
716719
### Restrict nonprivileged users from disabling the client
717720
⋯ 7 unchanged lines
725728
726729
In addition to restricting nonprivileged users from disabling the client, administrators can hide the **Disable** button on the icon menu in the client's system tray. Removing the **Disable** button from view further reduces the likelihood that users disable the client by accident or without authorization.
727730
728
−For more information regarding hiding client menu buttons, see [Hide or unhide system tray menu buttons](#hide-or-unhide-system-tray-menu-buttons).
731
+For more information about hiding client menu buttons, see [Hide or unhide menu buttons in the system tray](#hide-or-unhide-menu-buttons-in-the-system-tray).
729732
730733
## Client registry keys
731734
732
−The Global Secure Access client uses specific registry keys to enable or disable functionalities. Administrators can use a solution for mobile device management, such as Microsoft Intune or Group Policy, to control the registry values.
735
+The Global Secure Access client uses specific registry keys to enable or disable functionalities. Administrators can use an MDM solution, such as Microsoft Intune or Group Policy, to control the registry values.
733736
734737
> [!CAUTION]
735738
> Don't change other registry values unless Microsoft Support instructs you to.
⋯ 6 unchanged lines
742745
|Value |Type |Data |Description |
743746
|-------|------|------|-------------|
744747
|`RestrictNonPrivilegedUsers` |`REG_DWORD` |`0x0` |Nonprivileged users on the Windows device can disable and enable the client. |
745
−|`RestrictNonPrivilegedUsers` |`REG_DWORD` |`0x1` |Nonprivileged users on the Windows device are restricted from disabling and enabling the client. A User Account Control (UAC) prompt requires local administrator credentials for disable and enable options. The administrator can also hide the disable button (see [Hide or unhide system tray menu buttons](#hide-or-unhide-system-tray-menu-buttons)). |
748
+|`RestrictNonPrivilegedUsers` |`REG_DWORD` |`0x1` |Nonprivileged users on the Windows device are restricted from disabling and enabling the client. A User Account Control (UAC) prompt requires local administrator credentials for disable and enable options. The administrator can also hide the disable button (see [Hide or unhide menu buttons in the system tray](#hide-or-unhide-menu-buttons-in-the-system-tray)). |
746749
747750
### Disable or enable Private Access on the client
748751
⋯ 2 unchanged lines
751754
Users can disable or enable Private Access through the system tray menu.
752755
753756
> [!TIP]
754
−> This option is available on the menu only if it isn't hidden (see [Hide or unhide system tray menu buttons](#hide-or-unhide-system-tray-menu-buttons)) and Private Access is enabled for this tenant.
757
+> This option is available on the menu only if it isn't hidden (see [Hide or unhide menu buttons in the system tray](#hide-or-unhide-menu-buttons-in-the-system-tray)) and Private Access is enabled for this tenant.
755758
756
−Administrators can disable or enable Private Access for the user by setting the registry key:
759
+Administrators can disable or enable Private Access for the user by setting the following registry key:
757760
`Computer\HKEY_CURRENT_USER\Software\Microsoft\Global Secure Access Client`.
758761
759762
|Value |Type |Data |Description |
⋯ 5 unchanged lines
765768
766769
If the registry value doesn't exist, the default value is `0x0` and Private Access is enabled.
767770
768
−### Hide or unhide system tray menu buttons
771
+### Hide or unhide menu buttons in the system tray
769772
770773
Administrators can show or hide specific buttons on the icon menu in the client's system tray. Create the values under the following registry key:
771774
`Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Global Secure Access Client`.
⋯ 1 unchanged line
773776
|Value |Type |Data |Default behavior |Description |
774777
|---------|---------|---------|---------|---------|
775778
|`HideSignOutButton` |`REG_DWORD` |`0x0` - shown `0x1` - hidden |Hidden |Configure this setting to show or hide the **Sign out** action. This option is for specific scenarios when a user needs to sign in to the client with a different Microsoft Entra user than the one used to sign in to Windows. Note: You must sign in to the client with a user in the same Microsoft Entra tenant to which the device is joined. You can also use the **Sign out** action to reauthenticate the existing user. |
776
−|`HideDisablePrivateAccessButton` |`REG_DWORD` |`0x0` - shown `0x1` - hidden |Hidden |Configure this setting to show or hide the **Disable Private Access** action. This option is for a scenario when the device is directly connected to the corporate network and the user prefers accessing private applications directly through the network instead of through Global Secure Access. |
777
−|`HideDisableButton` |`REG_DWORD` |`0x0` - shown `0x1` - hidden |Shown |Configure this setting to show or hide the **Disable** action. When visible, the user can disable the Global Secure Access client. The client remains disabled until the user enables it again. If the **Disable** action is hidden, a nonprivileged user can't disable the client. |
779
+|`HideDisablePrivateAccessButton` |`REG_DWORD` |`0x0` - shown `0x1` - hidden |Hidden |Configure this setting to show or hide the **Disable Private Access** action. This option is for a scenario when the device is directly connected to the corporate network and the user prefers to access private applications directly through the network instead of through Global Secure Access. |
780
+|`HideDisableButton` |`REG_DWORD` |`0x0` - shown `0x1` - hidden |Shown |Configure this setting to show or hide the **Disable** action. When the action is visible, the user can disable the Global Secure Access client. The client remains disabled until the user enables it again. If the **Disable** action is hidden, a nonprivileged user can't disable the client. |
778781
779782
:::image type="content" source="media/how-to-install-windows-client/global-secure-access-registry-key-private-hide-signout.png" alt-text="Screenshot of the Registry Editor with the HideSignOutButton and HideDisablePrivateAccessButton registry keys highlighted.":::
780783
⋯ 7 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.