GSA macOS client prerequisites and installation
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/entra-docs · commit 038f794 · +83 −83 lines · also on GitHub
⋯ 1 unchanged line
22
title: Install the Global Secure Access Client for macOS
33
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: 02/21/2026
5
+ms.date: 03/30/2026
66
ms.author: jayrusso
77
author: HULKsmashGithub
88
ms.reviewer: lirazbarak
⋯ 9 unchanged lines
1818
1919
## Prerequisites
2020
21
−- A Mac device with an Intel, M1, M2, M3, or M4 processor running macOS version 13 or later.
21
+- A Mac device with an Intel, M1, M2, M3, or M4 processor running macOS version 14 or later.
2222
- A device registered to a Microsoft Entra tenant using Company Portal.
2323
- A Microsoft Entra tenant onboarded to Global Secure Access.
2424
- An internet connection.
⋯ 1 unchanged line
2626
2727
## Download the client
2828
29
−The most current version of the Global Secure Access client is available to download from the Microsoft Entra admin center.
29
+You can download the most current version of the Global Secure Access client from the Microsoft Entra admin center.
3030
3131
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).
3232
1. Browse to **Global Secure Access** > **Connect** > **Client download**.
⋯ 8 unchanged lines
4141
4242
`sudo installer -pkg ~/Downloads/GlobalSecureAccessClient.pkg -target / -verboseR`
4343
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.
44
+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.
4545
4646
### Deploy with Microsoft Intune
4747
To deploy the Global Secure Access client .pkg through Microsoft Intune as a managed app:
⋯ 3 unchanged lines
5151
1. In the **Select app type** pane, under **Other** app types, select **macOS app (PKG)** and select **Select**.
5252
1. On the **App package file** tab, select **Select app package file**, browse to the GlobalSecureAccessClient.pkg file, and select **OK**.
5353
1. On the **App information** tab, fill in the required details and select **Next**.
54
−1. On the **Requirements** tab, set the minimum operating system to **macOS 13.0** and select **Next**.
54
+1. On the **Requirements** tab, set the minimum operating system to **macOS 14.0** and select **Next**.
5555
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**.
5656
1. On the **Assignments** tab, assign the app to the appropriate device or user groups and select **Next**.
5757
1. Review the configuration and select **Create**.
⋯ 1 unchanged line
5959
### Allow system extensions through mobile device management (MDM)
6060
6161
> [!IMPORTANT]
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.
62
+> 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.
6363
64
−The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management) and you can adapt them for different MDMs:
64
+The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management). You can adapt them for different MDMs.
6565
6666
1. In the Microsoft Intune admin center, select **Devices** > **Manage devices** > **Configuration** > **Policies** > **Create** > **New policy**.
6767
1. Create a profile with a **Platform** of **macOS** and a **Profile type** set to **Settings catalog**. Select **Create**.
⋯ 7 unchanged lines
7575
1. In the list of **Allowed System Extensions**, select **+ Edit instance**.
7676
1. In the **Configure instance** dialog, configure the System Extensions payload settings with the following entries:
7777
78
−|Bundle identifier |Team identifier |
79
−|---------|---------|
80
−|com.microsoft.globalsecureaccess.tunnel |UBF8T346G9 |
81
−|com.microsoft.globalsecureaccess |UBF8T346G9 |
78
+ |Bundle identifier |Team identifier |
79
+ |---------|---------|
80
+ |com.microsoft.globalsecureaccess.tunnel |UBF8T346G9 |
81
+ |com.microsoft.globalsecureaccess |UBF8T346G9 |
8282
83
−10. Select **Save** and **Next**.
83
+1. Select **Save** and **Next**.
8484
1. On the **Scope tags** tab, add tags as appropriate.
8585
1. On the **Assignments** tab, assign the profile to a group of macOS devices or users.
8686
1. On the **Review + create** tab, review the configuration and select **Create**.
8787
8888
### Allow transparent application proxy through MDM
89
−The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management) and you can adapt them for different MDMs:
89
+The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management). You can adapt them for different MDMs.
9090
9191
1. In the Microsoft Intune admin center, select **Devices** > **Manage devices** > **Configuration** > **Policies** > **Create** > **New policy**.
9292
1. Create a profile for the macOS platform based on a template of type **Custom** and select **Create**.
⋯ 3 unchanged lines
9696
1. Keep **Deployment channel** set to "Device channel."
9797
1. Upload an .xml file that contains the following data:
9898
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>
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">
126103
<dict>
127104
<key>PayloadUUID</key>
128
− <string>04e13063-2bb8-4b72-b1ed-45290f91af68</string>
105
+ <string>87cbb424-6af7-4748-9d43-f1c5dda7a0a6</string>
129106
<key>PayloadType</key>
130
− <string>com.apple.vpn.managed</string>
107
+ <string>Configuration</string>
131108
<key>PayloadOrganization</key>
132109
<string>Microsoft Corporation</string>
133110
<key>PayloadIdentifier</key>
⋯ 1 unchanged line
135112
<key>PayloadDisplayName</key>
136113
<string>Global Secure Access Proxy Configuration</string>
137114
<key>PayloadDescription</key>
138
− <string/>
115
+ <string>Add Global Secure Access Proxy Configuration</string>
139116
<key>PayloadVersion</key>
140117
<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>
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>
162164
</dict>
163
− </array>
164
− </dict>
165
−</plist>
166
−```
165
+ </plist>
166
+ ```
167167
168
−7. Complete the creation of the profile by assigning users and devices according to your needs.
168
+1. Complete the creation of the profile by assigning users and devices according to your needs.
169169
170170
### Manual interactive installation
171171
To manually install the Global Secure Access client:
172
−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.
173173
1. On the **Introduction** step, select **Continue**.
174174
1. On the **License** step, select **Continue** and then select **Agree** to accept the license agreement.
175175
:::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
177177
1. On the **Summary** step, when the installation is complete, select **Close**.
178178
1. Allow the Global Secure Access system extension.
179179
1. In the **System Extension Blocked** dialog, select **Open System Settings**.
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.":::
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.":::
181181
182182
1. Allow the Global Secure Access client system extension by selecting **Allow**.
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.":::
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.":::
184184
185185
1. In the **Privacy & Security** dialog, enter your username and password to validate the approval of the system extension. Then select **Modify Settings**.
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.":::
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.":::
187187
188188
1. Complete the process by selecting **Allow** to enable the Global Secure Access client to add proxy configurations.
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.":::
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.":::
190190
191191
1. After the installation is complete, you might be prompted to sign in to Microsoft Entra.
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.
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.
194194
195
−8. The **Global Secure Access - Connected** icon appears in the system tray, indicating a successful connection to Global Secure Access.
195
+1. The **Global Secure Access - Connected** icon appears in the system tray, indicating a successful connection to Global Secure Access.
196196
:::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.":::
197197
198198
## Upgrade the Global Secure Access client
⋯ 22 unchanged lines
221221
222222
|Action |Description |
223223
|---------|---------|
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. |
224
+|**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. |
225225
|**Enable** |Enables the client. |
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. |
226
+|**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. |
227227
|**Resume** |Resumes the paused client. |
228228
|**Restart** |Restarts the client. |
229229
|**Collect logs** |Collects client logs and archives them in a zip file to share with Microsoft Support for investigation. |
⋯ 7 unchanged lines
237237
|---------|---------|---------|
238238
|:::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. |
239239
|:::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. |
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 you disabled the client. |
241241
|:::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. |
242242
|:::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). |
243243
|:::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. |
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 |You disabled Private Access on this device. |
245245
|:::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. |
246246
247247
## Settings and troubleshooting
248
−From the Settings window, you can set different configurations and perform some advanced actions.
249
−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:
250250
251251
### Settings
252252
⋯ 54 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.