Skip to content

Update OS settings (configuration profiles) guide #37982

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

Merged
noahtalerman merged 14 commits into from
Jan 27, 2026
Merged

Update OS settings (configuration profiles) guide #37982

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
ecf54f7
Update OS settings (configuration profiles) guide
noahtalerman Jan 7, 2026
04f6a53
Fix typos in Wi-Fi certificate documentation
noahtalerman Jan 7, 2026
909ad37
Update articles/connect-end-user-to-wifi-with-certificate.md
noahtalerman Jan 7, 2026
3940166
Update articles/custom-os-settings.md
noahtalerman Jan 7, 2026
331697f
Update articles/custom-os-settings.md
noahtalerman Jan 7, 2026
5e9b8a0
Update articles/custom-os-settings.md
noahtalerman Jan 7, 2026
5319a46
Update articles/custom-os-settings.md
noahtalerman Jan 7, 2026
dd92adc
Update articles/custom-os-settings.md
noahtalerman Jan 7, 2026
44af0d5
Update verification details for OS settings
noahtalerman Jan 7, 2026
a45762b
Merge branch 'main' into noahtalerman-patch-51
noahtalerman Jan 8, 2026
3bc12da
Update custom-os-settings.md
noahtalerman Jan 12, 2026
036ab03
Merge branch 'main' into noahtalerman-patch-51
noahtalerman Jan 13, 2026
f0910b1
Merge branch 'main' into noahtalerman-patch-51
noahtalerman Jan 14, 2026
d7e8780
Merge branch 'main' into noahtalerman-patch-51
noahtalerman Jan 26, 2026
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
5 changes: 2 additions & 3 deletions articles/connect-end-user-to-wifi-with-certificate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -598,7 +598,6 @@ You can add any other options listed under Device/SCEP in the [Microsoft documen
</Exec>
```

> Currently only device scoped SCEP profiles are supported for Windows devices.
</details>

## Custom EST (Enrollment over Secure Transport)
Expand Down Expand Up @@ -752,9 +751,9 @@ If an end user is on vacation (offline for more than 30 days), their certificate

## Advanced

### User scoped certificates
### User-scoped certificates

You can deploy a user scoped certificate on macOS and Windows hosts using a user scoped configuration profile.
You can deploy a user-scoped certificate on macOS and Windows hosts using a user-scoped configuration profile.

1. Follow the instructions above to connect Fleet to your certificate authority (CA).
2. Create a certificate [configuration profile](#example-configuration-profiles). For Windows, replace `./Device` with `./User` in all `<LocURI>` elements. For macOS, set `PayloadScope` to `User`.
Expand Down
72 changes: 50 additions & 22 deletions articles/custom-os-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,14 @@ Fleet API: Use the [Add custom OS setting (configuration profile) endpoint](http

### Device and user scope

Currently, on macOS hosts, Fleet supports enforcing OS settings at the device (device-scoped) and user (user-scoped) levels. User-scoped declaration (DDM) profiles and iOS, iPadOS, and Windows configuration profiles are coming soon.
Currently, on macOS and Windows hosts, Fleet supports enforcing OS settings at the device (device-scoped) and user (user-scoped) levels. The iOS, iPadOS, and Android platforms only support device-scoped configuration profiles. User-scoped declaration (DDM) profiles for macOS are coming soon.

If a host is automatically enrolled (via [ADE](https://support.apple.com/en-us/102300)), user-scoped profiles are delivered to the user that was created during first time setup. For hosts that enrolled and turned on MDM manually, user-scoped profiles are delivered to the user that turned on MDM on the **Fleet Desktop > My device** page.
If a macOS host is automatically enrolled (via [ADE](https://support.apple.com/en-us/102300)), user-scoped profiles are delivered to the user that was created during first time setup. For Macs that enrolled and turned on MDM manually, user-scoped profiles are delivered to the user that turned on MDM on the **Fleet Desktop > My device** page.

How to deliver user-scoped configuration profiles:

#### macOS

1. If you use iMazing Profile Creator, open your configuration profile in iMazing, select the **General** tab and update the **Payoad Scope** to **User**.
2. If you edit your configuration profiles in a text editor, open the configuraiton profile in your text editor, find or add the `PayloadScope` key, and set the value to `User`. Here's an example `.mobileconfig` snippet:

Expand All @@ -49,13 +52,19 @@ How to deliver user-scoped configuration profiles:
</plist>
```

#### Upgrading to 4.71.0
#### Windows

1. Head to the [Windows configuration profiles (CSPs) documentation](https://learn.microsoft.com/en-us/windows/client-management/mdm/policy-configuration-service-provider) to verify that all the settings in your Windows profile support the user scope. For example, the [SCEP setting](https://learn.microsoft.com/en-us/windows/client-management/mdm/clientcertificateinstall-csp#devicescep) supports both the device and user scope.
Copy link
Member Author

@noahtalerman noahtalerman Jan 7, 2026

Choose a reason for hiding this comment

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

@JordanMontgomery what do you think?

Copy link
Member

@JordanMontgomery JordanMontgomery Jan 7, 2026

Choose a reason for hiding this comment

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

Looks great

2. To make a Windows configuration profiles user-scoped, replace `./Device` with `./User` in all `<LocURI>` elements.
Copy link
Member

@mike-j-thomas mike-j-thomas Jan 9, 2026

Choose a reason for hiding this comment

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

@noahtalerman, should this be a Windows configuration profile or Windows configuration profiles? Also, user scoped is the correct grammar for this sentence. It only needs to be hyphenated when modifying a noun, e.g., "user-scoped certificates."

Copy link
Member Author

@noahtalerman noahtalerman Jan 12, 2026

Choose a reason for hiding this comment

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

@mike-j-thomas I went with your Windows configuration profile to be consistent with step 1.

Also, user scoped is the correct grammar for this sentence. It only needs to be hyphenated when modifying a noun, e.g., "user-scoped certificates."

Got it! Fixed.


#### Upgrading from below 4.71.0

Fleet added support for user-scoped macOS configuration profiles in Fleet 4.71.0. If you're upgrading Fleet from a version below 4.71.0, here's how to prepare your already enrolled hosts for macOS user-scoped configuration profiles:

When upgrading to 4.71.0, here's how to prepare your already enrolled hosts for user-scoped configuration profiles:
1. If the host automatically enrolled to Fleet (via ADE), you don't need to take action. Fleet added support for the user-scoped configuration profiles on these hosts.
2. To deliver user-scoped profiles to hosts that manually enrolled and turned on MDM, first turn off MDM and ask end user to [turn on MDM](https://fleetdm.com/guides/mdm-migration#migrate-hosts:~:text=If%20the%20host%20is%20not%20assigned%20to%20Fleet%20in%20ABM%20(manual%20enrollment)%2C%20the%20end%20user%20will%20be%20given%20the%20option%20to%20download%20the%20MDM%20enrollment%20profile%20on%20their%20My%20device%20page.) through the **My device** page.

When upgrading to Fleet 4.71.0, here's how to update configuration profiles that are already installed on hosts so that they're delivered to the user scope:
Edit user-scoped configuration profiles that are already installed on hosts:

1. Check for profiles with `PayloadScope` set to `User`. Already deployed profiles with `PayloadScope` set to `User` won’t be re-installed on hosts automatically.
2. To change them to the user-scope, update the `PayloadIdentifier`, re-add the profile to Fleet, and delete the old profile. This will uninstall the device-scope profile and install the profile in the user scope. If you're using [GitOps](https://fleetdm.com/docs/configuration/yaml-files), just update the `PayloadIdentifier` and run GitOps.
Expand All @@ -68,23 +77,42 @@ If you want to make sure the profile stays device-scoped, update `PayloadScope`

In the Fleet UI, head to the **Controls > OS settings** tab.

In the top box, with "Verified," "Verifying," "Pending," and "Failed" statuses, click each status to view a list of hosts:
In the top box, with "Verified," "Verifying," "Pending," and "Failed" statuses, click each status to view a list of hosts.

### Verified

Hosts that applied all OS settings.

For macOS configuration profiles and device-scoped Windows profiles, Fleet verified by running an osquery query. It can take up to 1 hour ([configurable](https://fleetdm.com/docs/configuration/fleet-server-configuration#osquery-detail-update-interval)) for these profiles to move from "Verifying" to "Verified".
Copy link
Member Author

@noahtalerman noahtalerman Jan 7, 2026

Choose a reason for hiding this comment

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

@JordanMontgomery is this "1 hour" part accurate?

cc @ddribeiro

Copy link
Member

@JordanMontgomery JordanMontgomery Jan 7, 2026

Choose a reason for hiding this comment

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

@noahtalerman that is correct. If the host is online it should happen within 1 hour


macOS declarations profiles are verified with a [DDM StatusReport](https://developer.apple.com/documentation/devicemanagement/statusreport)).

User-scoped Windows profiles are "Verified" after Fleet gets a [200 response](https://learn.microsoft.com/en-us/windows/client-management/oma-dm-protocol-support#syncml-response-status-codes) from the Windows MDM protocol.

iOS and iPadOS hosts are "Verified" after they acknowledge all MDM commands to apply OS settings. Android hosts are "Verified" after Fleet verifies that the settings is applied in the next [status report](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices).

### Verifying

Hosts that acknowledged all MDM commands to apply OS settings. Fleet is verifying. If the profile wasn't delivered, Fleet will redeliver the profile.

For Windows profiles, when Fleet gets a [200 response](https://learn.microsoft.com/en-us/windows/client-management/oma-dm-protocol-support#syncml-response-status-codes) from the Windows MDM protocol, device-scoped profiles are "Verifying" but, currently, user-scoped Windows profiles go straight to "Verified."

* **Verified**: hosts that applied all OS settings. Fleet verified by running an osquery query on Windows and macOS hosts (declarations profiles are verified with a [DDM StatusReport](https://developer.apple.com/documentation/devicemanagement/statusreport)). Currently, iOS and iPadOS hosts are "Verified" after they acknowledge all MDM commands to apply OS settings. Android hosts are "Verified" after Fleet verifies that the settings is applied in the next [status report](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices).
### Pending

* **Verifying**: hosts that acknowledged all MDM commands to apply OS settings. Fleet is verifying. If the profile wasn't delivered, Fleet will redeliver the profile.
Hosts that are running MDM commands or will run MDM commands to apply OS settings when they come online.

* **Pending**: hosts that are running MDM commands or will run MDM commands to apply OS settings when they come online.
### Failed

* **Failed**: hosts that failed to apply OS settings. For Windows profiles, status codes are listed in [Microsoft's OMA DM docs](https://learn.microsoft.com/en-us/windows/client-management/oma-dm-protocol-support#syncml-response-status-codes).
Hosts that failed to apply OS settings. For Windows profiles, status codes are listed in [Microsoft's OMA DM docs](https://learn.microsoft.com/en-us/windows/client-management/oma-dm-protocol-support#syncml-response-status-codes).

In the list of hosts, click on an individual host and click the **OS settings** item to see the status for a specific setting.

Currently, when editing a profile using Fleet's GitOps workflow, it can take 30 seconds for the
profile's status to update to "Pending."

For Windows configuration profiles with the [Win32 and Desktop Bridge app ADMX
policies](https://learn.microsoft.com/en-us/windows/client-management/win32-and-centennial-app-policy-configuration), Fleet only verifies that the host returned a success status code in response to the MDM command to install the configuration profile. You can query the registry keys defined by the ADMX policy. For instance, if an ADMX file defines the following policy:
### Special Windows behavior

For Windows configuration profiles with the [Win32 and Desktop Bridge app ADMX policies](https://learn.microsoft.com/en-us/windows/client-management/win32-and-centennial-app-policy-configuration), Fleet only verifies that the host returned a success status code in response to the MDM command to install the configuration profile. You can query the registry keys defined by the ADMX policy. For instance, if an ADMX file defines the following policy:
```
<policy name="Subteam" class="Machine" displayName="Subteam" key="Software\Policies\employee\Attributes" explainText="Subteam" presentation="String">
<parentCategory ref="DefaultCategory" />
Expand All @@ -102,27 +130,27 @@ SELECT data FROM registry WHERE path = 'HKEY_LOCAL_MACHINE\Software\Policies\emp

> If your Windows profile fails with the following error: "The MDM protocol returned a success but the result couldn’t be verified by osquery", and the profile includes `[!CDATA []]` sections, [escape the XML](https://www.freeformatter.com/xml-escape.html) instead of using CDATA. For example, `[!CDATA[<enabled/>]]>` should be changed to `&lt;enabled/&gt;`.

### Broken profiles
### Special Android behvaior

On Android, if some settings from the profile fail (e.g. incompatible device), other settings from the profile will still be applied. Failed settings will be surfaced on **Host > OS settings**.
Also, some settings from the profile might be overridden by another configuration profile, which means if multiple profiles include the same setting, the profile that is delivered most recently will be applied.

The error message will provide the reason from the Android Management API (AMAPI) for why certain settings are not applied. Possible reasons are listed in the [AMAPI docs](https://developers.google.com/android/management/reference/rest/v1/NonComplianceReason).

## Broken profiles

If one or more labels included in the profile's scope are deleted, the profile will not apply to new hosts that enroll.

On macOS, iOS, iPadOS, and Windows, a broken profile will not remove the enforcement of the OS settings applied to existing hosts. To enforce the OS setting on new hosts, delete it and upload it again.

On Android hosts, a broken profile will remove the enforcement of the OS settings for existing hosts. To enforce the OS setting on existing and new hosts, delete it and upload it again.

### Unmanaged profiles (macOS, iOS, and iPadOS)
## Unmanaged profiles

Profiles installed manually by the end user aren't managed by Fleet. They're not visible and can't be removed from the host via Fleet. Additionally, if a backup is migrated to a new host using [Apple's Migration Assistant](https://support.apple.com/en-us/102613) and it contains configuration profiles, those profiles aren't managed.
macOS, iOS, and iPadOS profiles installed manually by the end user aren't managed by Fleet. They're not visible and can't be removed from the host via Fleet. Additionally, if a backup is migrated to a new host using [Apple's Migration Assistant](https://support.apple.com/en-us/102613) and it contains configuration profiles, those profiles aren't managed.

To manually remove unmanaged profiles, ask the end user to go to **System Settings > General > Device Management**, select the profile, and select the **- (minus)** button at the bottom of the list.

### Partial failure (Android)

On Android, if some settings from the profile fail (e.g. incompatible device), other settings from the profile will still be applied. Failed settings will be surfaced on **Host > OS settings**.
Also, some settings from the profile might be overridden by another configuration profile, which means if multiple profiles include the same setting, the profile that is delivered most recently will be applied.

The error message will provide the reason from the Android Management API (AMAPI) for why certain settings are not applied. Possible reasons are listed in the [AMAPI docs](https://developers.google.com/android/management/reference/rest/v1/NonComplianceReason).

<meta name="category" value="guides">
<meta name="authorGitHubUsername" value="noahtalerman">
<meta name="authorFullName" value="Noah Talerman">
Expand Down
Loading