Skip to content

docs: fix stale file references in MDM templates #905

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
riccardomanfrin wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −15
Open

docs: fix stale file references in MDM templates #905

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions public/docs-static/files/io.netbird.client.plist
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,17 @@

For MDM platforms that expect a full Configuration Profile instead
of a bare plist (Custom Configuration Profile / .mobileconfig upload),
use docs/netbird-macos.mobileconfig — same keys, additional Payload*
use netbird-macos.mobileconfig — same keys, additional Payload*
envelope.

Editing this file:
- Remove or comment out any key you do NOT want to enforce. The
daemon treats an absent key as "no enforcement" for that field.
- Keep the document well-formed XML. Validate locally with:
plutil -lint docs/io.netbird.client.plist
plutil -lint io.netbird.client.plist
- Keys are camelCase; values are typed (<string>, <true/>, <false/>,
<integer>). See docs/src/pages/client/mdm-integration.mdx (the
public docs page) for the full reference.
<integer>). See https://docs.netbird.io/client/mdm-integration
for the full reference.

Persistence caveat:
macOS wipes /Library/Managed Preferences/ at every boot on
Expand Down
12 changes: 6 additions & 6 deletions public/docs-static/files/netbird-macos.mobileconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,17 @@
/Library/Managed Preferences/io.netbird.client.plist

Read at runtime by the netbird daemon's macOS loader
(client/mdm/policy_darwin.go — Phase 2). Key names match the canonical
lowerCamelCase form used in docs/netbird.admx and the mdm.Key*
(client/mdm/policy_darwin.go). Key names match the canonical
lowerCamelCase form used in netbird.admx and the mdm.Key*
constants in client/mdm/policy.go.

Bundle identifier: io.netbird.client
(confirm against the signed pkg before fleet roll-out)

Distribution:
- sign with `productsign --sign "Developer ID Installer: ..." ...`
before fleet roll-out (Apple-Configurator-2 won't install an
unsigned profile on Sonoma+ without user override).
- sign the profile with your Developer ID Installer identity before
fleet roll-out (Apple-Configurator-2 won't install an unsigned
profile on Sonoma+ without user override).
Comment on lines +19 to +21

@coderabbitai coderabbitai Bot Aug 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Files matching docs-mdm/mobileconfig:\n'
git ls-files | rg '(^|/)netbird-macos\.mobileconfig$|mdm-integration\.mdx$|docs-static/files|docs' || true

printf '\nmobileconfig relevant lines:\n'
sed -n '1,120p' public/docs-static/files/netbird-macos.mobileconfig 2>/dev/null || true

printf '\nmdm integration relevant lines:\n'
sed -n '200,255p' src/pages/client/mdm-integration.mdx 2>/dev/null || true

printf '\nSearch for Developer ID Installer signs/signing/profiles:\n'
rg -n "Developer ID Installer|Apple Configurator|Configuration Profiles|sign the profile|productsign|CMS|Profile Manager|MDM" public src -S || true

Repository: netbirdio/docs

Length of output: 50371

🌐 Web query:

Apple Developer ID Installer certificate configuration profiles Developer ID Signing identity

💡 Result:

Developer ID certificates are used to sign macOS software distributed outside the Mac App Store, allowing Gatekeeper to verify the developer's identity and ensure the software has not been tampered with [1][2]. There are two primary types of Developer ID signing identities, each with a specific purpose [3][4]. Developer ID Application Certificate This certificate is used to sign Mac applications, plug-ins, kernel extensions, system extensions, and disk images [5][6][4]. It is the standard identity for signing the executable code within your software [5]. Developer ID Installer Certificate This certificate is specifically used to sign Mac Installer Packages (.pkg files) [7][8][5]. You must use this certificate when packaging your app for distribution via an installer [7]. It is critical to use the correct certificate; while tools like productsign may technically allow you to sign an installer package with a Developer ID Application certificate, doing so will result in an installer that fails on the destination Mac [7]. Provisioning Profiles While code signing primarily relies on the certificate and private key, some macOS apps may utilize Developer ID provisioning profiles to access advanced capabilities, such as CloudKit and push notifications [8][1][2]. These profiles tie together the developer's certificates and authorized entitlements [9]. If your application requires these advanced features, you must ensure your Developer ID provisioning profile is valid for the installed version of your application to function correctly [8]. Best Practices - Creation: You can generate up to five of each certificate type via your Apple Developer account or Xcode [1][3]. - Notarization: Regardless of which Developer ID certificate you use, all software distributed outside the Mac App Store should be notarized by Apple to provide users with confidence that the software has been scanned for malicious content [2][6]. - Verification: Gatekeeper evaluates the validity of your Developer ID certificate at installation and/or launch [1]. If a Developer ID Installer certificate expires, the package must be re-signed with a valid certificate to remain installable [1]. However, apps already installed and signed with a valid Developer ID Application certificate generally continue to run [8]. - Security: Always maintain backups of your signing identities (the certificate and its private key) [3]. For command-line operations, use productsign or pkgutil to sign and verify your installer packages to ensure they include the required secure timestamps [5].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'netbird-macos.mobileconfig:\n'
cat -n public/docs-static/files/netbird-macos.mobileconfig | sed -n '1,80p'

printf '\nmdm integration lines 210-250:\n'
cat -n src/pages/client/mdm-integration.mdx | sed -n '210,250p'

printf '\nSearch for Apple Configurator/Developer ID Installer in docs/source:\n'
rg -n "Apple Configurator|Developer ID Installer|productsign|CMS signing|Configuration Profile|Configuration Profiles|unsigned profile|MDM.*sign|Profile Manager" public src -S

Repository: netbirdio/docs

Length of output: 11529

🌐 Web query:

Apple MDM configuration profile signing CMS Xsign MobileConfig Profile Manager

💡 Result:

Apple configuration profiles (.mobileconfig) can be signed to guarantee data integrity [1][2]. Signed profiles help prevent unauthorized tampering and, when signed with a trusted certificate, avoid the "Profile is not signed" warning displayed to users [3]. Technical Mechanism Configuration profiles are XML property lists [2][3]. Signing a profile involves wrapping the XML in a CMS (Cryptographic Message Syntax) Signed Data structure [1][4][5]. This is commonly referred to as "CMS signing" or "Xsign" in some contexts [1][6]. The resulting file is a DER-encoded CMS structure containing the original profile [1]. Methods to Sign Profiles There are several standard ways to sign these files: Command Line Interface: The macOS security command is the standard built-in tool for signing profiles [7][8][3]. Command: /usr/bin/security cms -S -N "" -i <input_file>.mobileconfig -o <output_file>.mobileconfig [8][3] The -N flag specifies the certificate's common name from your login keychain [8][3]. Apple Configurator: You can use the Apple Configurator app's graphical interface to sign profiles via the File > Sign Profile menu [8][9]. MDM Tools: Many MDM platforms and associated tools (such as mdmctl) include built-in functionality to sign profiles during the upload or configuration process [7][3][10]. Certificates To sign a profile, you need a digital signing identity (certificate and private key) installed in your keychain [7][3][9]. - Trusted Certificates: For the profile to be trusted by the device without warnings, the signing certificate must be trusted by the device (e.g., issued by an internal CA trusted by your fleet or an Apple Developer ID certificate) [4][7][3]. - Restrictions: You should not use Apple Distribution certificates (intended for App Store code signing) for signing configuration profiles [11]. Key Considerations - Integrity: Signing guarantees that the profile has not been altered since it was signed [1][12]. If a device receives a signed replacement for an existing signed profile, the replacement must be signed by the same issuer, unless it is installed via the MDM protocol [1][6]. - Encryption: In addition to signing, profiles can be encrypted using CMS-enveloped data [1][6]. This is often used for security during over-the-air (OTA) delivery to protect sensitive information [6][12]. - Deployment: While signing is not strictly mandatory for all MDM deployments, it is strongly recommended for production environments to ensure integrity and improve the user experience by eliminating "unsigned" warnings [3].

Citations:

🌐 Web query:

Apple developer guide Configuration Profile Reference signing profiles Developer ID Installer productsign .mobileconfig

💡 Result:

Configuration profiles (.mobileconfig files) are XML property lists that can be cryptographically signed to guarantee data integrity [1][2]. Signing is recommended for production deployments to avoid "Profile is not signed" warnings and to prevent unauthorized tampering [3][4]. Signing Configuration Profiles A configuration profile is signed by wrapping the XML content in a DER-encoded, CMS (Cryptographic Message Syntax) Signed Data structure [2]. Common methods for signing profiles include: 1. GUI Tools: Applications like Apple Configurator allow you to sign a profile via the File menu (File > Sign Profile) by selecting a signing identity from your keychain [3][5]. 2. Command Line: You can use the security cms tool on macOS to sign a profile [4][5]: security cms -S -N "Common Name of Certificate" -i input.mobileconfig -o output.mobileconfig Requirement for Signing Identity: You need a valid code-signing identity (such as a Developer ID Application certificate or an internal CA certificate) installed in your login keychain [4]. While Developer ID Installer certificates are intended for Mac Installer Packages (see below), they may work for signing profiles, though a standard code-signing certificate is generally sufficient [6][4]. Clarification on Developer ID Installer and productsign It is important to distinguish between configuration profiles and Mac Installer Packages: - Configuration Profiles (.mobileconfig): These are signed using the security cms tool as described above [4][5]. - Mac Installer Packages (.pkg): These are software distribution packages that must be signed with a Developer ID Installer certificate [7][8][9]. This is performed using the productsign command-line tool or pkgbuild/productbuild [7][9]. Using a Developer ID Application certificate to sign an installer package will cause the package to fail on the destination Mac [7]. In summary, do not use productsign or Developer ID Installer certificates to sign.mobileconfig files; use the security cms utility with a standard code-signing identity. Conversely, use productsign and Developer ID Installer certificates for macOS installer packages to ensure they are accepted by Gatekeeper [7][9][10].

Citations:

🌐 Web query:

Configuration Profile Reference signing profiles Developer ID Installer productsign productsign MobileConfig Apple

💡 Result:

Apple configuration profiles (.mobileconfig files) can be signed to guarantee data integrity and prevent tampering [1][2]. Signing a profile places the XML property list into a DER-encoded, CMS (Cryptographic Message Syntax) Signed Data structure [2]. It is important to distinguish between signing configuration profiles and signing macOS installer packages: 1. Signing Configuration Profiles: You can sign profiles using various digital identities, provided they are trusted by the target device [3][4]. While a "Developer ID" certificate can be used [4][5], the primary requirement is that the signing certificate forms a chain of trust that the device recognizes [5][6]. In managed environments, this is often achieved by deploying a custom root certificate to devices, which then trusts any profiles signed by certificates issued by that root [3]. When using other certificates, you may need to include the necessary intermediate certificates in the signature so the device can verify the chain of trust [5]. Apple Configurator for Mac provides a built-in interface to sign profiles (File > Sign Profile) [7]. 2. Signing Installer Packages (productsign): The productsign command-line tool is specifically designed for signing macOS installer packages (typically.pkg files), not configuration profiles [8][9]. When signing installer packages for distribution, you must use a Developer ID Installer certificate [8][9]. Using a different certificate type, such as a Developer ID Application certificate, may result in an installer that fails to run on the destination Mac [8][9]. In summary, productsign is the standard tool for signing installer packages with a Developer ID Installer certificate [8][9], whereas configuration profiles are typically signed using tools like Apple Configurator [7] or dedicated MDM solutions [6][10] using a certificate that establishes a valid chain of trust with the target devices [3][5].

Citations:

🌐 Web query:

site:developer.apple.com/Configuration Profile Reference signing profiles Developer ID Installer productsign Apple Configurator Profile Manager CMS

💡 Result:

Relevant Apple documentation:

  • Configuration profiles and CMS signing: Apple says to sign a profile by placing its XML property list in a DER-encoded CMS Signed Data structure. Signed-profile replacements must use the same signing identity unless installed through MDM. [1]
  • Developer ID signing: Developer ID certificates sign Mac apps, plug-ins, and installer packages distributed outside the Mac App Store. [2]
  • Developer ID Installer: Installer packages signed with a Developer ID Installer certificate must have a currently valid certificate when run. [3]
  • Provisioning profiles: Profiles contain signing certificates, device identifiers, and a bundle ID, and are used to sign and install apps. [4]
  • Profile installation: MDM can install configuration profiles and provisioning profiles through dedicated commands. [5]

Sources

[1] (developer.apple.com)
[2] (developer.apple.com)
[3] (developer.apple.com)
[4] (developer.apple.com)
[5] (developer.apple.com)

Citations:

🌐 Web query:

Site:developer.apple.com Configuration Profile Reference "Developer ID Installer" "Configuration Profile"

💡 Result:

In the context of macOS software distribution, there is a distinction between a "Configuration Profile" (a system configuration file) and a "Developer ID Installer" (a signing identity) [1][2][3]. They are not the same thing, though both are involved in the deployment and management of software on macOS [1][4]. A Developer ID Installer is a specific type of digital certificate provided by Apple to developers [2][3]. It is used to sign a Mac Installer Package (PKG) for distribution outside the Mac App Store [2][4]. When a user runs an installer package signed with a Developer ID Installer certificate, Gatekeeper validates the certificate to ensure the software is from a trusted developer [3][4]. If the certificate is valid at the time the installer package is run, the installation can proceed [3]. A Configuration Profile, on the other hand, is an XML file (property list format) used to distribute configuration settings—such as Wi-Fi, VPN, or security restrictions—to macOS and iOS devices [1][5]. These profiles are often deployed via Mobile Device Management (MDM) systems or manually to configure system-level behavior across many devices [1]. While a Developer ID Installer certificate is used to sign the installer, a Configuration Profile is used to manage device settings [1][3]. They do not function as a "Developer ID Installer Configuration Profile." However, they can overlap in administrative workflows: for example, an MDM administrator might use a Configuration Profile to manage security policies (such as System Extension policies or Gatekeeper settings) that affect how an app signed with a Developer ID Installer is allowed to run on managed devices [6]. If you are encountering issues related to "Developer ID" and profiles, it is often due to one of the following: 1. Provisioning Profiles: If your application requires restricted entitlements (e.g., CloudKit, Push Notifications), you may need a Developer ID provisioning profile to authorize those claims, even for direct distribution [2][3][7]. This profile must be included within your app's bundle [7]. 2. System Policy/MDM: If you are managing devices, you might use Configuration Profiles to whitelist or approve software, system extensions, or specific Developer ID team identifiers [6]. For authoritative guidance on configuring profiles, refer to Apple's official Configuration Profile Reference [1]. For details on signing and distribution, consult the Apple Developer documentation regarding Developer ID certificates [3][4].

Citations:

Use configuration-profile signing for the .mobileconfig.

Developer ID Installer targets installer packages, while .mobileconfig files use CMS profile signing or MDM-native profile signing. Replace these instructions with the actual Profile Manager/Apple Configurator/MDM profile-signing workflow, and update src/pages/client/mdm-integration.mdx lines 226-240 with the same corrected workflow.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@public/docs-static/files/netbird-macos.mobileconfig` around lines 19 - 21,
Replace the unsigned .mobileconfig rollout guidance near the profile
instructions with the correct CMS configuration-profile signing workflow using
Apple Configurator, Profile Manager, or the organization’s MDM, and remove the
incorrect Developer ID Installer reference. Apply the same corrected signing and
deployment workflow to the corresponding guidance in the MDM integration
documentation.

- For local dev install: `sudo profiles install -path netbird-macos.mobileconfig`.
- For MDM (Jamf/Kandji/Mosyle/Intune): upload as a Custom Profile.

Expand All @@ -36,7 +36,7 @@
UserDefaults[com.apple.configuration.managed] under a different
payload type (com.apple.app.configuration.managed); the wrapper
structure is the same but the inner payload dictionary differs.
See docs/netbird-ios.mobileconfig (Phase 5) when shipped.
An iOS sample profile is not shipped yet.
-->
<plist version="1.0">
<dict>
Expand Down
8 changes: 4 additions & 4 deletions public/docs-static/files/netbird-macos.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# Push the NetBird MDM policy to a macOS device via JumpCloud Commands.
#
# DESCRIPTION
# This is the macOS counterpart of docs/netbird-policy.reg.ps1.
# This is the macOS counterpart of netbird-policy.reg.ps1.
# It writes the values declared in the "POLICY VALUES" block below to
# the managed-preferences plist that the NetBird daemon's
# client/mdm/policy_darwin.go loader reads on every 1-minute MDM
Expand All @@ -25,7 +25,7 @@
# IMPORTANT: PERSISTENCE
# macOS wipes /Library/Managed Preferences/ at every boot on devices
# that are NOT MDM-enrolled. For a persistent fleet rollout, push the
# companion docs/netbird-macos.mobileconfig as a Custom Configuration
# companion netbird-macos.mobileconfig as a Custom Configuration
# Profile (Admin Console -> MDM -> Mac Custom Configuration Profiles)
# instead of this script. Use this script when:
# - the device is MDM-enrolled (file survives reboots), or
Expand All @@ -49,8 +49,8 @@ set -euo pipefail
#
# Reference for key names + accepted values:
# client/mdm/policy.go (Key* constants)
# docs/netbird-macos.mobileconfig (sample profile)
# docs/netbird.admx + .adml (Windows ADMX schema)
# netbird-macos.mobileconfig (sample profile)
# netbird.admx + netbird.adml (Windows ADMX schema)
#
NULL='__UNSET__'
managementURL='https://api.netbird.io:443'
Expand Down
2 changes: 1 addition & 1 deletion public/docs-static/files/netbird-policy.reg.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
by importing a sidecar netbird-policy.reg file.

.DESCRIPTION
Windows counterpart of docs/netbird-macos.sh. Outcome:
Windows counterpart of netbird-macos.sh. Outcome:
HKLM\Software\Policies\NetBird populated from the attached
netbird-policy.reg file, daemon picks up the change via the
1-minute MDM reload ticker.
Expand Down
Loading