Skip to main content

Safari Deployment

Safari grants a browser extension no website access at install time — unlike Chrome or Edge, there is no "install and it just works" path. Without website access, Surface Security's on-page phishing and credential-risk detectors never run, and the magic-link enrollment page cannot hand off to the extension. This guide covers the two ways to grant that access: a managed configuration pushed by your MDM (recommended for any fleet of supervised Macs), and a manual fallback for unmanaged devices or unsupported macOS versions.


1. Overview​

Two deployment paths, in order of preference:

  • Managed (recommended) — your MDM pushes a Declarative Device Management (DDM) configuration that grants the Surface Security extension "Always Allow on Every Website" automatically, with no end-user prompts. This requires supervised Macs and macOS 15 or later.
  • Manual — the user grants access themselves from Safari's Extensions settings. This is the only option on unmanaged devices or macOS 14.x, and it works as a fallback on any device.

Both paths lead to the same end state: the extension can see and act on every site the user visits, which is what its detectors and the magic-link enrollment flow depend on.


2. Requirements​

  • macOS Safari 16.4 or later on every device, regardless of deployment path. This is the floor at which Safari can install Surface Security's page-level protection hooks; on 16.4 through 17.x they are installed through the scripting API, and from Safari 18 through the extension manifest. Both routes are automatic and need no configuration from you.
  • On Safari versions where the extension cannot open the one-click grant dialog itself, the popup shows the Section 4 steps instead. The manual path works on every supported version.
  • For managed control specifically:
    • Supervised Macs, enrolled via Automated Device Enrollment (Apple Business Manager / Apple School Manager).
    • macOS 15 or later (Declarative Device Management support for com.apple.configuration.safari.extensions.settings requires macOS 15+ on the Mac).
    • An MDM that supports Declarative Device Management.
    • The Surface Security host app installed on the device — Safari App Extensions are managed through their host app, so the app must be present before the configuration can take effect. Note that the host app ships in an upcoming Surface Security release; the managed steps in Section 3 become actionable once it is available.

If any of these are missing, fall back to the manual path in Section 4 for those devices.


Managed deployment has two parts: get the Surface Security host app onto the device, then push the Safari extension settings declaration that grants it website access without a user prompt.

Step 1: Deploy the host app​

Once the Surface Security host app is released (it ships in an upcoming release — see "About the composed identifier" below), deploy it to target Macs through your MDM's normal app deployment mechanism before pushing the extension configuration below. The declaration has no effect until the host app (and the Safari extension it ships) is installed on the device.

Step 2: Deploy the configuration with Jamf Pro​

If you manage your fleet with Jamf Pro, this is the recommended path. On macOS Sequoia (15) and later, Jamf Pro delivers Declarative Device Management configurations — including Safari extension settings — through Blueprints:

  1. Open Blueprints from Jamf Pro's main navigation.
  2. Create a new Blueprint, or edit an existing one, scoped to your target computers (supervised, Automated Device Enrollment Macs running macOS 15+).
  3. Add the Manage Safari extensions configuration to the Blueprint — or supply this declaration as a custom DDM configuration — using the values from scripts/enterprise/safari/extension-settings.example.json.

Jamf Pro's exact screen layout can shift between releases — if the steps above don't match what you see, consult Jamf's current documentation for Blueprints and the Manage Safari extensions configuration. The underlying mechanism (Blueprint-based DDM delivery of com.apple.configuration.safari.extensions.settings) is what matters, and it's stable across Jamf Pro versions that support it.

Deploying with another MDM​

Any MDM that supports Declarative Device Management can deliver the same declaration — Jamf Blueprints are one delivery mechanism for it, not a Surface-specific requirement. If you use a different MDM, consult its documentation for how it surfaces DDM configuration delivery (some call it a "declarative configuration," a "DDM profile," or similar) and supply it the same JSON payload from scripts/enterprise/safari/extension-settings.example.json.

What the configuration does​

The declaration's type is com.apple.configuration.safari.extensions.settings, and its ManagedExtensions payload is keyed by the extension's composed identifier — bundleid (TEAMID) — with these settings:

  • State: "AlwaysOn" — the extension is enabled and the user cannot disable it.
  • AllowedDomains: ["*"] — the extension is granted access to every website with no per-site prompts. This is the recommended setting: a partial allow-list leaves Surface's detectors blind on any site not listed, which defeats the point of always-on monitoring. Don't scope this down unless you have a specific reason to.
  • PrivateBrowsing: "AlwaysOn" — the extension also runs in Private Browsing windows, so detection coverage doesn't have a private-browsing blind spot.
  • DeniedDomains — an optional list for explicit carve-outs (e.g. an internal domain you don't want the extension touching). A denied domain always overrides an allowed one, even under a "*" allow-list. Domains that appear in neither list remain user-configurable through Safari's normal extension settings.

Two top-level fields wrap that payload, and both are required for the declaration to be valid:

  • Identifier — a stable UUID naming this declaration. Pick one when you first create the declaration and never change it; changing it makes the MDM treat it as a brand-new declaration rather than an update.
  • ServerToken — a revision marker for the declaration's current content. Devices use it to decide whether they already have the latest version, so you must set a new value (any unique string — a fresh UUID or a timestamp works) every time you edit the declaration. If you reuse the old token, devices consider themselves up to date and silently keep the previous settings. If your MDM generates DDM declarations for you (Jamf Blueprints does), it manages both fields itself and you only supply the payload values.

About the composed identifier​

The sample file uses placeholder values (REPLACE.EXTENSION.BUNDLE.ID (REPLACETEAMID)) because the Surface Security Safari wrapper app has not shipped yet. The real bundle ID and Apple Developer Team ID will be published here, and in the sample file, once that app is released — do not deploy the placeholder identifier as-is; it will not match any installed extension.


4. Manual fallback (unmanaged or macOS 14.x)​

On devices that aren't supervised, aren't enrolled with an MDM that supports DDM, or are still on macOS 14.x, users grant access themselves:

  1. Open Safari > Settings > Extensions.
  2. Select Surface Security.
  3. Set website access to Always Allow on Every Website.

If the extension is missing this access, its popup and options page show a "Website access required" banner with a Grant Access button. Clicking it triggers the browser's native permission dialog; if the user declines, the banner shows instructions telling them to grant access themselves via Safari > Settings > Extensions > Surface Security > Always Allow on Every Website. The magic-link enrollment page shows the same instructions and continues automatically once access has been granted — there's no need to reload or re-click the link.


5. Verifying deployment​

On a correctly configured device, the Surface Security extension's popup shows no "Website access required" banner — the extension already has the access it needs.

If the banner appears after you've pushed the managed configuration, the profile did not apply. Check, in order:

  1. The Mac is supervised (Automated Device Enrollment) and running macOS 15 or later.
  2. The Surface Security host app is installed on the device.
  3. The composed identifier in your deployed configuration exactly matches the published bundle ID and Team ID for the installed extension.

6. Enrollment​

With the profile in place (or manual access granted), enrollment requires no extra steps: the user clicks their magic link, and the extension — already holding website access — completes enrollment automatically.


7. Known limitations on Safari​

  • Browser-extension inventory is not collected from Safari endpoints. Safari does not expose the WebExtensions management API, so the Surface Security extension cannot enumerate the other extensions installed in Safari the way it can in Chrome, Edge, and Firefox. Safari devices therefore do not contribute to the extension inventory on the dashboard. Native collection through the Surface Security host app is planned for a future release.

Surface Security

This documentation is protected. Enter the password to continue.