> For the complete documentation index, see [llms.txt](https://support.goodaccess.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.goodaccess.com/configuration-guides/macos.md).

# macOS

Full documentation for the GoodAccess macOS Client Application, including mass distribution using MDM.

## Requirements

* macOS 15.6 (Sequoia) or later
* Administrator rights for the first-time setup, unless your organization deploys GoodAccess through MDM (see [MDM deployment](#mdm-deployment))

## Installation

GoodAccess for macOS is distributed as a single installer package: **`GoodAccess.pkg`**. The package is signed and notarized by Apple.

1. Download `GoodAccess.pkg`.
2. Open it and follow the installer. macOS asks for an administrator password.
3. GoodAccess is installed to `/Applications/GoodAccess.app`.

> Install GoodAccess only from the PKG. Copying the app manually, for example from another Mac, leaves it owned by your user account instead of the system, and macOS will not start the GoodAccess helper. The app then shows: *"GoodAccess is not owned by root… Reinstall GoodAccess using the installer package."*

[Download GoodAccess.pkg](https://link.goodaccess.com/download-mac-pkg)

## First launch (onboarding)

On first launch, GoodAccess guides you through a short setup and shows only the steps that still need doing. If a permission is revoked later, its step comes back the next time onboarding runs.

| Step                                  | What it does                                                                                                                                                                                                      | Required                         | Admin rights |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------ |
| **PIN Setup**                         | Protects the app with a PIN, and optionally Touch ID. Shown only if your organization requires a PIN.                                                                                                             | If required by your organization | No           |
| **Get Notified**                      | Allows notifications about connection status: connecting, reconnecting, disconnects, no internet connection, MFA required, Device Posture Check results, available updates, and messages from your administrator. | No (recommended)                 | No           |
| **Allow Network Extension**           | Approves the GoodAccess system network extension that routes your traffic through the VPN. **WireGuard cannot work without it.**                                                                                  | **Yes**                          | **Yes**      |
| **Enable Automatic Updates** (helper) | Allows the GoodAccess helper to run in the background. The helper installs app updates and runs the OpenVPN protocol.                                                                                             | **Yes**                          | **Yes**      |
| **Launch at login**                   | Starts GoodAccess automatically when you log in. You can change this later in Settings › Behavior › *Run on system startup*.                                                                                      | No                               | No           |

### Allowing the Network Extension

1. Click **Allow**. macOS shows the dialog *"GoodAccess" would like to use a new network extension*.
2. Click **Open System Settings**, not **OK**.

   > ⚠️ The blue **OK** button only closes the dialog. It does **not** enable the extension. If you clicked OK by mistake, open System Settings manually and continue with step 3.
3. In **System Settings › General › Login Items & Extensions**, find GoodAccess under *Extensions*, click **ⓘ** and enable **Network Extension**.
4. Enter an administrator name and password.

### Allowing the helper (background activity)

1. Click **Allow Helper**. macOS shows an **App Background Activity** notification in the top right corner of the screen: *"GoodAccess" can run in the background for all users. Do you want to allow this?*
2. Hover over the notification, click **Options** and choose **Allow**.
3. Enter an administrator name and password.

If the notification disappeared, or you chose *Don't Allow*, open **System Settings › General › Login Items & Extensions** and turn on GoodAccess under *Background App Activity*.

Users without administrator rights cannot complete these two steps themselves. Their IT department can pre-approve both components through MDM (see [MDM deployment](#mdm-deployment)).

### First connection: allowing the VPN configuration

The first time you click **Connect** using **WireGuard** or **IKEv2**, macOS shows the dialog *"GoodAccess" Would Like to Add VPN Configurations. All network activity on this Mac may be filtered or monitored when using VPN.*

Click **Allow**. GoodAccess cannot connect without this approval.

> ⚠️ The blue button is **Don't Allow**. **Allow** is the grey button on the left.

No administrator rights are needed, and the dialog also appears on Macs managed through MDM. OpenVPN does not show this dialog.

## Running from the menu bar

GoodAccess runs in the macOS **menu bar** (the icon at the top right of the screen). Closing the window does not quit the app or disconnect the VPN. Click the menu bar icon to:

* see the current status (Connected, Connecting, Reconnecting, Disconnecting, Disconnected)
* connect to or disconnect from a gateway
* show or hide the app window
* quit the app

## VPN protocols

GoodAccess for macOS supports three protocols:

| Protocol      | Depends on                                                     |
| ------------- | -------------------------------------------------------------- |
| **WireGuard** | Network Extension (onboarding step *Allow Network Extension*)  |
| **IKEv2**     | Built-in macOS VPN; no extra component                         |
| **OpenVPN**   | GoodAccess helper (onboarding step *Enable Automatic Updates*) |

You can choose your preferred protocol in **Settings › Connection**.

## Languages

The app is available in:

* English
* Czech (Čeština)
* German (Deutsch)
* Spanish (Español)
* French (Français)
* Italian (Italiano)
* Japanese (日本語)
* Polish (Polski)
* Portuguese (Português, Brazil)

You can change the language in **Settings › Language**. The change takes effect after the app is relaunched.

## Updates

### How automatic updates work

* When an update is available, it is **downloaded and installed automatically in the background**, with no prompts.
* The new version takes effect after the app is relaunched. GoodAccess shows *"A new version is ready. Relaunch the app to apply the update."* You can relaunch right away or leave it for later; the update will also apply on the next normal relaunch.
* **Forced relaunch:** for security reasons GoodAccess can set a deadline for an update. Once the deadline passes, the app relaunches itself and the VPN connection is briefly interrupted.

### Checking for updates manually

Open **Settings** and click the version label at the bottom (**Version x.y.z / Check for updates**). When an update is waiting, the label shows a red dot and **Update available**.

### Turning automatic updates off

End users cannot turn automatic updates off. Organizations that want to control which version is installed must deploy GoodAccess through an MDM solution such as Jamf or Microsoft Intune, using the update policy profile described in [MDM deployment](#mdm-deployment).

## MDM deployment

For managed Macs, GoodAccess provides two configuration profiles:

| Profile                                | Purpose                                                                                                                                                     | Who needs it             |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `GoodAccess.mobileconfig`              | Pre-approves the Network Extension and the background helper, so users **without administrator rights** can set up and use GoodAccess with no admin prompts | Every managed deployment |
| `GoodAccess-UpdatePolicy.mobileconfig` | Turns off automatic updates; the administrator deploys new versions instead                                                                                 | Optional                 |

### Requirements

* The Mac must be enrolled in MDM with **User-Approved MDM** status. This is automatic for Apple Business Manager or Apple School Manager (Automated Device Enrollment) enrollments.
* Profiles must be delivered **by the MDM**. A `GoodAccess.mobileconfig` installed manually (by double-clicking it) does **not** pre-approve anything; this is standard macOS behavior.

### Deployment steps

1. Upload `GoodAccess.mobileconfig` to your MDM as a custom configuration profile (device level) and scope it to the target Macs.
2. *(Optional)* Do the same with `GoodAccess-UpdatePolicy.mobileconfig`.
3. Deploy `GoodAccess.pkg` through your MDM's software distribution. Make sure the profiles reach the Mac **before** the user first opens GoodAccess; otherwise the user still sees the admin prompts.

Result: GoodAccess installs silently and the user goes through onboarding without any admin prompt.

### Keeping the package in your MDM up to date

Replace `GoodAccess.pkg` in your MDM with the latest version regularly, **even if automatic updates stay on**. Automatic updates only update Macs where GoodAccess is already installed. The package in your MDM is what every *new* Mac receives.

> Example: you upload GoodAccess 4.8.0 and leave automatic updates on. Existing Macs update themselves over time. A year later, a new employee's Mac still gets 4.8.0 from your MDM, even though the current version is 5.2.10.

### Profile 1: `GoodAccess.mobileconfig` (pre-approval)

| Payload                                  | Pre-approves                                                                                  |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| System Extension policy                  | Network Extension `com.samohyb.GoodAccessMac.WireGuardNetworkExtension`, Team ID `6HDHM5U7LV` |
| Service Management (managed login items) | GoodAccess helper, Team ID `6HDHM5U7LV`                                                       |

> Do **not** add a separate VPN payload (`com.apple.vpn.managed`) for GoodAccess. The app creates and manages its own VPN configuration, and a managed (read-only) one would stop it from connecting.

[Download GoodAccess.mobileconfig](https://link.goodaccess.com/download-mac-extension-mobileconfig)

### Profile 2: `GoodAccess-UpdatePolicy.mobileconfig` (disable automatic updates)

With this profile installed:

* GoodAccess **still checks for updates** but never downloads or installs them.
* The user is told once per version: *"A new version is available. Auto-updates are disabled. Please contact your administrator."* Settings shows a red dot and **Update available**.
* The administrator deploys new versions by pushing the new `GoodAccess.pkg` through the MDM. After that, the app asks the user to relaunch to apply it.
* **Removing the profile** turns automatic updates back on from the next check.

This profile requires GoodAccess **4.8.0 or later**. Older versions ignore it.

[Download GoodAccess-UpdatePolicy.mobileconfig](https://link.goodaccess.com/download-mac-updatepolicy-mobileconfig)

### Step-by-step: Jamf

Before you start, set up a static computer group for the target Macs (for example *GoodAccess – Pilot*). We recommend starting with one test Mac that uses a **standard (non-admin)** account.

**1. Upload the configuration profiles**

1. Go to **Computers › Configuration Profiles › Upload** and upload `GoodAccess.mobileconfig`.
2. Set **Level** to *Computer* and **Distribution Method** to *Install Automatically*. Scope the profile to your target group.
3. Save the profile, then reopen it and check that the payloads still contain the Team ID `6HDHM5U7LV` and the extension `com.samohyb.GoodAccessMac.WireGuardNetworkExtension`.
4. *(Optional)* Upload `GoodAccess-UpdatePolicy.mobileconfig` the same way to turn off automatic updates.

**2. Upload the package**

Go to **Settings › Computer management › Packages › New** and upload `GoodAccess.pkg`.

**3. Create a smart group, so the app installs only after the profile is in place**

1. Go to **Computers › Smart Computer Groups › New** (for example *GoodAccess – Ready to install*).
2. Add the criteria **Computer Group** *member of* your target group **AND** **Profile Name** *has* the name of the uploaded profile (by default *GoodAccess*).

> The value picker for *Profile Name* lists only profiles that are already installed on at least one Mac, so it is empty for a new profile. Close the picker and type the exact profile name into the field.

**4. Create the install policy**

1. Go to **Computers › Policies › New**.
2. **General:** set the trigger to *Recurring Check-in* and **Execution Frequency** to *Once per computer*.
3. **Packages:** add `GoodAccess.pkg` with the action *Install*.
4. **Maintenance:** turn on *Update Inventory*.
5. **Scope:** the smart group from step 3 only.

**5. Verify on the test Mac**

Follow [Verifying on a test Mac](#verifying-on-a-test-mac).

When the test passes, add the remaining Macs to the profile scope first, then to the smart group.

**Deploying new versions (with the update policy profile)**

Upload the new `GoodAccess.pkg` and create a new install policy for that version, or replace the package in the existing policy and flush its logs. A policy set to *Once per computer* does not run again on Macs where it already ran.

### Step-by-step: Microsoft Intune

Intune cannot make an app wait until a configuration profile is installed. Use two Microsoft Entra groups so that the profile reaches each Mac before the app does:

* a **profile group** (for example *GoodAccess – Profile*), which receives the configuration profiles
* an **app group** (for example *GoodAccess – App*), which receives `GoodAccess.pkg`

We recommend starting with one test Mac that uses a **standard (non-admin)** account. Add it to the profile group now and to the app group in step 2.

**1. Upload the configuration profiles**

1. Go to **Devices › macOS › Configuration** and click **Create › New Policy**.
2. Set **Profile type** to *Templates*, choose **Custom** and click **Create**.
3. **Basics:** enter a name, for example *GoodAccess – Extension + Helper approval*.
4. **Configuration settings:**
   * Enter a **Custom configuration profile name**, for example *GoodAccess*.
   * Set **Deployment channel** to *Device channel*.
   * Under **Configuration profile file**, select `GoodAccess.mobileconfig`. The file content appears below; check that it contains the Team ID `6HDHM5U7LV` and the extension `com.samohyb.GoodAccessMac.WireGuardNetworkExtension`.
5. **Scope tags:** keep the default.
6. **Assignments:** under *Included groups*, click **Add groups** and select the profile group.
7. **Review + create:** click **Create**.
8. *(Optional)* Repeat steps 1–7 with `GoodAccess-UpdatePolicy.mobileconfig` to turn off automatic updates.

Open the profile from **Devices › macOS › Configuration** and wait until the test Mac is counted under **Succeeded** in *Device and user check-in status*.

**2. Add the app**

1. Go to **Apps › macOS** and click **Create**. Set **App type** to *macOS app (PKG)* and click **Select**.
2. **App information:** click **Select app package file**, choose `GoodAccess.pkg` and click **OK**. Intune fills in **Name** and **Description** from the file name. Enter **Publisher** (*GoodAccess*); the remaining fields are optional.
3. **Program:** leave both scripts empty.
4. **Requirements:** set **Minimum operating system** to *macOS Sequoia 15.0*. Intune does not offer 15.6, so make sure the target Macs run macOS 15.6 or later (see [Requirements](#requirements)).
5. **Detection rules:** under *Included apps*, keep the bundle ID `com.samohyb.GoodAccessMac` with the app version filled in from the package. Set **Ignore app version**:
   * **Yes** if automatic updates stay on. GoodAccess updates itself, and with *No* Intune would treat the newer installed version as a mismatch and install the older uploaded package over it.
   * **No** if you deploy the update policy profile, so that a newly uploaded version also updates Macs that already have GoodAccess.
6. **Scope tags:** keep the default.
7. **Assignments:** under **Required**, click **Add group** and select the app group.
8. **Review + create:** click **Create**. Keep the page open until Intune finishes uploading the package.

Add the test Mac to the app group.

**3. Verify on the test Mac**

Follow [Verifying on a test Mac](#verifying-on-a-test-mac).

When the test passes, add the remaining Macs to the profile group first. Add each Mac to the app group only after the profile shows it under **Succeeded**.

**Deploying new versions (with the update policy profile)**

Open the app in **Apps › macOS**, replace the package under **Properties › App information**, and check that the app version under **Detection rules** matches the new package. With **Ignore app version** set to *No*, Macs that already have GoodAccess install the new version at their next Intune check-in.

### Verifying on a test Mac

Run these in Terminal:

```sh
# Must report "Yes (User Approved)"
profiles status -type enrollment

# After the user finishes onboarding: must show 6HDHM5U7LV com.samohyb.GoodAccessMac.WireGuardNetworkExtension … [activated enabled]
systemextensionsctl list

# Only with the update policy profile: must print 1
defaults read "/Library/Managed Preferences/com.samohyb.GoodAccessMac" DisableAutomaticUpdates
```

Then log in as the standard user, open GoodAccess and complete onboarding. Neither the Network Extension step nor the helper step should ask for administrator credentials. On the first WireGuard or IKEv2 connection, the user still has to allow the VPN configuration; this is expected and needs no admin rights. In **System Settings › General › Login Items & Extensions**, GoodAccess should be enabled.

## Sending logs to support

Open **Settings › Logs** and click **Export**. Choose **All logs** to include the network extension and helper logs, then send the file to [GoodAccess support](https://www.goodaccess.com/contact/).

## Uninstalling

Drag **GoodAccess** from `/Applications` to the Trash. macOS warns that the app hosts a system extension that will be removed. Click **Continue**.
