GSA macOS client prerequisites and installation
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/entra-docs · commit fc49cf5 · +96 −96 lines · also on GitHub
⋯ 1 unchanged line
22
title: The Global Secure Access Client for macOS
33
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.
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
⋯ 8 unchanged lines
1717
1818
## Prerequisites
1919
20
−- A Mac device with an Intel, M1, M2, M3, or M4 processor running macOS version 13 or later.
20
+- A Mac device with an Intel, M1, M2, M3, or M4 processor running macOS version 14 or later.
2121
- A device registered to a Microsoft Entra tenant using Company Portal.
2222
- A Microsoft Entra tenant onboarded to Global Secure Access.
2323
- An internet connection.
⋯ 1 unchanged line
2525
2626
## Download the client
2727
28
−The most current version of the Global Secure Access client is available to download from the Microsoft Entra admin center.
28
+You can download the most current version of the Global Secure Access client from the Microsoft Entra admin center.
2929
3030
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).
3131
1. Browse to **Global Secure Access** > **Connect** > **Client download**.
⋯ 8 unchanged lines
4040
4141
`sudo installer -pkg ~/Downloads/GlobalSecureAccessClient.pkg -target / -verboseR`
4242
43
−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.
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.
4444
4545
### Deploy with Microsoft Intune
4646
To deploy the Global Secure Access client .pkg through Microsoft Intune as a managed app:
⋯ 3 unchanged lines
5050
1. In the **Select app type** pane, under **Other** app types, select **macOS app (PKG)** and select **Select**.
5151
1. On the **App package file** tab, select **Select app package file**, browse to the GlobalSecureAccessClient.pkg file, and select **OK**.
5252
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 13.0** and select **Next**.
53
+1. On the **Requirements** tab, set the minimum operating system to **macOS 14.0** and select **Next**.
5454
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**.
5555
1. On the **Assignments** tab, assign the app to the appropriate device or user groups and select **Next**.
5656
1. Review the configuration and select **Create**.
⋯ 1 unchanged line
5858
### Allow system extensions through mobile device management (MDM)
5959
6060
> [!IMPORTANT]
61
−> 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.
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.
6262
63
−The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management) and you can adapt them for different MDMs:
63
+The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management). You can adapt them for different MDMs.
6464
6565
1. In the Microsoft Intune admin center, select **Devices** > **Manage devices** > **Configuration** > **Policies** > **Create** > **New policy**.
6666
1. Create a profile with a **Platform** of **macOS** and a **Profile type** set to **Settings catalog**. Select **Create**.
⋯ 7 unchanged lines
7474
1. In the list of **Allowed System Extensions**, select **+ Edit instance**.
7575
1. In the **Configure instance** dialog, configure the System Extensions payload settings with the following entries:
7676
77
−|Bundle identifier |Team identifier |
78
−|---------|---------|
79
−|com.microsoft.globalsecureaccess.tunnel |UBF8T346G9 |
80
−|com.microsoft.globalsecureaccess |UBF8T346G9 |
77
+ |Bundle identifier |Team identifier |
78
+ |---------|---------|
79
+ |com.microsoft.globalsecureaccess.tunnel |UBF8T346G9 |
80
+ |com.microsoft.globalsecureaccess |UBF8T346G9 |
8181
82
−10. Select **Save** and **Next**.
82
+1. Select **Save** and **Next**.
8383
1. On the **Scope tags** tab, add tags as appropriate.
8484
1. On the **Assignments** tab, assign the profile to a group of macOS devices or users.
8585
1. On the **Review + create** tab, review the configuration and select **Create**.
8686
8787
### Allow transparent application proxy through MDM
88
−The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management) and you can adapt them for different MDMs:
88
+The following instructions are for [Microsoft Intune](/mem/intune/apps/apps-win32-app-management). You can adapt them for different MDMs.
8989
9090
1. In the Microsoft Intune admin center, select **Devices** > **Manage devices** > **Configuration** > **Policies** > **Create** > **New policy**.
9191
1. Create a profile for the macOS platform based on a template of type **Custom** and select **Create**.
⋯ 3 unchanged lines
9595
1. Keep **Deployment channel** set to "Device channel."
9696
1. Upload an .xml file that contains the following data:
9797
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
−```
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
+ ```
166166
167
−7. Complete the creation of the profile by assigning users and devices according to your needs.
167
+1. Complete the creation of the profile by assigning users and devices according to your needs.
168168
169169
### Manual interactive installation
170170
To manually install the Global Secure Access client:
171
−1. Run the GlobalSecureAccessClient.pkg setup file. The **Install** wizard launches. Follow the prompts.
171
+1. Run the `GlobalSecureAccessClient.pkg` setup file. The **Install** wizard launches. Follow the prompts.
172172
1. On the **Introduction** step, select **Continue**.
173173
1. On the **License** step, select **Continue** and then select **Agree** to accept the license agreement.
174174
:::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
176176
1. On the **Summary** step, when the installation is complete, select **Close**.
177177
1. Allow the Global Secure Access system extension.
178178
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.":::
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.":::
180180
181181
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.":::
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.":::
183183
184184
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.":::
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.":::
186186
187187
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.":::
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.":::
189189
190190
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.
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.
193193
194
−8. The **Global Secure Access - Connected** icon appears in the system tray, indicating a successful connection to Global Secure Access.
194
+1. The **Global Secure Access - Connected** icon appears in the system tray, indicating a successful connection to Global Secure Access.
195195
:::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.":::
196196
197197
## Upgrade the Global Secure Access client
⋯ 22 unchanged lines
220220
221221
|Action |Description |
222222
|---------|---------|
223
−|**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. |
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. |
224224
|**Enable** |Enables the client. |
225
−|**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. |
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. |
226226
|**Resume** |Resumes the paused client. |
227227
|**Restart** |Restarts the client. |
228228
|**Collect logs** |Collects client logs and archives them in a zip file to share with Microsoft Support for investigation. |
⋯ 7 unchanged lines
236236
|---------|---------|---------|
237237
|:::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. |
238238
|:::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 the user disabled the client. |
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. |
240240
|:::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. |
241241
|:::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). |
242242
|:::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 |The user disabled Private Access on this device. |
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. |
244244
|:::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. |
245245
246246
## 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:
247
+From the **Settings** window, you can set different configurations and perform some advanced actions.
248
+The **Settings** window has two tabs:
249249
250250
### Settings
251251
⋯ 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.