GSA macOS client prerequisites and installation
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/entra-docs · commit 7706047 · +109 −108 lines · also on GitHub
11
---
2
−title: The Global Secure Access Client for macOS
3
−description: The Global Secure Access client secures network traffic at the end-user device. This article describes how to download and install the macOS client.
2
+title: Install the Global Secure Access Client for macOS
3
+description: The Global Secure Access client helps secure network traffic at the user device. This article describes how to download and install the macOS client.
44
ms.topic: how-to
5
−ms.date: 03/30/2026
5
+ms.date: 02/21/2026
66
ms.author: jayrusso
77
author: HULKsmashGithub
88
ms.reviewer: lirazbarak
99
ms.custom: sfi-image-nochange
10
−# Customer intent: As an IT admin, I want to deploy the Global Secure Access client on macOS devices so that my organization’s network traffic is protected.
10
+# Customer intent: As an IT admin, I want to deploy the Global Secure Access client on macOS devices so that my organization's network traffic is protected.
1111
1212
---
1313
# Install the Global Secure Access client for macOS
14
+
1415
The Global Secure Access client, an essential component of Global Secure Access, helps organizations manage and secure network traffic on end-user devices. The client's main role is to route 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), configured in the portal, determine which traffic the Global Secure Access client routes to the cloud service.
1516
1617
This article describes how to download and install the Global Secure Access client for macOS.
1718
1819
## Prerequisites
1920
20
−- A Mac device with an Intel, M1, M2, M3, or M4 processor running macOS version 14 or later.
21
+- A Mac device with an Intel, M1, M2, M3, or M4 processor running macOS version 13 or later.
2122
- A device registered to a Microsoft Entra tenant using Company Portal.
2223
- A Microsoft Entra tenant onboarded to Global Secure Access.
2324
- An internet connection.
⋯ 1 unchanged line
2526
2627
## Download the client
2728
28
−You can download the most current version of the Global Secure Access client from the Microsoft Entra admin center.
29
+The most current version of the Global Secure Access client is available to download from the Microsoft Entra admin center.
2930
3031
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).
3132
1. Browse to **Global Secure Access** > **Connect** > **Client download**.
⋯ 8 unchanged lines
4041
4142
`sudo installer -pkg ~/Downloads/GlobalSecureAccessClient.pkg -target / -verboseR`
4243
43
−The client uses system extensions and a transparent application proxy that you need to approve during the installation. For a silent deployment without prompting the end user to allow these components, deploy a policy to automatically approve the components by using mobile device management.
44
+The client uses system extensions and a transparent application proxy that need to be approved during the installation. For a silent deployment without prompting the end user to allow these components, you can deploy a policy to automatically approve the components with mobile device management.
4445
4546
### Deploy with Microsoft Intune
4647
To deploy the Global Secure Access client .pkg through Microsoft Intune as a managed app:
⋯ 3 unchanged lines
5051
1. In the **Select app type** pane, under **Other** app types, select **macOS app (PKG)** and select **Select**.
5152
1. On the **App package file** tab, select **Select app package file**, browse to the GlobalSecureAccessClient.pkg file, and select **OK**.
5253
1. On the **App information** tab, fill in the required details and select **Next**.
53
−1. On the **Requirements** tab, set the minimum operating system to **macOS 14.0** and select **Next**.
54
+1. On the **Requirements** tab, set the minimum operating system to **macOS 13.0** and select **Next**.
5455
1. On the **Detection rules** tab, review the **Included apps** list to verify the Global Secure Access client app is detected correctly and select **Next**.
5556
1. On the **Assignments** tab, assign the app to the appropriate device or user groups and select **Next**.
5657
1. Review the configuration and select **Create**.
⋯ 1 unchanged line
5859
### Allow system extensions through mobile device management (MDM)
5960
6061
> [!IMPORTANT]
61
−> Previous versions of these instructions referenced the deprecated **Extensions** profile type. If your organization previously deployed system extensions by using the **Extensions** profile, migrate to the **Allowed System Extensions** setting in the **Settings catalog** as described in the following steps.
62
+> Previous versions of these instructions referenced the deprecated **Extensions** profile type. If your organization previously deployed system extensions using the **Extensions** profile, migrate to the **Allowed System Extensions** setting in the **Settings catalog** as described in the following steps.
6263
63
−The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management). You can adapt them for different MDMs.
64
+The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management) and you can adapt them for different MDMs:
6465
6566
1. In the Microsoft Intune admin center, select **Devices** > **Manage devices** > **Configuration** > **Policies** > **Create** > **New policy**.
6667
1. Create a profile with a **Platform** of **macOS** and a **Profile type** set to **Settings catalog**. Select **Create**.
⋯ 7 unchanged lines
7475
1. In the list of **Allowed System Extensions**, select **+ Edit instance**.
7576
1. In the **Configure instance** dialog, configure the System Extensions payload settings with the following entries:
7677
77
− |Bundle identifier |Team identifier |
78
− |---------|---------|
79
− |com.microsoft.globalsecureaccess.tunnel |UBF8T346G9 |
80
− |com.microsoft.globalsecureaccess |UBF8T346G9 |
78
+|Bundle identifier |Team identifier |
79
+|---------|---------|
80
+|com.microsoft.globalsecureaccess.tunnel |UBF8T346G9 |
81
+|com.microsoft.globalsecureaccess |UBF8T346G9 |
8182
82
−1. Select **Save** and **Next**.
83
+10. Select **Save** and **Next**.
8384
1. On the **Scope tags** tab, add tags as appropriate.
8485
1. On the **Assignments** tab, assign the profile to a group of macOS devices or users.
8586
1. On the **Review + create** tab, review the configuration and select **Create**.
8687
8788
### Allow transparent application proxy through MDM
88
−The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management). You can adapt them for different MDMs.
89
+The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management) and you can adapt them for different MDMs:
8990
9091
1. In the Microsoft Intune admin center, select **Devices** > **Manage devices** > **Configuration** > **Policies** > **Create** > **New policy**.
9192
1. Create a profile for the macOS platform based on a template of type **Custom** and select **Create**.
⋯ 3 unchanged lines
9596
1. Keep **Deployment channel** set to "Device channel."
9697
1. Upload an .xml file that contains the following data:
9798
98
− ```xml
99
− <?xml version="1.0" encoding="UTF-8"?>
100
− <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
101
− <plist version="1.0">
102
− <dict>
103
− <key>PayloadUUID</key>
104
− <string>87cbb424-6af7-4748-9d43-f1c5dda7a0a6</string>
105
− <key>PayloadType</key>
106
− <string>Configuration</string>
107
− <key>PayloadOrganization</key>
108
− <string>Microsoft Corporation</string>
109
− <key>PayloadIdentifier</key>
110
− <string>com.microsoft.globalsecureaccess</string>
111
− <key>PayloadDisplayName</key>
112
− <string>Global Secure Access Proxy Configuration</string>
113
− <key>PayloadDescription</key>
114
− <string>Add Global Secure Access Proxy Configuration</string>
115
− <key>PayloadVersion</key>
116
− <integer>1</integer>
117
− <key>PayloadEnabled</key>
118
− <true/>
119
− <key>PayloadRemovalDisallowed</key>
120
− <true/>
121
− <key>PayloadScope</key>
122
− <string>System</string>
123
− <key>PayloadContent</key>
124
− <array>
125
− <dict>
126
− <key>PayloadUUID</key>
127
− <string>04e13063-2bb8-4b72-b1ed-45290f91af68</string>
128
− <key>PayloadType</key>
129
− <string>com.apple.vpn.managed</string>
130
− <key>PayloadOrganization</key>
131
− <string>Microsoft Corporation</string>
132
− <key>PayloadIdentifier</key>
133
− <string>com.microsoft.globalsecureaccess</string>
134
− <key>PayloadDisplayName</key>
135
− <string>Global Secure Access Proxy Configuration</string>
136
− <key>PayloadDescription</key>
137
− <string/>
138
− <key>PayloadVersion</key>
139
− <integer>1</integer>
140
− <key>TransparentProxy</key>
141
− <dict>
142
− <key>AuthenticationMethod</key>
143
− <string>Password</string>
144
− <key>Order</key>
145
− <integer>1</integer>
146
− <key>ProviderBundleIdentifier</key>
147
− <string>com.microsoft.globalsecureaccess.tunnel</string>
148
− <key>ProviderDesignatedRequirement</key>
149
− <string>identifier "com.microsoft.globalsecureaccess.tunnel" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = UBF8T346G9</string>
150
− <key>ProviderType</key>
151
− <string>app-proxy</string>
152
− <key>RemoteAddress</key>
153
− <string>100.64.0.0</string>
154
− </dict>
155
− <key>UserDefinedName</key>
156
− <string>Global Secure Access Proxy Configuration</string>
157
− <key>VPNSubType</key>
158
− <string>com.microsoft.globalsecureaccess</string>
159
− <key>VPNType</key>
160
− <string>TransparentProxy</string>
161
− </dict>
162
− </array>
163
− </dict>
164
− </plist>
165
− ```
99
+```xml
100
+<?xml version="1.0" encoding="UTF-8"?>
101
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
102
+<plist version="1.0">
103
+ <dict>
104
+ <key>PayloadUUID</key>
105
+ <string>87cbb424-6af7-4748-9d43-f1c5dda7a0a6</string>
106
+ <key>PayloadType</key>
107
+ <string>Configuration</string>
108
+ <key>PayloadOrganization</key>
109
+ <string>Microsoft Corporation</string>
110
+ <key>PayloadIdentifier</key>
111
+ <string>com.microsoft.globalsecureaccess</string>
112
+ <key>PayloadDisplayName</key>
113
+ <string>Global Secure Access Proxy Configuration</string>
114
+ <key>PayloadDescription</key>
115
+ <string>Add Global Secure Access Proxy Configuration</string>
116
+ <key>PayloadVersion</key>
117
+ <integer>1</integer>
118
+ <key>PayloadEnabled</key>
119
+ <true/>
120
+ <key>PayloadRemovalDisallowed</key>
121
+ <true/>
122
+ <key>PayloadScope</key>
123
+ <string>System</string>
124
+ <key>PayloadContent</key>
125
+ <array>
126
+ <dict>
127
+ <key>PayloadUUID</key>
128
+ <string>04e13063-2bb8-4b72-b1ed-45290f91af68</string>
129
+ <key>PayloadType</key>
130
+ <string>com.apple.vpn.managed</string>
131
+ <key>PayloadOrganization</key>
132
+ <string>Microsoft Corporation</string>
133
+ <key>PayloadIdentifier</key>
134
+ <string>com.microsoft.globalsecureaccess</string>
135
+ <key>PayloadDisplayName</key>
136
+ <string>Global Secure Access Proxy Configuration</string>
137
+ <key>PayloadDescription</key>
138
+ <string/>
139
+ <key>PayloadVersion</key>
140
+ <integer>1</integer>
141
+ <key>TransparentProxy</key>
142
+ <dict>
143
+ <key>AuthenticationMethod</key>
144
+ <string>Password</string>
145
+ <key>Order</key>
146
+ <integer>1</integer>
147
+ <key>ProviderBundleIdentifier</key>
148
+ <string>com.microsoft.globalsecureaccess.tunnel</string>
149
+ <key>ProviderDesignatedRequirement</key>
150
+ <string>identifier "com.microsoft.globalsecureaccess.tunnel" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = UBF8T346G9</string>
151
+ <key>ProviderType</key>
152
+ <string>app-proxy</string>
153
+ <key>RemoteAddress</key>
154
+ <string>100.64.0.0</string>
155
+ </dict>
156
+ <key>UserDefinedName</key>
157
+ <string>Global Secure Access Proxy Configuration</string>
158
+ <key>VPNSubType</key>
159
+ <string>com.microsoft.globalsecureaccess</string>
160
+ <key>VPNType</key>
161
+ <string>TransparentProxy</string>
162
+ </dict>
163
+ </array>
164
+ </dict>
165
+</plist>
166
+```
166167
167
−1. Complete the creation of the profile by assigning users and devices according to your needs.
168
+7. Complete the creation of the profile by assigning users and devices according to your needs.
168169
169170
### Manual interactive installation
170171
To manually install the Global Secure Access client:
171
−1. Run the `GlobalSecureAccessClient.pkg` setup file. The **Install** wizard launches. Follow the prompts.
172
+1. Run the GlobalSecureAccessClient.pkg setup file. The **Install** wizard launches. Follow the prompts.
172173
1. On the **Introduction** step, select **Continue**.
173174
1. On the **License** step, select **Continue** and then select **Agree** to accept the license agreement.
174175
:::image type="content" source="media/how-to-install-macos-client/macos-install-license-agreement.png" alt-text="Screenshot of the Install wizard on the SumLicense step, showing the software license agreement pop-up.":::
⋯ 1 unchanged line
176177
1. On the **Summary** step, when the installation is complete, select **Close**.
177178
1. Allow the Global Secure Access system extension.
178179
1. In the **System Extension Blocked** dialog, select **Open System Settings**.
179
− :::image type="content" source="media/how-to-install-macos-client/macos-client-open-system-settings.png" alt-text="Screenshot of the System Extension Blocked dialog box with the Open System Settings highlighted.":::
180
+:::image type="content" source="media/how-to-install-macos-client/macos-client-open-system-settings.png" alt-text="Screenshot of the System Extension Blocked dialog box with the Open System Settings highlighted.":::
180181
181182
1. Allow the Global Secure Access client system extension by selecting **Allow**.
182
− :::image type="content" source="media/how-to-install-macos-client/macos-allow-blocked-application.png" alt-text="Screenshot of the System Settings, open to the Privacy & Security options, showing a blocked application message, with the Allow button highlighted.":::
183
+:::image type="content" source="media/how-to-install-macos-client/macos-allow-blocked-application.png" alt-text="Screenshot of the System Settings, open to the Privacy & Security options, showing a blocked application message, with the Allow button highlighted.":::
183184
184185
1. In the **Privacy & Security** dialog, enter your username and password to validate the approval of the system extension. Then select **Modify Settings**.
185
− :::image type="content" source="media/how-to-install-macos-client/macos-client-credentials.png" alt-text="Screenshot of the Privacy & Security pop-up requesting sign-in credentials and the Modify Settings button highlighted.":::
186
+:::image type="content" source="media/how-to-install-macos-client/macos-client-credentials.png" alt-text="Screenshot of the Privacy & Security pop-up requesting sign-in credentials and the Modify Settings button highlighted.":::
186187
187188
1. Complete the process by selecting **Allow** to enable the Global Secure Access client to add proxy configurations.
188
− :::image type="content" source="media/how-to-install-macos-client/macos-add-proxy.png" alt-text="Screenshot of the Global Secure Access client would like to add proxy configurations pop-up with the Allow button highlighted.":::
189
+:::image type="content" source="media/how-to-install-macos-client/macos-add-proxy.png" alt-text="Screenshot of the Global Secure Access client would like to add proxy configurations pop-up with the Allow button highlighted.":::
189190
190191
1. After the installation is complete, you might be prompted to sign in to Microsoft Entra.
191
− > [!NOTE]
192
− > If the [Microsoft Enterprise SSO plug-in for Apple devices](../identity-platform/apple-sso-plugin.md) is deployed, the default behavior is to use single sign-on with the credentials entered in the company portal.
192
+> [!NOTE]
193
+> If the [Microsoft Enterprise SSO plug-in for Apple devices](../identity-platform/apple-sso-plugin.md) is deployed, the default behavior is to use single sign-on with the credentials entered in the company portal.
193194
194
−1. The **Global Secure Access - Connected** icon appears in the system tray, indicating a successful connection to Global Secure Access.
195
+8. The **Global Secure Access - Connected** icon appears in the system tray, indicating a successful connection to Global Secure Access.
195196
:::image type="content" source="media/how-to-install-macos-client/macos-client-system-tray-icon-connected.png" alt-text="Screenshot of the system tray with the Global Secure Access - Connected icon highlighted.":::
196197
197198
## Upgrade the Global Secure Access client
⋯ 6 unchanged lines
204205
205206
## Uninstall the Global Secure Access client
206207
To manually uninstall the Global Secure Access client, use either of the following methods:
207
−- Run the **Uninstall Global Secure Access Client** application.
208
+- Run the **Uninstall Global Secure Access Client** application.
208209
209210
Or
210211
211
−- Run the following command:
212
+- Run the following command:
212213
213214
`sudo /Applications/GlobalSecureAccessClient/Global\ Secure\ Access\ Client.app/Contents/Resources/install_scripts/uninstall`
214215
⋯ 5 unchanged lines
220221
221222
|Action |Description |
222223
|---------|---------|
223
−|**Disable** |Disables the client until you enable it again. When you disable the client, you're prompted to enter a business justification and reenter your sign-in credentials. The business justification is logged. |
224
+|**Disable** |Disables the client until the user enables it again. When the user disables the client, they're prompted to enter a business justification and reenter their sign-in credentials. The business justification is logged. |
224225
|**Enable** |Enables the client. |
225
−|**Pause** |Pauses the client for either 10 minutes, until you resume the client, or until the device is restarted. When you pause the client, you're prompted to enter a business justification and reenter your sign-in credentials. The business justification is logged. |
226
+|**Pause** |Pauses the client for either 10 minutes, until the user resumes the client, or until the device is restarted. When the user pauses the client, they're prompted to enter a business justification and reenter their sign-in credentials. The business justification is logged. |
226227
|**Resume** |Resumes the paused client. |
227228
|**Restart** |Restarts the client. |
228229
|**Collect logs** |Collects client logs and archives them in a zip file to share with Microsoft Support for investigation. |
⋯ 5 unchanged lines
234235
235236
|Icon |Message |Description |
236237
|---------|---------|---------|
237
−|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-initializing.png"::: |Global Secure Access Client |The client is initializing and checking its connection to Global Secure Access. |
238
−|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-connected.png"::: |Global Secure Access Client - Connected |The client is connected to Global Secure Access. |
239
−|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-disabled.png"::: |Global Secure Access Client - Disabled |The client is disabled because services are offline or you disabled the client. |
240
−|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-disconnected.png"::: |Global Secure Access Client - Disconnected |The client failed to connect to Global Secure Access. |
241
−|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access Client - 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). |
242
−|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access Client - Disabled by your organization |Your organization disabled the client (that is, all traffic forwarding profiles are disabled). |
243
−|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access - Private Access is disabled |You disabled Private Access on this device. |
244
−|:::image type="icon" source="media/how-to-install-macos-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 a network that requires captive portal sign in. |
238
+|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-initializing.png"::: |Global Secure Access Client |The client is initializing and checking its connection to Global Secure Access. |
239
+|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-connected.png"::: |Global Secure Access Client - Connected |The client is connected to Global Secure Access. |
240
+|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-disabled.png"::: |Global Secure Access Client - Disabled |The client is disabled because services are offline or the user disabled the client. |
241
+|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-disconnected.png"::: |Global Secure Access Client - Disconnected |The client failed to connect to Global Secure Access. |
242
+|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access Client - 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). |
243
+|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access Client - Disabled by your organization |Your organization disabled the client (that is, all traffic forwarding profiles are disabled). |
244
+|:::image type="icon" source="media/how-to-install-macos-client/global-secure-access-client-icon-warning.png"::: |Global Secure Access - Private Access is disabled |The user disabled Private Access on this device. |
245
+|:::image type="icon" source="media/how-to-install-macos-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 a network that requires captive portal sign in. |
245246
246247
## Settings and troubleshooting
247
−From the **Settings** window, you can set different configurations and perform some advanced actions.
248
−The **Settings** window has two tabs:
248
+From the Settings window, you can set different configurations and perform some advanced actions.
249
+The Settings window has two tabs:
249250
250251
### Settings
251252
⋯ 2 unchanged lines
254255
|**Telemetry full diagnostics** |Sends full telemetry data to Microsoft for application improvement. |
255256
|**Enable Verbose Logging** |Enables verbose logging and network capture to be collected when exporting the logs to a zip file. |
256257
257
−:::image type="content" source="media/how-to-install-macos-client/macos-client-settings-toggles.png" alt-text="Screenshot of the macOS Settings and Troubleshooting view, with the Settings tab selected.":::
258
+:::image type="content" source="media/how-to-install-macos-client/macos-client-settings-toggles.png" alt-text="Screenshot of the macOS Settings and Troubleshooting view, with the Settings tab selected.":::
258259
259260
### Troubleshooting
260261
⋯ 45 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 01:13 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.