diff --git a/articles/automatic-software-install-in-fleet.md b/articles/automatic-software-install-in-fleet.md index 20642166a4..52ef87a498 100644 --- a/articles/automatic-software-install-in-fleet.md +++ b/articles/automatic-software-install-in-fleet.md @@ -25,6 +25,8 @@ SELECT 1 FROM apps WHERE bundle_identifier = 'com.adobe.Reader' AND version_comp ![Install software modal](../website/assets/images/articles/automatic-software-install-install-software-398x259@2x.png) +> If a software title has more than one [custom package](https://fleetdm.com/guides/deploy-software-packages#add-multiple-packages-to-a-software-title), you can select which package to install. Fleet selects the package that was added first by default. Fleet installs the package on hosts within that package's label scope. + Once the software is installed, Fleet will automatically refetch the host's vitals and update the software inventory. Policy automation software installs are automatically attempted up to 3 total times. Each time the policy runs and fails, Fleet triggers the software install again, up to a total of 3 attempts. If the host passes the policy, the retry count resets. diff --git a/articles/connect-end-user-to-wifi-with-certificate.md b/articles/connect-end-user-to-wifi-with-certificate.md index e3f87fcb84..4d8c95e464 100644 --- a/articles/connect-end-user-to-wifi-with-certificate.md +++ b/articles/connect-end-user-to-wifi-with-certificate.md @@ -35,7 +35,7 @@ We'll deploy a certificate with a dynamic SCEP challenge. To deploy certificates ### Step 2: Connect Fleet to Okta's CA -1. In Fleet, head to **Settings > Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificate enrollment**. 2. Select the **Add CA** button and select **Okta CA or Microsoft NDES** in the dropdown. Okta uses NDES under the hood. 3. Enter your **SCEP URL**, **Admin URL**, and **Username** and **Password**. 4. Select **Add CA**. Your Okta CA should appear in the list in Fleet. @@ -77,7 +77,7 @@ The following steps show how to deploy DigiCert certificates. ### Step 3: Connect Fleet to DigiCert -1. In Fleet, head to **Settings > Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificate enrollment**. 2. Select **Add CA** and then choose **DigiCert** in the dropdown. 3. Add a **Name** for your certificate authority. Best practice is all caps snake case (for example, "WIFI_AUTHENTICATION"). This name is used later as a variable name in a configuration profile. 4. If you're using DigiCert One's cloud offering, keep the default **URL**. If you're using a self-hosted (on-prem) DigiCert One, update the URL to match the one you use to log in to your DigiCert One. @@ -211,7 +211,7 @@ Set-Date -Date "2026-03-16 12:00:00" ### Step 2: Connect Fleet to NDES -1. In Fleet, head to **Settings > Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificate enrollment**. 2. Select the **Add CA** button and select **Okta CA or Microsoft NDES** in the dropdown. 3. Enter your **SCEP URL**, **Admin URL**, and **Username** and **Password**. 4. Select **Add CA**. Your NDES certificate authority (CA) should appear in the list in Fleet. @@ -428,6 +428,8 @@ To create a **user-scope** profile, replace `./Device/` with `./User/` in all `< The following steps show how to deploy [Smallstep](https://smallstep.com/) certificates. +> Smallstep is currently supported on macOS, iOS, and iPadOS hosts only. It is not currently supported for Windows hosts. See [fleetdm/fleet#48925](https://github.com/fleetdm/fleet/issues/48925). + ### Step 1: Configure Smallstep with Fleet information Currently, using the Smallstep-Jamf connector is the best practice. Fleet is testing the new Smallstep-Fleet connector. @@ -446,7 +448,7 @@ Currently, using the Smallstep-Jamf connector is the best practice. Fleet is tes ### Step 2: Configure Fleet with Smallstep information -1. In Fleet, go to **Settings > Integrations > Certificates** and click **Add CA**. +1. In Fleet, go to **Settings > Integrations > Certificate enrollment** and click **Add CA**. 2. In the modal, select **Smallstep** from the dropdown and enter a name for your certificate authority (CA). Best practice is all caps snake case (for example, "WIFI_AUTHENTICATION"). This name is used later as a variable name in a configuration profile. @@ -547,7 +549,7 @@ The flow for Hydrant differs from the other certificate authorities (CA's). Whil ### Step 2: Connect Fleet to Hydrant -1. In Fleet, head to **Settings > Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificate enrollment**. 2. Select **Add CA** and then choose **Hydrant EST** in the dropdown. 3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (ex. "WIFI_AUTHENTICATION"). 4. Add your Hydrant EST **URL**. @@ -630,7 +632,7 @@ The following steps show how to deploy certificates from any certificate authori ### Step 1: Connect Fleet to a SCEP CA -1. In Fleet, head to **Settings > Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificate enrollment**. 2. Select the **Add CA** button and select **Custom Simple Certificate Enrollment Protocol (SCEP)** in the dropdown. 3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (for example, "WIFI_AUTHENTICATION"). This name will be used later as a variable name in a configuration profile. 4. Add your **SCEP URL** and **Challenge**. @@ -889,7 +891,7 @@ This step will vary between providers. EST servers require a `username` and `pas ### Step 2: Connect Fleet to the EST server -1. In Fleet, head to **Settings > Integrations > Certificates**. +1. In Fleet, head to **Settings > Integrations > Certificate enrollment**. 2. Select **Add CA** and then choose **Custom Enrollment over Secure Transport (EST)** in the dropdown. 3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (ex. "WIFI_AUTHENTICATION"). 4. Add your EST **URL**. @@ -1038,7 +1040,7 @@ fetch_cert -ca -fleeturl "" -csr CustomerUserNetwo * On **Windows**, SCEP challenge strings should NOT include `base64` encoding or special characters such as `! @ # $ % ^ & * _`, and Common Names (CN) should NOT include `+` characters. * The Windows SCEP client adds ⁠/pkiclient.exe to the SCEP server URL. When using Fleet's SCEP proxy to deploy certificates, Fleet removes it, allowing you to use non-NDES SCEP servers. * On **Windows** hosts, Fleet supports one proxied certificate per configuration profile. To deploy multiple certificates to a host, use a separate configuration profile for each certificate. -* On **Windows** hosts, Fleet will not verify the SCEP profile via osquery. Fleet will mark it as verified, if a successful request went through, even if the certificate is not present. +* On **Windows** hosts, Fleet verifies proxied SCEP certificates (Custom SCEP proxy and NDES) by observing the issued certificate on the host via osquery, and marks the profile **Failed** if the certificate never appears or if the upstream CA returns an error. This requires osquery 5.23.1 or later on the host. See [Verifying Windows SCEP certificates](#verifying-windows-scep-certificates). * On **Windows** hosts, Fleet will not remove deployed certificates when configuration profiles are removed from Fleet or when host is transfered to another fleet. ### Troubleshooting NDES on Windows @@ -1075,6 +1077,22 @@ SCEP proxy: - The static challenge configured for the SCEP server remains in the SCEP profile. +### Verifying Windows SCEP certificates + +When Fleet proxies SCEP certificate issuance for a Windows host (Custom SCEP proxy or Microsoft NDES), it confirms that the certificate was actually issued before reporting the profile as **Verified**. Each host's profile moves through the following statuses, visible on **Host details > OS settings**: + +- **Pending**: the profile is queued for delivery to the host. +- **Verifying**: the host acknowledged the profile and the SCEP exchange is in progress. Fleet has not yet observed the issued certificate on the host. +- **Verified**: Fleet observed the issued certificate on the host. Fleet matches the certificate to the profile using the `$FLEET_VAR_SCEP_RENEWAL_ID` value in the certificate's OU. +- **Failed**: either Fleet's SCEP proxy observed an error from the upstream CA during certificate issuance (for example, `SCEP PKIOperation failed: HTTP 500`), or the certificate was not observed on the host within one hour of delivery (`Fleet did not detect the SCEP certificate on the host after profile was delivered.`). + +To verify Windows SCEP certificates, Fleet requires: + +- Fleet's agent (fleetd) with **osquery 5.23.1 or later** on the host, so Fleet can read the host's installed certificates. +- The `$FLEET_VAR_SCEP_RENEWAL_ID` variable in the profile's `SubjectName` OU (also required for [renewal](#renewal)), so Fleet can match the issued certificate to the profile. + +For [user-scoped certificates](#user-scoped-certificates), Fleet can only observe the certificate while the target user is signed in, so the profile stays **Verifying** until the user logs in. Fleet assumes a single primary user per Windows host. + ### How to get the CAThumbprint for Windows SCEP profiles An example CAThumprint looks like this: `2133EC6A3CFB8418837BB395188D1A62CA2B96A6` diff --git a/articles/custom-os-settings.md b/articles/custom-os-settings.md index e7daf2f4b4..db7f78f768 100644 --- a/articles/custom-os-settings.md +++ b/articles/custom-os-settings.md @@ -10,6 +10,42 @@ For Windows hosts, copy this [Windows configuration profile template](https://fl For Android hosts, copy this [Android configuration profile template](https://fleetdm.com/learn-more-about/example-android-profile) and update the profile using the options available in [Android Management API](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#resource:-policy). To learn how, watch [this video](https://youtu.be/Jk4Zcb2sR1w). To learn more about the different settings availabe for fully managed vs. BYOD Android devices, see [Google's documentation](https://support.google.com/work/android/topic/9621435?hl=en&ref_topic=6151012,6090502,6090491,&sjid=13375704519136380831-NA). +### Apple declarations (DDM) + +For macOS hosts, Fleet supports uploading Apple Declarative Device Management (DDM) profiles as `.json` files. Fleet supports the following declaration types: + +#### Configurations (`com.apple.configuration.*`) +Enforce settings like passcode policies, account configurations, and more. + +The following configuration declarations are not supported: + +- com.apple.configuration.management.status-subscriptions +- com.apple.configuration.watch.enrollment +- com.apple.configuration.app.managed +- com.apple.configuration.package + +#### Assets (`com.apple.asset.*`) +Deploy credentials, certificates, and other assets referenced by configurations. + +Each **asset declaration** `.json` must include a `Type`, `Identifier`, and `Payload` key. Example: + +```json +{ + "Type": "com.apple.asset.data", + "Identifier": "com.example.sudo-config-asset", + "Payload": { + "Reference": { + "DataURL": "https://mdm.yourcompany.com/assets/sudo-config.zip", + "ContentType": "application/zip" + } + } +} +``` + +To upload an asset declaration, use the same workflow (UI, API, or GitOps) as configuration profiles. + +For more complex workflows, such as deploying an in-house app package (`.ipa`), the recommended approach is to host the manifest and package on your own infrastructure and upload the corresponding asset declaration to Fleet. Asset files are raw JSON following Apple's [DDM schema](https://developer.apple.com/documentation/devicemanagement). + ## Enforce You can enforce OS settings using the Fleet UI, Fleet API, or [GitOps](https://fleetdm.com/docs/configuration/yaml-files). @@ -20,9 +56,17 @@ Fleet UI: 2. Choose which fleet you want to add a configuration profile to by selecting the desired fleet in the fleets dropdown in the upper left corner. Fleets are available in Fleet Premium. -3. Select **Add profile** and choose your configuration profile. +3. Select either **Profiles** or **Assets** from the sub menu. + - To add a configuration profile, select **Add profile** and choose your configuration profile and target. + - To add an asset, select **Add asset** and choose your asset. -4. To edit the OS setting, first remove the old configuration profile and then add the new one. +Once the profile is saved, you can edit the profile's targets or replace the configuration file. Hover over the profile row and select the **pencil/edit button** to edit the following: + + - Targets (all hosts or custom). For custom targets, you can edit the labels (include and/or exclude). + - Configuration profile. In the edit modal, hover over the uploaded file and select the **pencil/edit button** to upload a replacement file. + > The replacement file must match the original: + > - **DDM profiles:** same declaration identifier and file name + > - **.mobileconfig profiles:** same `PayloadIdentifier` and `PayloadDisplayName` Fleet API: Use the [Create configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#create-configuration-profile) in the Fleet API. @@ -66,7 +110,7 @@ If two Windows profiles configure the same setting (LocURI) and one is removed, ### Device and user scope -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. +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. 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. @@ -75,6 +119,7 @@ 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: ``` @@ -90,9 +135,25 @@ How to deliver user-scoped configuration profiles: ``` +Here's an example DDM (`com.apple.configuration.*`) snippet: +```json +{ + "Type": "com.apple.configuration.passcode.settings", + "Identifier": "EB13EE2B-5D63-4EBA-810F-5B81D07F5017", + "ServerToken": "E180CA9A-F089-4FA3-BBDF-94CC159C4AE8", + "Payload": { + "RequirePasscode": true, + "RequireComplexPasscode": true, + "MinimumLength": 10, + "MaximumInactivityInMinutes": 1 + } +} +``` + #### 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. + 2. To make your Windows configuration profiles user scoped, replace `./Device` with `./User` in all `` elements. #### Upgrading from below 4.71.0 @@ -100,11 +161,13 @@ How to deliver user-scoped configuration profiles: 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: 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. 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. In versions older than 4.71.0, Fleet always delivered configuration profiles to the device scope (even when the profile's `PayloadScope` was set to `User`) @@ -117,7 +180,9 @@ In the Fleet UI, head to the **Controls > OS settings** tab. To see the status of a specific setting, hover over the setting's row in the **Configuration profiles** table and select the information (**i**) icon. -Currently, when editing a profile using Fleet's GitOps workflow, it can take 30 seconds for the profile's status to update to "Pending." +When editing a profile via Fleet's GitOps workflow, the profile's status will begin updating to "Pending" within 30 seconds. In larger installations, it may take a few minutes for the status to apply to all hosts. + +Editing a profile's labels sets the status to "Pending" for newly targeted hosts. ### Verified diff --git a/articles/deploy-software-packages.md b/articles/deploy-software-packages.md index 8c2e0837c5..5700c9b274 100644 --- a/articles/deploy-software-packages.md +++ b/articles/deploy-software-packages.md @@ -23,7 +23,7 @@ Learn more about automatically installing software [the Automatically install so > Software cannot be added to "All fleets" * Click the **Add software** button in the top right corner. * Select the **Custom package** tab. -* Choose a file to upload. `.pkg`, `.msi`, `.exe`, `.rpm`, `.deb`, `.ipa`, `.tar.gz`, `.sh`, and `.ps1` files are supported. +* Choose a file to upload. `.pkg`, `.msi`, `.exe`, `.rpm`, `.deb`, `.ipa`, `.tar.gz`, `.sh`, `.py`, and `.ps1` files are supported. * To customize installer behavior, click on **Advanced options**. > After the initial package upload, all options can be modified by editing the software. This includes self-service, targets, advanced options (pre-install query, scripts), and the software package file. However, if the installer package needs to be replaced, the new package must be of the same file type (such as .pkg, .msi, .exe, .deb, .rpm, or .ipa) and for the same software as the original. Files in .dmg or .zip formats cannot be edited or uploaded for replacement. To enable automatic installs, follow the steps in our [automatic software install guide](https://fleetdm.com/guides/automatic-software-install-in-fleet). @@ -49,7 +49,7 @@ Software installer uploads will fail if Fleet can't extract this metadata and ve ### Script-only packages -Script-only packages (`.sh` and `.ps1` files) are packages that only contain a script that runs directly on hosts without installing traditional software. The script file's contents become the install script. The `.sh` files are supported for Linux hosts, and`.ps1` files for Windows hosts. +Script-only packages (`.sh`, `.py`, and `.ps1` files) are packages that only contain a script that runs directly on hosts without installing traditional software. The script file's contents become the install script. The `.sh` and `.py` files are supported for macOS and Linux hosts, and `.ps1` files for Windows hosts. Script-only packages are useful for: - Self-service scripts (e.g., connecting to a VPN, configuring printers) @@ -88,6 +88,28 @@ Fleet also provides an `$UPGRADE_CODE` placeholder for MSIs. This placeholder is > Uninstall scripts do _not_ download the installer package to a host before running; if a .tar.gz archive includes an uninstall script, the contents of that script and any dependencies should be copied into the uninstall script text field rather than referred to by filename. +## Add multiple packages to the same fleet + +You can add up to 10 custom packages of the same software to a fleet. This lets you support multiple architectures (for example, Arm and Intel builds) or run a staged rollout (a stable build for all hosts plus a newer build scoped to a test group) without creating separate fleets. + +To add another package to a software: + +* Navigate to the **Software** page, select a fleet, and select the **Library** tab. +* Select the software. +* In the **Library** section of the **Software details** page, select **Add package**. +* Choose a file to upload, set the **Target**, and configure any advanced options. + +Each package has its own [target labels](https://fleetdm.com/guides/managing-labels-in-fleet), [self-service](https://fleetdm.com/guides/software-self-service) availability, categories, and advanced options. Scope each package to a distinct set of labels so that each host matches only one package. + +> If multiple packages target the same host, Fleet installs the one that was added first. + +During [setup experience](https://fleetdm.com/guides/setup-experience), Fleet installs the package that was added first. Labels don't apply during setup experience. + +Fleet identifies packages by their contents, so you can add different builds of the same version. Uploading the exact same file again is rejected. + + +Script-only packages (`.sh` and `.ps1`) can also be added multiple times to the same software item. Fleet uses the filename as a unique identifier to group multiple script-only packages into the same software. + ## Install the package After a software package is added to a fleet, it can be installed on hosts via the UI. @@ -109,7 +131,7 @@ Once the package is installed, Fleet will automatically refetch the host's vital * Navigate to the **Software** page, choose a fleet, and select the **Library** tab. * Select the software you want to edit. -* On the **Software details** page select **Actions > Edit software** to edit the software's [self-service](https://fleetdm.com/guides/software-self-service) status, change its target to different sets of hosts, or edit advanced options like pre-install query, install script, post-install script, and uninstall script. +* On the **Software details** page, select **Edit** next to a package in the **Library** section to edit that package's [self-service](https://fleetdm.com/guides/software-self-service) status, change its target to different sets of hosts, or edit advanced options like pre-install query, install script, post-install script, and uninstall script. Each package is edited separately. * Select **Actions > Edit appearance** to edit the software's icon and display name. The icon and display name can be edited for software that is available for install. The new icon and display name will appear on the software list and details pages for the fleet where the package is uploaded, as well as on **My device > Self-service**. If the display name is not set, then the default name (ingested by osquery) will be used. > Editing the advanced options cancels all pending installations and uninstallations for that package. Installs and uninstalls currently running on a host will complete, but results won't appear in Fleet. The software's host counts will be reset. @@ -129,7 +151,7 @@ After a software package is installed on a host, it can be uninstalled on the ho * Navigate to the **Software** page, choose a fleet, and select the **Library** tab. * Select the software you want to delete. -* On the **Software details** page, select the **Delete** icon next to the uploaded package file. +* On the **Software details** page, select the **Delete** icon next to a package in the **Library** section to delete that package. If a title has more than one package, the remaining packages stay intact. > Deleting a software package from a fleet will cancel pending installs for hosts that are not in the middle of installing the software, but will not uninstall the software from hosts where it is already installed. diff --git a/articles/deploying-apple-account-provisioning-with-fleet.md b/articles/deploying-apple-account-provisioning-with-fleet.md new file mode 100644 index 0000000000..faf481e527 --- /dev/null +++ b/articles/deploying-apple-account-provisioning-with-fleet.md @@ -0,0 +1,195 @@ +# Deploying Apple account provisioning with Fleet + +Fleet's Apple account provisioning creates your end users' macOS local accounts during automatic enrollment (ADE) using their identity provider (IdP) credentials, and keeps the local account password in sync with the IdP afterwards. It uses Fleet's own Platform SSO extension, built into the Fleet Desktop app, which proxies authentication through your Fleet server to any IdP that supports OAuth Resource Owner Password Grant (ROPG). This guide covers setup with Okta, but any OAuth ROPG-compatible IdP works. + +> This feature requires Fleet Premium. + +If your IdP offers its own native Platform SSO integration, such as [Okta Device Access](https://fleetdm.com/guides/deploying-okta-platform-sso-with-fleet) or [Microsoft Entra](https://fleetdm.com/guides/deploying-entra-platform-sso-with-fleet), consider using that instead. Fleet's account provisioning is designed for cases where a native integration is unavailable or not licensed for your organization. + +## What you get (and what you don't) + +With Apple account provisioning enabled: + +- End users authenticate with their IdP username and password during Setup Assistant, and macOS creates their local account with that password. +- The local account password stays in sync with the IdP. After a password change in the IdP, signing in with the new password at the login window, lock screen, or FileVault unlock updates the local password and keeps the keychain intact. +- The local account's short name and full name can be mapped from IdP attributes using `TokenToUserMapping`. + +What you don't get (yet): + +- Single sign-on to SaaS apps and websites. Fleet's extension currently handles account creation and password sync only. + +> OAuth ROPG is required because password sync needs the IdP to verify the user's actual password. Other desktop password sync products use the same class of flow for provisioning and syncing. Because ROPG sends the username and password directly to the token endpoint, it bypasses MFA, and some organizations' security policies may not allow it. + +## Prerequisites + +- Fleet Premium +- macOS hosts running macOS 26 or later, enrolling via ADE through Apple Business +- An IdP that supports OAuth ROPG (this guide uses Okta) +- Fleet's [setup experience](https://fleetdm.com/guides/setup-experience) configured for the target fleet +- The Fleet Desktop app, which contains Fleet's Platform SSO extension, available as a [Fleet-maintained app](https://fleetdm.com/guides/fleet-maintained-apps) + +> Account provisioning can currently only be configured for "All fleets" and only supports single-user macOS hosts. + +## Step 1: Create an OAuth ROPG app in Okta + +Okta only supports the Resource Owner Password grant on Native app integrations. + +1. Sign in to the Okta Admin Console and go to **Applications > Applications > Create App Integration**. + +2. Select **OIDC - OpenID Connect** as the sign-in method and **Native Application** as the application type, then click **Next**. + +3. Give the app a name, like "Fleet account provisioning." + +4. Under **Grant type**, check **Resource Owner Password**. + +5. Under **Assignments**, assign the app to the users or groups who will enroll Macs, then click **Save**. + +6. On the app's **General** tab, click **Edit** in the **Client Credentials** section, set **Client authentication** to **Client secret**, and click **Save**. + +7. Copy the **Client ID** and **Client secret**. You'll add these to Fleet in step 3. + +Next, confirm the app can complete a password-only sign-in: + +1. Go to **Applications > Applications**, open your app, and select the **Sign On** tab. + +2. Make sure the authentication policy assigned to the app allows sign-in with **Password** as a single factor. If the policy requires MFA, ROPG requests will fail. + +Finally, find your token URL. Fleet recommends the `default` authorization server because it supports the custom claims used for name mapping in step 2: + +1. Go to **Security > API > Authorization Servers** and open **default**. + +2. Your token URL is the **Issuer** URI plus `/v1/token`, for example `https://example.okta.com/oauth2/default/v1/token`. + +3. On the **Access Policies** tab, make sure a policy rule assigned to your app allows the **Resource Owner Password** grant type. + +> You can also use Okta's org authorization server (`https://example.okta.com/oauth2/v1/token`), but it doesn't support custom claims, so short name mapping with `TokenToUserMapping` won't be available. + +## Step 2: Map short name and full name (optional) + +Without any mapping, macOS uses the end user's IdP username as the local account's account name (short name), so a user signing in as `fleetie@example.com` gets `fleetie@example.com` as their account name. To get a friendlier account name like `fleetie`, add a custom claim in Okta and map it in your configuration profile with `TokenToUserMapping`. + +Fleet forwards the standard `email`, `name`, and `preferred_username` claims from your IdP's ID token to the Mac, plus any custom claim whose name starts with `account`. Name your custom claims accordingly, for example `accountName` or `accountFullName`. + +To add the short name claim in Okta: + +1. Go to **Security > API > Authorization Servers** and open **default**. + +2. On the **Claims** tab, click **Add Claim** and enter: + - **Name:** `accountName` + - **Include in token type:** ID Token, Always + - **Value type:** Expression + - **Value:** `String.substringBefore(user.login, "@")` + - **Include in:** Any scope + +3. Click **Create**. + +For the full name, the standard `name` claim works out of the box when the `profile` scope is granted (Fleet requests `openid profile email` by default). You can also add a custom `accountFullName` claim the same way if you want a different value. + +You'll reference these claim names in the configuration profile's `TokenToUserMapping` dictionary in step 5. + +## Step 3: Connect Fleet to your IdP + +1. In Fleet, go to **Settings > Integrations > Account provisioning**. + +2. Enter the **Token URL**, **Client ID**, and **Client secret** from step 1, then save. + +Alternatively, configure it with [GitOps](https://fleetdm.com/docs/configuration/yaml-files#apple-account-provisioning) in `default.yml`: + +```yaml +controls: + apple_account_provisioning: + oauth_idp_token_url: https://example.okta.com/oauth2/default/v1/token + oauth_idp_client_id: 0oa12345abcdeFGHI678 + oauth_idp_client_secret: # TODO: client secret (masked and non-exportable from the API) +``` + +## Step 4: Add Fleet's Platform SSO app to setup experience + +The Fleet Desktop app that contains the Platform SSO extension isn't installed by default. Add it as setup experience software so it's installed during Setup Assistant, before the user reaches the sign-in screen: + +1. In Fleet, head to the **Software** page for the target fleet, select **Add software**, open the **Fleet-maintained** tab, and add **Fleet Desktop**. + +2. Go to **Controls > Setup experience > Install software** and select the Fleet Desktop app so it installs during setup experience. + +## Step 5: Create and upload the configuration profile + +The extension is activated by a single configuration profile containing 2 payloads: an **Extensible Single Sign-On** payload and an **Associated Domains** payload. Start from the [example profile](https://github.com/fleetdm/fleet/blob/main/docs/solutions/macos/configuration-profiles/fleet-sso-extension-example.mobileconfig) and replace every occurrence of `fleet.example.com` with your Fleet server's domain. + +In the Extensible Single Sign-On payload: + +- **ExtensionIdentifier:** `com.fleetdm.fleet-desktop.pssoextension` and **TeamIdentifier:** `8VBZ3948LU`. Use these values exactly. +- **ExtensionData > BaseURL** and **URLs:** your Fleet server URL. +- **RegistrationToken:** `$FLEET_VAR_PSSO_DEVICE_REGISTRATION_TOKEN`. Fleet replaces this variable with a unique per-device registration token when the profile is delivered to each host. +- **EnableRegistrationDuringSetup** and **UseSharedDeviceKeys:** both `true`, so the user is registered during Setup Assistant. +- **TokenToUserMapping:** maps macOS account fields to claim names in the token the Mac receives. The example profile maps the short name to the `accountName` claim from step 2 and the full name to the standard `name` claim: + +```xml +TokenToUserMapping + + AccountName + accountName + FullName + name + +``` + +If you skipped step 2, remove the `AccountName` key (or the whole `TokenToUserMapping` dictionary) and macOS will use the IdP username as the account name. + +> `$FLEET_VAR_PSSO_DEVICE_REGISTRATION_TOKEN` is only allowed in the `RegistrationToken` key of a Fleet SSO extension payload. Fleet redacts the token when you view the delivered `InstallProfile` command, so it's never exposed in the UI or API. + +In the Associated Domains payload, both app identifiers (`8VBZ3948LU.com.fleetdm.fleet-desktop` and `8VBZ3948LU.com.fleetdm.fleet-desktop.pssoextension`) must list `authsrv:` plus your Fleet server's domain. + +Upload the profile to the target fleet under **Controls > OS settings > Custom settings**. + +> Don't scope this profile with labels. Labeled profiles may not be delivered in time for Setup Assistant, and if that happens the user won't be prompted to sign in. + +## End user experience + +1. The user powers on the Mac and it enrolls through automatic enrollment. End user authentication is optional; if it's enabled, the user signs in with their IdP first. + +2. Setup experience installs the Fleet Desktop app and delivers the configuration profile. + +3. During Setup Assistant, after Fleet's setup experience window closes, the user is prompted to sign in with their IdP username and password. + +4. macOS creates the local account. The password is the user's IdP password, and the account name and full name come from `TokenToUserMapping` if configured. The account creation screen will be shown, however the values are locked and the user cannot edit them at this point. + +After setup, password sync works like this: + +- When the user changes their password in the IdP and then signs in or unlocks with the new password, the local password syncs and a notification confirms it. The keychain stays intact. +- If the user keeps using the old password after a change, it continues to work until the Mac next checks in with the IdP, up to 4 hours later. After that, macOS prompts the user to sync at the next desktop login. +- FileVault unlock works with the synced password. +- If the Fleet server is unreachable, users are never locked out. The existing local password keeps working until connectivity returns. + +> Consider directing users to lock and then unlock their Mac using their new password after completing a password change via your IdP to immediately synchronize their Mac password, rather than relying on it happening later. + +## Troubleshoot + +**The user isn't prompted to sign in during Setup Assistant.** + +Confirm the Fleet Desktop app is set as setup experience software (step 4), the profile is uploaded to the same fleet without label scoping (step 5), and the host is running macOS 26 or later. + +**Sign-in fails with valid credentials.** + +Check the Okta app configuration (step 1). The **Resource Owner Password** grant must be enabled, client authentication must be set to **Client secret**, the user must be assigned to the app, and the app's authentication policy must allow password-only sign-in. Also confirm the token URL in Fleet points to the right authorization server and that its access policy allows the password grant. + +**The account name is the full email address.** + +The `accountName` claim isn't reaching the Mac. Confirm the custom claim exists on the same authorization server as your token URL (custom claims require a custom authorization server, not the org authorization server), that it's included in the ID token, and that its name starts with `account`. + +**The user is prompted for their previous password.** + +Occasionally when the user has logged out and logs back in, rather than locking and unlocking their Mac, the user will be prompted for their previous password at the desktop. This is expected and the user should enter their previous password to complete the process. If they cannot complete this process, the FileVault password may not sync with their new password. + +## Further reading + +- [Setup experience](https://fleetdm.com/guides/setup-experience) +- [Deploying Platform SSO with Okta Device Access](https://fleetdm.com/guides/deploying-okta-platform-sso-with-fleet) +- [Apple's Extensible Single Sign-On profile reference](https://developer.apple.com/documentation/devicemanagement/extensiblesinglesignon) +- [Okta's custom authorization server documentation](https://developer.okta.com/docs/concepts/auth-servers/) + + + + + + + diff --git a/articles/deploying-okta-platform-sso-with-fleet.md b/articles/deploying-okta-platform-sso-with-fleet.md index ad22d60aaa..227dad763e 100644 --- a/articles/deploying-okta-platform-sso-with-fleet.md +++ b/articles/deploying-okta-platform-sso-with-fleet.md @@ -62,7 +62,7 @@ The recommended approach is to use Fleet as a SCEP proxy with Okta's dynamic cha #### Step 2: Add Okta as a CA in Fleet -In Fleet, go to **Settings** → **Integrations** → **Certificate authorities** and click **Add CA**. Select **Okta CA or Microsoft Device Enrollment service (NDES)** and enter the values from step 7: +In Fleet, go to **Settings** → **Integrations** → **Certificate enrollment** and click **Add CA**. Select **Okta CA or Microsoft Device Enrollment service (NDES)** and enter the values from step 7: - **SCEP URL:** The SCEP URL from Okta - **Admin URL:** The Challenge URL from Okta diff --git a/articles/fleet-usage-statistics.md b/articles/fleet-usage-statistics.md index 7af6fe3523..64ec90d32d 100644 --- a/articles/fleet-usage-statistics.md +++ b/articles/fleet-usage-statistics.md @@ -27,6 +27,8 @@ Below is the JSON payload that is sent to Fleet Device Management Inc: "mdmMacOsEnabled": true, "hostExpiryEnabled": true, "mdmWindowsEnabled": false, + "numHostsFleetMDMEnrolledMacOS": 999, + "numHostsFleetMDMEnrolledWindows": 999, "liveQueryDisabled": false, "numWeeklyActiveUsers": 999, "numWeeklyPolicyViolationDaysActual": 999, diff --git a/articles/fleet-variables.md b/articles/fleet-variables.md index 2a50f46530..42ba00e95b 100644 --- a/articles/fleet-variables.md +++ b/articles/fleet-variables.md @@ -2,7 +2,7 @@ _Available in Fleet Premium_ -Fleet supports built-in variables (prefixed with `$FLEET_VAR_`) to inject host vitals into [configuration profiles](https://fleetdm.com/guides/custom-os-settings) or [iOS/iPadOS managed app configurations](https://fleetdm.com/guides/install-app-store-apps#ios-and-ipados-managed-configuration). +Fleet supports built-in variables (prefixed with `$FLEET_VAR_`) to inject host vitals into [configuration profiles](https://fleetdm.com/guides/custom-os-settings) or managed app configurations ([iOS/iPadOS](https://fleetdm.com/guides/install-app-store-apps#ios-and-ipados-managed-configuration), [Android](https://fleetdm.com/guides/install-app-store-apps#android-managed-configuration)). You can also create [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles) (prefixed with `$FLEET_SECRET_`) to define your own key-value pairs. @@ -16,23 +16,23 @@ Built-in variables: | Name | Configuration profiles | Managed app configuration | Description | |---|---|---|---| -| `$FLEET_VAR_NDES_SCEP_CHALLENGE` | macOS, iOS, iPadOS | None | Fleet-managed one-time NDES challenge password used during SCEP certificate configuration profile deployment. | -| `$FLEET_VAR_NDES_SCEP_PROXY_URL` | macOS, iOS, iPadOS | None | Fleet-managed NDES SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | -| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's IdP username (e.g. "user@example.com"). When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's IdP full name. When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Local part of the email (e.g. john from john@example.com). When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_GROUPS` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Comma separated IdP groups that host belongs to. When these change, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's IdP department. When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_HARDWARE_SERIAL` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's hardware serial number. Not available for user enrolled iOS and iPadOS hosts with Managed Apple Account. | -| `$FLEET_VAR_HOST_UUID` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's hardware UUID, or Enrollment ID for user enrolled iOS and iPadOS hosts. | -| `$FLEET_VAR_HOST_PLATFORM` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's platform. Values are `"macos"`, `"ios"`, `"ipados"`, and `"windows"`. | -| `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_` | macOS, iOS, iPadOS, Windows | None | Fleet-managed one-time challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the custom SCEP certificate authority configured in **Settings > Integrations > Certificate authorities**. | +| `$FLEET_VAR_NDES_SCEP_CHALLENGE` | macOS, iOS, iPadOS, Windows | None | Fleet-managed one-time NDES challenge password used during SCEP certificate configuration profile deployment. | +| `$FLEET_VAR_NDES_SCEP_PROXY_URL` | macOS, iOS, iPadOS, Windows | None | Fleet-managed NDES SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | +| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Host's IdP username (e.g. "user@example.com"). When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Host's IdP full name. When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Local part of the email (e.g. john from john@example.com). When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_GROUPS` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Comma separated IdP groups that host belongs to. When these change, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Host's IdP department. When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_HARDWARE_SERIAL` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Host's hardware serial number. Not available for user-enrolled iOS and iPadOS hosts with Managed Apple Account. | +| `$FLEET_VAR_HOST_UUID` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Host's hardware UUID, or Enrollment ID for user-enrolled iOS and iPadOS hosts. | +| `$FLEET_VAR_HOST_PLATFORM` | macOS, iOS, iPadOS, Windows, Android | iOS, iPadOS, and Android | Host's platform. Values are `"macos"`, `"ios"`, `"ipados"`, `"windows"`, and `"android"`. | +| `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_` | macOS, iOS, iPadOS, Windows | None | Fleet-managed one-time challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the custom SCEP certificate authority configured in **Settings > Integrations > Certificate enrollment**. | | `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_` | macOS, iOS, iPadOS, Windows | None | Fleet-managed SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | | `$FLEET_VAR_CERTIFICATE_RENEWAL_ID` | macOS, iOS, iPadOS, Windows | Fleet-managed ID that's required to automatically renew certificates. The ID must be specified in the Organizational Unit (OU) field in the configuration profile. | -| `$FLEET_VAR_DIGICERT_PASSWORD_` | macOS, iOS, iPadOS | None | Fleet-managed password required to decode the base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the DigiCert certificate authority configured in **Settings > Integrations > Certificate authorities**. | -| `$FLEET_VAR_DIGICERT_DATA_` | macOS, iOS, iPadOS | None | Fleet-managed base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the DigiCert certificate authority configured in **Settings > Integrations > Certificate authorities**. | +| `$FLEET_VAR_DIGICERT_PASSWORD_` | macOS, iOS, iPadOS | None | Fleet-managed password required to decode the base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the DigiCert certificate authority configured in **Settings > Integrations > Certificate enrollment**. | +| `$FLEET_VAR_DIGICERT_DATA_` | macOS, iOS, iPadOS | None | Fleet-managed base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the DigiCert certificate authority configured in **Settings > Integrations > Certificate enrollment**. | | `$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID` | Windows | None | ID used for SCEP configuration profile on Windows. It must be included in the `` field. | -| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_` | macOS, iOS, iPadOS | None | Fleet-managed one-time Smallstep challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the Smallstep certificate authority configured in **Settings > Integrations > Certificate authorities**. | +| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_` | macOS, iOS, iPadOS | None | Fleet-managed one-time Smallstep challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the Smallstep certificate authority configured in **Settings > Integrations > Certificate enrollment**. | | `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_` | macOS, iOS, iPadOS | None | Fleet-managed Smallstep SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | diff --git a/articles/foreign-vitals-map-idp-users-to-hosts.md b/articles/foreign-vitals-map-idp-users-to-hosts.md index 87e73a5663..7b33e233e8 100644 --- a/articles/foreign-vitals-map-idp-users-to-hosts.md +++ b/articles/foreign-vitals-map-idp-users-to-hosts.md @@ -43,13 +43,12 @@ To map users from Okta to hosts in Fleet, we'll do the following steps: 5. For the **Authentication Mode**, select **HTTP Header**. 6. [Create a Fleet API-only user](https://fleetdm.com/guides/fleetctl#create-api-only-user) with admin permissions and access to all [`/scim/*` API endpoints](https://fleetdm.com/docs/rest-api/rest-api#scim). 7. Copy the API token for that user and paste it in Okta's **Authorization** field. +8. Select the **Test Connector Configuration** button. You should see a success message pop up in Okta. You can close this message. +9. In Fleet, head to **Settings > Integrations > User mapping** and verify that Fleet successfully received the request from Okta. +10. Back in Okta, select **Save**. +11. Under the **Provisioning** tab, select **To App** and then select **Edit** in the **Provisioning to App** section. Enable **Create Users**, **Update User Attributes**, **Deactivate Users**, and then select **Save**. +12. On the same page, make sure that `givenName` and `familyName` attributes have Okta values assigned to them. Currently, Fleet requires the `userName`, `givenName`, and `familyName` SCIM attributes. Fleet also supports the `department` attribute, but does not require it. Remove the mapping for the rest of the attributes. - -9. Select the **Test Connector Configuration** button. You should see a success message pop up in Okta. You can close this message. -10. In Fleet, head to **Settings > Integrations > Identity provider (IdP)** and verify that Fleet successfully received the request from Okta. -11. Back in Okta, select **Save**. -12. Under the **Provisioning** tab, select **To App** and then select **Edit** in the **Provisioning to App** section. Enable **Create Users**, **Update User Attributes**, **Deactivate Users**, and then select **Save**. -13. On the same page, make sure that `givenName` and `familyName` attributes have Okta values assigned to them. Currently, Fleet requires the `userName`, `givenName`, and `familyName` SCIM attributes. Fleet also supports the `department` attribute, but does not require it. Remove the mapping for the rest of the attributes. ![Okta SCIM attributes mapping](../website/assets/images/articles/okta-scim-attributes-mapping-402x181@2x.png) > If you use attributes other than the supported attributes above, the payload will be rejected by Fleet. diff --git a/articles/rename-hosts-with-a-naming-template.md b/articles/rename-hosts-with-a-naming-template.md new file mode 100644 index 0000000000..c45326a39a --- /dev/null +++ b/articles/rename-hosts-with-a-naming-template.md @@ -0,0 +1,114 @@ +# Rename hosts with a naming template + +_Available in Fleet Premium_ + +Set a naming convention once and Fleet renames every macOS, iOS, and iPadOS host in a fleet to match, both on the device and in Fleet. Instead of building an automation to send a custom MDM command to each host, you save a name template like `iPad $FLEET_VAR_HOST_HARDWARE_SERIAL` and Fleet resolves it per host, renames the device over MDM, and keeps its own record in sync. + +This applies to Apple hosts (macOS, iOS, iPadOS) only. Windows and Android hosts are unaffected. + +## Prerequisites + +- Fleet Premium. +- Fleet's MDM [turned on](https://fleetdm.com/guides/macos-mdm-setup). +- Hosts enrolled in Fleet's MDM. Personally enrolled (BYOD) hosts are skipped and never renamed. +- iOS and iPadOS hosts must be supervised. Apple only applies a name change to supervised iPhones and iPads; unsupervised hosts receive the command once and land on **Failed**. + +## Set a name template + +1. In the top navigation, select **Controls**, then select a fleet (or **Unassigned** for hosts that aren't in a fleet). +2. Select **OS settings**, then **Host names**. +3. In **Name template**, enter your naming convention. Use plain text, built-in variables, custom variables, or a combination. For example: `Conference Room iPad $FLEET_VAR_HOST_HARDWARE_SERIAL`. +4. Select **Save**. + +Fleet queues a rename for every eligible host in the fleet. The name you set becomes the host's name in Fleet and on the device itself. + +> **Note:** Clearing the **Name template** field and saving stops enforcement but doesn't rename any host. Hosts keep their current name. + +### Built-in variables + +Use these variables in a template to give each host a unique name: + +| Variable | Resolves to | +|---|---| +| `$FLEET_VAR_HOST_HARDWARE_SERIAL` | The host's hardware serial number. | +| `$FLEET_VAR_HOST_UUID` | The host's UUID. | +| `$FLEET_VAR_HOST_PLATFORM` | The host's platform: `macOS`, `iOS`, or `iPadOS`. | +| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` | The host end user's identity provider (IdP) username. | +| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART` | The local part of the IdP username (before `@`). | +| `$FLEET_VAR_HOST_END_USER_IDP_GROUPS` | The end user's IdP groups, comma-separated. | +| `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT` | The end user's IdP department. | +| `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME` | The end user's IdP full name. | + +Each variable also works in its `${FLEET_VAR_...}` form. For more on built-in variables, see [Built-in variables](https://fleetdm.com/guides/fleet-variables). + +> **Note:** The IdP variables need the host to have end-user IdP data. If a host has no IdP user, or the field the template references is empty (for example, no department), that host lands on **Failed** — the same behavior as configuration profiles that use these variables. The identity variables (serial, UUID, platform) are always available. + +> **Note:** A resolved host name can't be longer than 63 bytes (Apple's device name limit). Hosts whose resolved name exceeds this land on **Failed**. + +### Custom variables + +You can also use custom (`$FLEET_SECRET_*`) variables in a template, for example `$FLEET_SECRET_SITE-$FLEET_VAR_HOST_HARDWARE_SERIAL`. Custom variables are global, so a variable resolves to the same value for every fleet and host. See [Custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles). + +The custom variable must already exist when you save the template, or the save fails. A custom variable used in a name template can't be deleted until you remove it from the template. + +> **Important:** Unlike in scripts and configuration profiles, a custom variable used in a name template isn't kept hidden. Its value becomes the host's name in Fleet and on the device, so only use custom variables for values that are safe to display (for example, a site or location code), not for secrets. + +### Variables that aren't supported + +Certificate authority variables — for example `$FLEET_VAR_NDES_SCEP_CHALLENGE`, `$FLEET_VAR_DIGICERT_DATA_`, `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_`, `$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID`, and `$FLEET_VAR_CERTIFICATE_RENEWAL_ID` — and the Platform SSO device registration token can't be used in a name template. They resolve to one-time challenges, proxy URLs, or certificate data: values that are meaningless as a device name and would expose secrets in a name that's visible on the device, in reports, and in the Fleet UI. Fleet rejects a template that references them. + +The deprecated `$FLEET_VAR_HOST_END_USER_EMAIL_IDP` variable also isn't supported; use the `HOST_END_USER_IDP_*` variables above instead. + +### Renaming when a variable's value changes + +Fleet keeps host names in sync with their variables. When a host's IdP data changes (for example, the end user's department is updated) or a custom variable's value changes, Fleet resolves the template again and renames the hosts that use that variable. + +## Set a name template with GitOps + +Add `name_template` under `controls` in a fleet's YAML, or in `no_team.yml` or `default.yml` controls to apply it to "Unassigned" hosts: + +```yaml +controls: + name_template: "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL" # Available in Fleet Premium +``` + +You can reference a custom (`$FLEET_SECRET_*`) variable in the template too: + +```yaml +controls: + name_template: "iPad $FLEET_SECRET_SITE" # Available in Fleet Premium +``` + +Removing the key clears the template. For all controls options, see the [YAML files reference](https://fleetdm.com/docs/configuration/yaml-files#controls). + +## Verify + +Open a host's **OS settings** to see its host name status: + +1. Select **Hosts**, then select a host. +2. Select **Actions > Show details**, then open the **OS settings** modal. +3. Find the **Host name** row. Its status moves from **Enforcing** to **Verifying** (the device applied the name) to **Verified** (Fleet confirmed the name from the device). + +Controls > OS settings also rolls host name statuses into the **Verified**, **Verifying**, **Pending**, and **Failed** aggregate cards. + +## Troubleshoot + +**A host's Host name row shows Failed.** The status is Failed when the device rejected the command, the resolved name was too long, the host is missing IdP data a variable in the template needs, a custom variable in the template is no longer defined, or an end user renamed the device off-template. The row's tooltip shows the error. Select **Resend** on the row to try again. + +**An iPhone or iPad shows Failed with a supervision error.** Apple only applies MDM name changes to supervised iOS and iPadOS hosts. Supervise the host (for example, by enrolling it through Apple Business Manager), then select **Resend**. + +**A host has no Host name row.** Fleet omits the row for hosts it doesn't enforce: hosts whose fleet (or "Unassigned") has no template, non-MDM hosts, and personally enrolled (BYOD) hosts. + +## Further reading + +- [Built-in variables](https://fleetdm.com/guides/fleet-variables) +- [Custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles) +- [YAML files reference](https://fleetdm.com/docs/configuration/yaml-files#controls) +- [Update host name template API](https://fleetdm.com/docs/rest-api/rest-api#update-host-name-template) + + + + + + + diff --git a/articles/role-based-access.md b/articles/role-based-access.md index e8dcd5af53..e58499b4a4 100644 --- a/articles/role-based-access.md +++ b/articles/role-based-access.md @@ -124,6 +124,9 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines. | Add Microsoft Entra tenant | | | | | ✅ | | | View [custom variables](https://fleetdm.com/docs/rest-api/rest-api#list-custom-variables) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Create, edit, and delete custom variables | | | | ✅ | ✅ | ✅ | +| View custom host vitals | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Create, edit, and delete custom host vitals | | | | ✅ | ✅ | ✅ | +| Set custom host vital values on hosts | | | | ✅ | ✅ | | \* Applies only to Fleet Premium @@ -201,6 +204,8 @@ Users can be assigned to multiple fleets, and can have different roles for each | Turn off MDM for specific hosts | | | | ✅ | ✅ | | | View certificate authorities (CA) | | | | ✅ | ✅ | ✅ | | View [custom variables](https://fleetdm.com/docs/rest-api/rest-api#list-custom-variables) | ✅ | ✅ | ✅ | ✅ | ✅ | | +| View custom host vitals | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Set custom host vital values on hosts | | | | ✅ | ✅ | | \* Applies only to [Fleet REST API](https://fleetdm.com/docs/using-fleet/rest-api) diff --git a/articles/scripts.md b/articles/scripts.md index 53cb3eaacf..8a7e8cacf5 100644 --- a/articles/scripts.md +++ b/articles/scripts.md @@ -7,6 +7,7 @@ Shell (`.sh`) and Python (`.py`) scripts are supported on macOS and Linux. By default, shell scripts will run in the host's (root) shell (`/bin/sh`). To run a shell script in `/bin/zsh` or `/bin/bash`, add a shebang as the first line (for example, `#!/bin/zsh` or `#!/bin/bash`). Python scripts must start with a Python shebang as the first line (for example, `#!/usr/bin/env python3` or `#!/usr/bin/python3`). +> Python must be installed on the target host before running `.py` scripts. If you're deploying a script-only package that uses Python, ensure Python is present (e.g., via a prerequisite software package or a shell script that installs it first). PowerShell scripts are supported on Windows. Other types of scripts are not supported yet. diff --git a/articles/secrets-in-scripts-and-configuration-profiles.md b/articles/secrets-in-scripts-and-configuration-profiles.md index c74b7a6755..76a8a42d98 100644 --- a/articles/secrets-in-scripts-and-configuration-profiles.md +++ b/articles/secrets-in-scripts-and-configuration-profiles.md @@ -4,11 +4,13 @@ -In Fleet you can add variables, in [scripts](https://fleetdm.com/guides/scripts) and [configuration profiles](https://fleetdm.com/guides/custom-os-settings). Variables are hidden when the script or configuration profile is viewed in the Fleet UI or API. +In Fleet you can add variables in [scripts](https://fleetdm.com/guides/scripts), [configuration profiles](https://fleetdm.com/guides/custom-os-settings), and [host name templates](https://fleetdm.com/guides/rename-hosts-with-a-naming-template). In scripts and configuration profiles, variables are hidden when viewed in the Fleet UI or API. In a host name template, a variable's value becomes the host's name in Fleet and on the device, so it isn't hidden. Configuration profiles can also use any of Fleet's [built-in variables](https://fleetdm.com/guides/fleet-variables). -Custom variables (`$FLEET_SECRET_*`) hold a single value shared across all hosts. To store a different value per host, use [custom host vitals](https://fleetdm.com/guides/custom-host-vitals) (`$FLEET_HOST_VITAL_*`) instead. +Script-only packages (.sh, .ps1, .py) also support custom variables (`$FLEET_SECRET_*`). Fleet replaces them with their values when the install script is sent to the host. + +Custom variables hold a single value shared across all hosts. To store a different value per host, use [custom host vitals](https://fleetdm.com/guides/custom-host-vitals) (`$FLEET_HOST_VITAL_*`) instead. ## Add variables @@ -22,7 +24,7 @@ To add or delete a variable in the UI, go to `Controls` > `Variables` and click ![Add variable](../website/assets/images/articles/controls-add-variable-337x209@2x.png) -Variables are global, meaning they can be used in scripts and profiles across all fleets. +Variables are global, meaning they can be used in scripts, configuration profiles, and host name templates across all fleets. ### GitOps @@ -101,6 +103,7 @@ Here's an example profile with `$FLEET_SECRET_CERT_PASSWORD` and `$FLEET_SECRET_ ## Known limitations and issues - **Apple MDM profiles**: Fleet secret variables (`$FLEET_SECRET_*`) cannot be used in the `PayloadDisplayName` field of Apple configuration profiles. This field becomes the visible name of the profile and using secrets here could expose sensitive information. Place secrets in other fields like `PayloadDescription`, `Password`, or `PayloadContent` instead. +- **Host name templates**: A custom variable used in a [host name template](https://fleetdm.com/guides/rename-hosts-with-a-naming-template) isn't hidden — its value becomes the host's name in Fleet and on the device. Only use custom variables for values that are safe to display (for example, a site or location code). - After changing a variable used by a Windows profile, that profile is currently not re-sent to the device when the GitHub action (or GitLab pipeline) runs: [story #27351](https://github.com/fleetdm/fleet/issues/27351) - Fleet does not hide the secret in script results. Don't print/echo your secrets to the console output. - There is no way to explicitly delete a secret variable. Instead, you can overwrite it with any value. diff --git a/articles/securing-externally-hosted-ddm-assets.md b/articles/securing-externally-hosted-ddm-assets.md new file mode 100644 index 0000000000..b341359cb6 --- /dev/null +++ b/articles/securing-externally-hosted-ddm-assets.md @@ -0,0 +1,232 @@ +# How to secure externally hosted DDM assets + +Declarative device management (DDM) lets you define an asset once and reference it from many configurations. One such asset type is `com.apple.asset.data`. + +```json +{ + "Type": "com.apple.asset.data", + "Identifier": "com.fleet.asset.wifi-cert", + "Payload": { + "Reference": { + "ContentType": "application/x-pkcs12", + "DataURL": "https://assets.example.com/wifi-cert" + } + } +} +``` + +When a device processes this asset, it downloads the data from `DataURL` itself. That URL can live anywhere: a CDN, an S3 bucket behind a small service, or your own host. This is what "externally hosted assets" means. The data never passes through Fleet. + +That raises a problem. If the asset holds something sensitive, like a certificate or a credential, an open URL is a liability. Anyone who learns the URL could fetch the file. Even worse, a device enrolled in a different organization's Fleet server should not be able to read your assets. + +Apple solves this with the same mechanism it uses for the MDM protocol itself: the `Mdm-Signature` header. This guide explains how that header works and how your asset host can verify it, so only enrolled devices can download the data. It also covers mutual TLS (mTLS), an alternative that verifies the same identity certificate during the TLS handshake. + +## How the device signs its request + +Fleet's enrollment profile sets `SignMessage` to `true`. From then on, the device signs its requests with the identity certificate it received during enrollment. That certificate was issued by Fleet's built-in certificate authority (CA). + +When the device requests an externally hosted asset, it attaches an `Mdm-Signature` header. The header is a base64-encoded [CMS](https://datatracker.ietf.org/doc/html/rfc5652) (PKCS #7) detached signature over the request body. The device's signing certificate is embedded in the signature. Because an asset download is a `GET`, the body is empty, so the signature covers empty content. The proof of identity comes from the certificate and the private key, not from the payload. + +Apple documents this in ["Pass an identity certificate through a proxy."](https://developer.apple.com/documentation/devicemanagement/managing-certificates-for-device-management-services-and-devices#Pass-a-device-identity-certificate-through-a-proxy) Fleet uses the exact same header to authenticate every MDM check-in, so your asset host can reuse the same verification steps. + +## What verification proves + +Two checks confirm a request came from a device enrolled in your Fleet server, and both are stateless. Anyone with Fleet's CA certificate can run them: + +1. **Did the holder of this certificate sign this request?** Verify the CMS signature. +2. **Did Fleet's CA issue this certificate?** Verify the certificate chains to Fleet's CA. + +> The following code snippets are written in Go. + +## Step 1: Verify the signature + +Decode the header, attach the request body as the detached content, and verify. This example uses [`go.mozilla.org/pkcs7`](https://pkg.go.dev/go.mozilla.org/pkcs7), the same style of library Fleet uses internally. + +```go +import ( + "crypto/x509" + "encoding/base64" + "errors" + + "go.mozilla.org/pkcs7" +) + +// verifySignature checks the Mdm-Signature header against the request body and +// returns the certificate that signed it. +func verifySignature(header string, body []byte) (*x509.Certificate, error) { + sig, err := base64.StdEncoding.DecodeString(header) + if err != nil { + return nil, err + } + + // Reject oversized headers before parsing to limit abuse. A real signature + // is a few kilobytes at most. + if len(sig) > 10*1024 { + return nil, errors.New("Mdm-Signature header too large") + } + + p7, err := pkcs7.Parse(sig) + if err != nil { + return nil, err + } + + // The signature is detached, so set the content to the request body. + p7.Content = body + if err := p7.Verify(); err != nil { + return nil, err + } + + cert := p7.GetOnlySigner() + if cert == nil { + return nil, errors.New("no signer certificate") + } + return cert, nil +} +``` + +At this point you know the request was signed by whoever holds the private key for `cert`. You do not yet know who that is. + +## Step 2: Verify the certificate chains to Fleet's CA + +A valid signature from an unknown certificate proves nothing. Anyone can generate a self-signed certificate and sign a request with it. The certificate has to trace back to your Fleet server's CA. + +```go +import ( + "crypto/x509" + "time" +) + +// verifyChain confirms the certificate was issued by Fleet's CA and is valid +// for client authentication. +func verifyChain(cert *x509.Certificate, fleetCA *x509.Certificate) error { + roots := x509.NewCertPool() + roots.AddCert(fleetCA) + + _, err := cert.Verify(x509.VerifyOptions{ + Roots: roots, + KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageClientAuth}, + CurrentTime: time.Now(), + }) + return err +} +``` + +`cert.Verify` also enforces the certificate's validity window, so an expired identity fails here. + +Each Fleet server generates its own CA when MDM is turned on. A certificate issued by a different Fleet server, or by any other CA, will not chain to yours. This is what keeps other organizations' devices out. + +## Getting Fleet's CA certificate + +Your asset host needs Fleet's CA certificate to run step 2, and to trust client certificates over mTLS. Fleet exposes it over the standard SCEP endpoint. Fetch it once and cache it: + +```go +import ( + "crypto/x509" + "io" + "net/http" +) + +// fetchFleetCA downloads Fleet's CA certificate from the SCEP endpoint. +func fetchFleetCA(fleetURL string) (*x509.Certificate, error) { + resp, err := http.Get(fleetURL + "/mdm/apple/scep?operation=GetCACert") + if err != nil { + return nil, err + } + defer resp.Body.Close() + + der, err := io.ReadAll(resp.Body) + if err != nil { + return nil, err + } + return x509.ParseCertificate(der) +} +``` + +You can inspect the same certificate from the command line, which is handy for debugging: + +```bash +curl 'https://fleet.example.com/mdm/apple/scep?operation=GetCACert' -o ca.der +openssl x509 -inform DER -in ca.der -noout -subject -issuer +``` + +## Putting it together + +Your asset handler runs the two checks in order and serves the file only when both pass: + +```go +func handleAssetDownload(w http.ResponseWriter, r *http.Request, fleetCA *x509.Certificate) { + body, _ := io.ReadAll(r.Body) + + cert, err := verifySignature(r.Header.Get("Mdm-Signature"), body) + if err != nil { + http.Error(w, "bad signature", http.StatusBadRequest) + return + } + if err := verifyChain(cert, fleetCA); err != nil { + http.Error(w, "untrusted certificate", http.StatusForbidden) + return + } + + // Both checks passed: the request came from a device enrolled in this Fleet. + serveAsset(w, r) +} +``` + +## What each check protects against + +- A request with no signature, or a forged one, fails step 1. +- A device whose certificate came from a different CA, including another Fleet server, fails step 2. + +## Alternative: verify with mutual TLS (mTLS) + +The device presents its Fleet identity certificate two ways on the same request. It signs the body for the `Mdm-Signature` header, and it also offers the certificate as a TLS client certificate during the handshake. If your asset host terminates TLS itself, you can verify that client certificate instead of reading the header, and let the TLS layer reject unauthorized clients before any request reaches your code. + +Point the server's client CA pool at Fleet's CA and require a verified client certificate: + +```go +import ( + "crypto/tls" + "crypto/x509" + "net/http" +) + +// newTLSServer completes the handshake only for clients that present a +// certificate chaining to Fleet's CA. +func newTLSServer(fleetCA *x509.Certificate) *http.Server { + pool := x509.NewCertPool() + pool.AddCert(fleetCA) + + handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + // The handshake already required a client certificate that chains to + // Fleet's CA, so any request that reaches here is from an enrolled + // device. The verified certificate is on r.TLS.PeerCertificates[0] if + // you want to log which device it was. + serveAsset(w, r) + }) + + return &http.Server{ + Addr: ":443", + Handler: handler, + TLSConfig: &tls.Config{ + ClientAuth: tls.RequireAndVerifyClientCert, + ClientCAs: pool, + MinVersion: tls.VersionTLS12, + }, + } +} +``` + +`RequireAndVerifyClientCert` with `ClientCAs` set to Fleet's CA is the same trust check as step 2, moved into the handshake. Go verifies the chain and the certificate's validity window before your handler runs, so a client with no certificate, or one from another CA, is turned away at the connection. + +mTLS has two advantages over the header. It rejects unauthorized clients at the handshake, before any HTTP is processed, and because each connection is a fresh handshake, a captured request cannot be replayed. The condition is that your server must terminate TLS. If a proxy or CDN terminates TLS in front of your host, the client certificate never reaches your code, and the `Mdm-Signature` header is the option that still works. Some proxies can forward the certificate in a header, but that depends on the proxy. + +## Conclusion + +Externally hosted assets let you serve DDM asset data from wherever suits your infrastructure without routing it through Fleet. The `Mdm-Signature` header keeps that data protected: verify the signature, then confirm the certificate chains to Fleet's CA. Those two checks prove a request came from one of your enrolled devices, so unauthorized requests and devices from other Fleet servers cannot reach what you host. When your host terminates TLS, mTLS verifies the same identity certificate at the handshake and gives you that protection one layer earlier. + + + + + + + \ No newline at end of file diff --git a/articles/setup-experience.md b/articles/setup-experience.md index 4b0b7be52e..51ccc899f0 100644 --- a/articles/setup-experience.md +++ b/articles/setup-experience.md @@ -16,7 +16,7 @@ Below is the end user experience for macOS. Check out the separate videos for [i -## Require IdP authentication +## End user authentication You can require IdP authentication during automatic enrollment (ADE) for Apple (macOS, iOS, iPadOS) hosts and manual enrollment for personal (BYOD) iOS, iPadOS, and Android hosts. IdP authentication is also supported on [Windows and Linux](https://fleetdm.com/guides/windows-linux-setup-experience). End users can use passkeys, such as YubiKeys, with macOS hosts during the authentication process. @@ -30,7 +30,7 @@ You can require IdP authentication during automatic enrollment (ADE) for Apple ( 3. Make sure your end users' full names are set to one of the following attributes (depends on IdP): `name`, `displayname`, `cn`, `urn:oid:2.5.4.3`, or `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`. Fleet will automatically populate the macOS local account **Full Name** with any of these. -4. In Fleet, configure your IdP by heading to **Settings > Integrations > Single sign-on (SSO) > End users**. Then, enable IdP authentication by heading to **Controls > Setup experience > Require IdP authentication**. Alternatively, you can use [Fleet's GitOps workflow](https://fleetdm.com/docs/configuration/yaml-files) to configure your IdP integration and enable IdP authentication. +4. In Fleet, configure your IdP by heading to **Settings > Integrations > Authentication (SSO) > End users**. Then, enable IdP authentication by heading to **Controls > Setup experience > Require IdP authentication**. Alternatively, you can use [Fleet's GitOps workflow](https://fleetdm.com/docs/configuration/yaml-files) to configure your IdP integration and enable IdP authentication. > If you've already configured [single sign-on > (SSO)](https://fleetdm.com/docs/deploy/single-sign-on-sso) in Fleet, you still want to create a @@ -91,28 +91,34 @@ Valid values are `"admin"`, `"standard"`, and `"none"`. When set to `"standard"` ## Managed local account -Fleet can create a hidden admin account (`_fleetadmin`) with a unique password on each macOS host during Setup Assistant. IT admins can use this account as a break-glass login for troubleshooting. +Fleet can create a hidden admin account (`_fleetadmin`) with a unique password on each eligible host during setup. IT admins can use this account as a break-glass login for troubleshooting. -This feature is available for macOS hosts that automatically enroll via Apple Business (AB). Manually enrolled hosts are not supported. +This feature is available for macOS hosts that automatically enroll via Apple Business (AB) and Windows hosts that automatically enroll via Azure AD. Manually enrolled hosts are not supported. To enable managed local accounts: -1. In Fleet, head to **Controls > Setup experience > Users** and check **Managed local account**. Alternatively, you can enable this using [Fleet's REST API](https://fleetdm.com/docs/rest-api/rest-api#update-setup-experience) or [GitOps workflow](https://fleetdm.com/docs/configuration/yaml-files). +1. In Fleet, head to **Controls > Setup experience > Users** and select the platform (macOS or Windows), then choose **Managed > Create hidden admin**. Alternatively, you can enable this using [Fleet's REST API](https://fleetdm.com/docs/rest-api/rest-api#update-setup-experience) or [GitOps workflow](https://fleetdm.com/docs/configuration/yaml-files). -2. Wipe and re-enroll any existing macOS hosts that should receive the account. Hosts enrolled before the feature is turned on won't receive a managed account until they go through Setup Assistant again. +2. Wipe and re-enroll any existing hosts that should receive the account. Hosts enrolled before the feature is turned on won't receive a managed account until they go through the setup experience again. To view the password for a host's managed account, head to **Host details > Actions > Show managed account**. The password is unique per host and stored securely in Fleet. -> The managed account is hidden from the macOS login window. Apple's MDM protocol only supports creating hidden accounts during Automated Device Enrollment (ADE), which is why this feature requires hosts to enroll via Apple Business and go through Setup Assistant. To log in as `_fleetadmin`, click **Other** on the login window (or press the username field) and type the username and password manually. +### macOS +> The managed account is hidden from the macOS login window. To log in as `_fleetadmin`, click **Other** on the login window (or press the username field) and type the username and password manually. > The managed account does not have a Secure Token. To access a FileVault-encrypted disk, first unlock it using the [escrowed recovery key](https://fleetdm.com/guides/macos-mdm-setup#disk-encryption), then log in as `_fleetadmin` at the login window. > On macOS 15.7, if the end user account type is set to **Standard** or **Skip (no account)**, FileVault cannot be enabled locally through System Settings by the managed local account. To encrypt the disk, [enforce disk encryption via Fleet](https://fleetdm.com/guides/enforce-disk-encryption) instead. This issue does not affect macOS 26. +### Windows +> The managed account is hidden from the Windows sign-in screen. To log in as _fleetadmin, select **Other user** on the sign-in screen and enter the username and password manually. + ## Platform SSO Fleet supports configuring Platform SSO (PSSO) for macOS hosts with the option to create a local user account during enrollment. If you use Okta, see [Deploying Okta Platform SSO with Fleet](https://fleetdm.com/guides/deploying-okta-platform-sso-with-fleet) for setup instructions. PSSO can be used with or without [end user authentication](#end-user-authentication) enabled. +Fleet also supports using the Fleet Desktop app's built-in PSSO extension to achieve initial account provisioning during setup and password sync with any OAuth ROPG IdP for use cases where a native IdP PSSO integration is unavailable or is not configured. See [Deploying Apple Account Provisioning with Fleet](https://fleetdm.com/guides/deploying-apple-account-provisioning-with-fleet). + ## End user license agreement (EULA) To require a EULA, in Fleet, head to **Settings > Integrations > MDM > End user license agreement (EULA)** or use the [Fleet API](https://fleetdm.com/docs/rest-api/rest-api#upload-an-eula-file). diff --git a/articles/software-self-service.md b/articles/software-self-service.md index a55cc45427..72ac5b34a5 100644 --- a/articles/software-self-service.md +++ b/articles/software-self-service.md @@ -30,6 +30,8 @@ You can also add the software and later make it available in self-service: If a software item isn't made available in self-service, end users will not see it in **Fleet Desktop > Self-service**. IT admins can still install, update, and uninstall the software from Fleet. +> For [custom packages](https://fleetdm.com/guides/deploy-software-packages#add-multiple-packages-to-a-software-title), self-service is set per package. When a title has more than one self-service package and a host matches more than one, Fleet installs the package that was added first. + ## Manage self-service categories _Available in Fleet Premium_ @@ -58,6 +60,8 @@ End users can install every app in a category in one click from the **My device 1. Select a category from the dropdown above the software table. 2. Select **Install all** to install every app in the category. The count in the button adjusts based on what's already installed on the device. +> **Install all** only appears when a specific category is selected. It's hidden on the unfiltered **All** view to prevent accidentally queuing installs for the entire software catalog. + Fleet queues each install as a separate operation. End users can monitor progress in the **Status** column. Software is installed in alphabetical order. ## Deploy self-service on iOS and iPadOS diff --git a/articles/using-maintenance-windows.md b/articles/using-maintenance-windows.md index e71c658548..2de2286188 100644 --- a/articles/using-maintenance-windows.md +++ b/articles/using-maintenance-windows.md @@ -14,7 +14,7 @@ You can customize these flows with a webhook (e.g. Tines) to run scripts, use th ### Setup -1. Connect a Google Workspace service account to Fleet under **Settings > Integrations > Calendars**. +1. Connect a Google Workspace service account to Fleet under **Settings > Integrations > Calendar events**. 2. Create a webhook to handle the remediation (see [Fleet + Tines guide](https://fleetdm.com/guides/building-webhook-flows-with-fleet-and-tines)). 3. In the **Policies** tab, click **Manage automations > Calendar events**, enable the feature, and paste your webhook URL. diff --git a/articles/view-certificates-in-host-vitals.md b/articles/view-certificates-in-host-vitals.md index 2ef251dd77..a98c41c6de 100644 --- a/articles/view-certificates-in-host-vitals.md +++ b/articles/view-certificates-in-host-vitals.md @@ -1,13 +1,14 @@ # View certificates in host vitals -Fleet [v4.65.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.65.0) expands host vitals to include a list of certificates for macOS, iOS, and iPadOS hosts. This feature allows you to view the certificates installed on devices, helping you understand if a missing or expired certificate is the reason why an end user can't connect to the corporate network. +Fleet [v4.65.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.65.0) expands host vitals to include a list of certificates for macOS, iOS, and iPadOS hosts. Fleet [v4.90.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.90.0) adds support for Windows hosts. This feature allows you to view the certificates installed on devices, helping you understand if a missing or expired certificate is the reason why an end user can't connect to the corporate network. This guide introduces you to the certificates section in host vitals and explains how to access and interpret the certificate information. ## Prerequisites -* Fleet [v4.65.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.65.0) or greater. -* macOS, iOS, or iPadOS devices enrolled in Fleet. +* Fleet [v4.65.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.65.0) or greater for macOS, iOS, and iPadOS hosts. Fleet [v4.90.0](https://github.com/fleetdm/fleet/releases/tag/fleet-v4.90.0) or greater for Windows hosts. +* macOS, iOS, iPadOS, or Windows devices enrolled in Fleet. +* For Windows hosts, osquery 5.23.1 or greater, which is included with fleetd. ## How does it work? @@ -17,17 +18,19 @@ The **Certificates** section displays the name of the certificate and its expira Fleet API users can access host certificate information via the "Get host's certificates" [endpoint](https://fleetdm.com/docs/rest-api/rest-api#get-hosts-certificates). -For macOS hosts, Fleet retrieves certificate information using osquery's `certificates` [table](https://fleetdm.com/learn-more-about/certificates-query). For iOS and iPadOS hosts, Fleet retrieves certificates via MDM using the `CertificateList` [command](https://developer.apple.com/documentation/devicemanagement/certificate-list-command). +For macOS and Windows hosts, Fleet retrieves certificate information using osquery's `certificates` [table](https://fleetdm.com/learn-more-about/certificates-query). For iOS and iPadOS hosts, Fleet retrieves certificates via MDM using the `CertificateList` [command](https://developer.apple.com/documentation/devicemanagement/certificate-list-command). + +On Windows hosts, Fleet shows certificates in the **Personal** certificate store. To see certificates in other stores, you can query the `certificates` table directly. Fleet labels each certificate's scope as either **System** or **User**. System certificates are installed in the local machine's Personal store. User certificates are installed in a specific user's Personal store, and Fleet shows the owning username. Because osquery runs as the local system account, it can read a user's certificates only while that user is logged in. When no user is logged in, Fleet only updates host's system certificates, leaving all users' certificates in their previous state. When a macOS host installs a configuration profile containing an ACME payload, Fleet also retrieves the resulting certificate via the MDM `CertificateList` command. This surfaces hardware-bound ACME certificates that don't appear in osquery's `certificates` table. Ingestion runs per-host on each ACME profile install and re-install — there is no recurring cadence — so certificates from a given profile become visible the first time the profile is installed or re-deployed on a host. ## Conclusion -The certificates section in host vitals provides you with a quick overview of the certificates installed on your macOS, iOS, and iPadOS devices. This feature helps you identify and troubleshoot certificate-related issues that may prevent your end users from connecting to the corporate network. +The certificates section in host vitals provides you with a quick overview of the certificates installed on your macOS, iOS, iPadOS, and Windows devices. This feature helps you identify and troubleshoot certificate-related issues that may prevent your end users from connecting to the corporate network. - - + + - + \ No newline at end of file diff --git a/articles/windows-linux-setup-experience.md b/articles/windows-linux-setup-experience.md index a50014ecb2..09a36603cc 100644 --- a/articles/windows-linux-setup-experience.md +++ b/articles/windows-linux-setup-experience.md @@ -51,7 +51,9 @@ If software installs fail, Fleet automatically retries. Learn more in the [setup To replace the Fleet logo with your organization's logo: 1. Go to **Settings** > **Organization settings** > **Organization info** + 2. Add URLs to your logos in the **Organization avatar URL (for dark backgrounds)** and **Organization avatar URL (for light backgrounds)** fields + 3. Press **Save** > See [configuration documentation](https://fleetdm.com/docs/configuration/yaml-files#org-info) for recommended logo sizes. @@ -75,9 +77,13 @@ For Windows hosts enrolling through Autopilot or Entra OOBE, you can configure F To enable for a team: 1. Select the team you're configuring (or **No team**) from the team dropdown. + 2. Go to **Controls** > **Setup experience** > **Install software**. + 3. Click the **Windows** tab. + 4. Switch on **Cancel setup if software fails**. + 5. Press **Save**. The setting only applies to Autopilot and Entra-join-during-OOBE enrollments. On those paths, when a setup-experience software install fails, Fleet does the following: @@ -99,12 +105,41 @@ On Autopilot or Entra-OOBE, the device shows "Working on it..." for roughly a mi Add setup experience software setup experience: 1. Click on the **Controls** tab in the main navigation bar, then **Setup experience** > **3. Install software**. + 2. Click on the tab corresponding to the operating system (e.g. Linux). + 3. Click **Add software**, then select or search for the software you want installed during the setup experience. + 4. Press **Save** to save your selection. Fleet also provides a API endpoints for managing setup experience software programmatically. Learn more in Fleet's [API reference](https://fleetdm.com/docs/rest-api/rest-api#update-software-setup-experience). +## Managed local account +Fleet can create a hidden admin account (_fleetadmin) with a unique password on each Windows host during setup. IT admins can use this account as a break-glass login for troubleshooting. + +This feature is available for Windows hosts that automatically enroll via Azure AD. Manually enrolled hosts are not supported. + +> For macOS managed local accounts, see the [macOS MDM setup guide](https://fleetdm.com/guides/macos-mdm-setup). + +### Enable managed local accounts +1. Select the team you're configuring (or No team) from the team dropdown. + +2. Go to **Controls > Setup experience > Users** and click the **Windows** tab. + +4. Select **Managed > Create hidden admin**. + +5. Press **Save**. + +Alternatively, you can enable this using Fleet's REST API or a GitOps workflow. + +Wipe and re-enroll any existing Windows hosts that should receive the account. Hosts enrolled before the feature is turned on won't receive a managed account until they go through the setup experience again. + +### View the managed account password +To view the password for a host's managed account, go to Host details > Actions > Show managed account. The password is unique per host and stored securely in Fleet. + +### Sign in as the managed account +The managed account is hidden from the Windows sign-in screen. To log in as `_fleetadmin`, select **Other user** on the sign-in screen and enter the username and password manually. If the sign-in screen does not show Other user, type `.\\_fleetadmin` in the username field to authenticate against the local machine. + ## Recover a Windows host from the setup failure screen When a Windows host is parked at the Enrollment Status Page failure screen, the on-screen options are limited to **Reset device** (which wipes the host) and a **Collect logs** button that may or may not appear. The procedures below let you log in to the device and reach a desktop without wiping anything. @@ -144,8 +179,11 @@ Restart-Computer -Force To run it: 1. Change `StrongPassword123!` to a password your organization controls. + 2. Go to **Controls** > **Scripts** and upload the script, or open the host's detail page and select **Actions** > **Run script** to paste it inline. + 3. Run the script against the locked-out host. + 4. The host's orbit agent picks up the script within a few seconds and runs it as SYSTEM. The host reboots automatically as the last step. After the reboot, the device leaves the failure screen on its own and arrives at a Windows sign-in screen. diff --git a/docs/Configuration/fleet-server-configuration.md b/docs/Configuration/fleet-server-configuration.md index bad7624df4..59cd390cee 100644 --- a/docs/Configuration/fleet-server-configuration.md +++ b/docs/Configuration/fleet-server-configuration.md @@ -3708,22 +3708,24 @@ If you have an [Apple Developer account that is enabled as an MDM vendor](https: apple_vpp_app_metadata_api_bearer_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ92eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikp ``` -### mdm.enable_custom_filevault +### mdm.enable_custom_disk_encryption -> `mdm.enable_custom_os_updates_and_filevault` is deprecated as of Fleet 4.87.0. Custom OS updates will be enabled for all, for FileVault you can use `mdm.enable_custom_filevault` instead. When set to `true`, it enables both custom OS update and FileVault profiles (equivalent to setting both replacement options to `true`). Maintained for backwards compatibility. +> `mdm.enable_custom_filevault` is deprecated as of Fleet 4.90.0 and `mdm.enable_custom_os_updates_and_filevault` is deprecated as of Fleet 4.87.0. Both are maintained for backwards compatibility. Please use `mdm.enable_custom_disk_encryption` instead. As of Fleet 4.87.0, custom OS updates are enabled by default. *Available in Fleet Premium.* -Allows users to add custom Apple MDM profiles for FileVault management, including [FDEFileVault](https://developer.apple.com/documentation/devicemanagement/fdefilevault), [FDEFileVaultOptions](https://developer.apple.com/documentation/devicemanagement/fdefilevaultoptions), and [FDERecoveryKeyEscrow](https://developer.apple.com/documentation/devicemanagement/fderecoverykeyescrow) configuration profiles +For macOS, allows users to add custom macOS [configuration profiles](https://fleetdm.com/guides/custom-os-settings) for FileVault, including [FDEFileVault](https://developer.apple.com/documentation/devicemanagement/fdefilevault), [FDEFileVaultOptions](https://developer.apple.com/documentation/devicemanagement/fdefilevaultoptions), and [FDERecoveryKeyEscrow](https://developer.apple.com/documentation/devicemanagement/fderecoverykeyescrow) configuration profiles. -> Enabling this option may cause conflicts between your custom FileVault configuration profiles and the profiles Fleet manages under the hood for disk encryption. +For Windows, allows users to add custom Windows profiles for BitLocker. + +> Enabling this option may cause conflicts between your custom disk encryption configuration profiles and the profiles Fleet manages under the hood when [Fleet's disk encryption](https://fleetdm.com/guides/enforce-disk-encryption) is enabled. - Default value: `false` -- Environment variable: `FLEET_MDM_ENABLE_CUSTOM_FILEVAULT` +- Environment variable: `FLEET_MDM_ENABLE_CUSTOM_DISK_ENCRYPTION` - Config file format: ```yaml mdm: - enable_custom_filevault: false + enable_custom_disk_encryption: false ``` ### mdm.allow_all_declarations diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index 4f20d0bbce..14783daec7 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -342,7 +342,7 @@ agent_options: The `controls` section allows you to configure scripts and device management (MDM) features in Fleet. -- `scripts` is a list of paths to macOS, Windows, or Linux scripts. Supports `path:` (single file) and `paths:` (glob pattern, filtered to `.sh` and `.ps1` files only). Filenames must not contain `*`, `?`, `[`, or `{` when using `path:`. See [`path:` vs `paths:`](#path-vs-paths-glob-patterns) for details. +- `scripts` is a list of paths to macOS, Windows, or Linux scripts. Supports `path:` (single file) and `paths:` (glob pattern, filtered to `.sh`, `.py`, and `.ps1` files only). Filenames must not contain `*`, `?`, `[`, or `{` when using `path:`. See [`path:` vs `paths:`](#path-vs-paths-glob-patterns) for details. - `windows_enabled_and_configured` specifies whether or not to turn on Windows MDM features (default: `false`). Can only be configured for "All fleets" (`default.yml`). - `windows_entra_tenant_ids` is a list of Microsoft Entra tenant IDs to enable automatic (Autopilot) and manual enrollment by end users (**Settings** > **Accounts** > **Access work or school** on Windows). Can only be configured for "All fleets" (`default.yml`). Find your **Tenant ID**, on [**Microsoft Entra ID** > **Home**](https://entra.microsoft.com/#home). - `windows_entra_client_ids` is a list of Microsoft Entra application (client) IDs for the applications used to enroll Windows hosts via Microsoft Entra. Set this when you set up Entra enrollment: Microsoft Entra issues v2 access tokens whose audience is the application's client ID, so Fleet needs the client ID to authorize enrollment. Can only be configured for "All fleets" (`default.yml`). Find your **Application (client) ID** on [**Microsoft Entra ID** > **App registrations**](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) > your MDM application > **Overview**. @@ -352,6 +352,7 @@ The `controls` section allows you to configure scripts and device management (MD - `windows_require_bitlocker_pin` specifies whether or not to require end users on Windows hosts to set a BitLocker PIN. When set, this PIN is required to unlock Windows host during startup. `enable_disk_encryption` must be set to `true`. (default: `false`). - `apple_require_hardware_attestation` specifies whether or not to require Apple Silicon macOS hosts to complete a device attestation challenge verifying that the hardware serial matches a known host record from AB as part of DEP enrollment (default: `false`). Can only be configured for "All fleets" (default.yml). - `enable_recovery_lock_password` specifies whether or not to enforce Recovery Lock password on eligible macOS hosts (default: `false`). +- `name_template` sets a naming convention for macOS, iOS, and iPadOS hosts. Fleet resolves the template per host, renames the host on the device via an MDM command, and updates the host's name in Fleet. Supports the built-in host identity variables (`$FLEET_VAR_HOST_HARDWARE_SERIAL`, `$FLEET_VAR_HOST_UUID`, `$FLEET_VAR_HOST_PLATFORM`), the IdP end-user variables (`$FLEET_VAR_HOST_END_USER_IDP_USERNAME`, `_USERNAME_LOCAL_PART`, `_GROUPS`, `_DEPARTMENT`, `_FULL_NAME`), and custom (`$FLEET_SECRET_*`) variables; certificate authority variables aren't supported. A referenced custom variable must already exist. Supported for fleets and for hosts that aren't in a fleet ("Unassigned"): set it in a fleet's YAML, or in `no_team.yml`/`default.yml` controls to apply it to "Unassigned" hosts. Removing the key clears the template but doesn't rename any host. _Available in Fleet Premium._ - `android_enabled_and_configured` specifies whether or not to turn on Android MDM features (default: `false`). Can only be configured for "All fleets" (`default.yml`). #### Example @@ -362,7 +363,7 @@ controls: - path: ../lib/macos-script.sh - path: ../lib/windows-script.ps1 - path: ../lib/linux-script.sh - - paths: ../lib/scripts/*.sh # Glob pattern (filtered to .sh and .ps1 only) + - paths: ../lib/scripts/*.sh # Glob pattern (filtered to .sh, .py, and .ps1 only) windows_enabled_and_configured: true windows_entra_tenant_ids: - 4e342a0d-ec1a-4353-bdeb-785542e0a8fb @@ -373,6 +374,7 @@ controls: enable_disk_encryption: true # Available in Fleet Premium apple_require_hardware_attestation: false # Available in Fleet Premium enable_recovery_lock_password: true # Available in Fleet Premium + name_template: "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL" # Available in Fleet Premium android_enabled_and_configured: true macos_updates: # Available in Fleet Premium deadline: "2024-12-31" @@ -390,11 +392,19 @@ controls: apple_settings: configuration_profiles: - paths: ../lib/macos/profiles/*.mobileconfig + - path: ../lib/macos/profiles/my-declaration.json + assets: + - path: ../lib/macos/assets/my-asset.json + managed_local_account_settings: + - enabled: true + end_user_local_account_type: "admin" windows_settings: configuration_profiles: - paths: ../lib/windows/profiles/*.xml labels_include_any: - Engineering + managed_local_account_settings: + - enabled: true android_settings: configuration_profiles: - path: ../lib/android-profile.json @@ -442,8 +452,15 @@ controls: ### apple_settings and windows_settings -- `apple_settings.configuration_profiles` is a list of macOS, iOS, and iPadOS configuration profiles (.mobileconfig) or declaration profiles (.json). -- `windows_settings.configuration_profiles` is a list of Windows configuration profiles (.xml). +Both `apple_settings` and `windows_settings` support the following: + +- `configuration_profiles` is a list of configuration profiles. Accepts .mobileconfig/.json (macOS/iOS/iPadOS) or .xml (Windows). +- `managed_local_account_settings` are settings for the managed local account. + - `enabled` specifies whether to create the managed local account on that platform (default: `false`). + +Only `apple_settings` supports the following: + +- `end_user_local_account_type` specifies the end user account type for macOS hosts. Requires `managed_local_account_settings.enabled` to be `true`. Default: `"admin"`. Each entry can use either `path:` or `paths:`: @@ -452,6 +469,8 @@ Each entry can use either `path:` or `paths:`: Use `labels_include_all` to target hosts that have all labels, `labels_include_any` to target hosts that have any label, or `labels_exclude_any` to target hosts that don't have any of the labels. Only one of `labels_include_all`, `labels_include_any`, or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. +In addition to configuration profiles, you can upload **assets** which are `.json` files containing an Apple asset declaration (`com.apple.asset`). Assets follow the same `path:` / `paths:` syntax as profiles but should be stored in a separate `assets/` folder (e.g. `../lib/macos/assets/my-asset.json`). + ### android_settings - `android_settings.configuration_profiles` is a list of Android configuration profiles (.json). @@ -498,8 +517,9 @@ The `setup_experience` section lets you control the out-of-the-box [setup experi - `apple_enable_release_device_manually` when enabled, you're responsible for sending the [`DeviceConfigured` command](https://developer.apple.com/documentation/devicemanagement/device-configured-command). End users will be stuck in Setup Assistant until this command is sent. Applies to Apple (macOS, iOS, iPadOS) hosts that automatically enroll via Apple Business (AB). - `apple_setup_assistant` is a path to a custom [automatic enrollment (ADE) profile](https://support.apple.com/guide/deployment/automated-device-enrollment-management-dep73069dd57/web) (.json). Applies to macOS and iOS/iPadOS hosts. - `macos_script` is the path to a custom setup script to run after the host is first set up. Applies to macOS only. -- `enable_managed_local_account` specifies whether or not to create a local admin managed account on macOS hosts (default: `false`). -- `end_user_local_account_type` specifies the end user account type. `enable_managed_local_account` must be set to `true`. (default: `admin`). + +`enable_managed_local_account` and `end_user_local_account_type` at this level are deprecated. +Please use the platform-specific `apple_settings.managed_local_account_settings`, `apple_settings.end_user_local_account_type`, or `windows_settings.managed_local_account_settings` instead. #### Example @@ -530,7 +550,7 @@ Can only be configured for "All fleets" (`default.yml`). The `software` section allows you to configure packages, store apps (Apple App Store and Google Play Store), and Fleet-maintained apps that you want to install on your hosts. -- `packages` is a list of paths to custom packages (.pkg, .ipa, .msi, .exe, .deb, .rpm, .tar.gz, .sh, or .ps1). +- `packages` is a list of paths to custom packages (.pkg, .ipa, .msi, .exe, .deb, .rpm, .tar.gz, .sh, .py, or .ps1). - `app_store_apps` is a list of Apple App Store or Android Play Store apps. - `fleet_maintained_apps` is a list of Fleet-maintained apps. @@ -540,6 +560,8 @@ Currently, Fleet only allows one package, Apple App Store app, or Fleet-maintain Currently, when a `.ipa` file is added in `packages`, Fleet adds software for both iOS and iPadOS, along with all specified settings (e.g. `self_service`). If software for one platform is deleted in the UI, it will come back when GitOps is re-run. +Script-only packages (.sh, .ps1, .py) also support $FLEET_SECRET_* variables. Fleet replaces them with their values when the install script is sent to the host. + #### Example `fleets/fleet-name.yml`, or `fleets/unassigned.yml` @@ -600,6 +622,7 @@ software: ``` #### self_service, labels, categories, and setup_experience + - `self_service` specifies whether end users can install from **Fleet Desktop > Self-service** (default: `false`) on macOS or [self-service web app](https://fleetdm.com/learn-more-about/deploy-self-service-to-ios) on iOS/iPadOS. - `labels_include_all` targets hosts that **have all** of the specified labels. `labels_include_any` targets hosts that **have any** of the specified labels. `labels_exclude_any` targets hosts that **have none** of the specified labels. Only one of these fields can be set. If none are set, all hosts are targeted. - `categories` is a list of self-service category names. Categories group self-service software on your end users' **Fleet Desktop > My device** page so that end users can filter by category and install all software in a category at once. @@ -622,6 +645,46 @@ software: #### Example +##### Multiple versions of the same software + +You can add multiple packages for the same software in a package YAML file. This enables staged rollouts and support of architecture-specific installers. + +`self_service`, `categories`, and labels are defined per package. `setup_experience` is defined on the fleet-level. + +If multiple packages target the same host, Fleet will install the one that was added first. + +> In GitOps, the first package added is the first one in the package YAML file's list on the initial run that adds the title's packages. Reordering the list on a later run doesn't change the order. +> +> You can preview the order of the packages in the UI. The first package in the list is always a fallback in case of a conflict. + +`fleets/fleet-name.yml`, or `fleets/unassigned.yml` + +```yaml +software: + packages: + - path: ../lib/software/santa.package.yml +``` + +`lib/software/santa.package.yml` + +```yaml +- url: https://github.com/northpolesec/santa/releases/download/2026.2/santa-2026.2.pkg + install_script: + path: ../lib/software/santa-install-script.sh + self_service: true + labels_include_all: + - macOS +- url: https://github.com/northpolesec/santa/releases/download/2026.4/santa-2026.4.pkg + install_script: + path: ../lib/software/santa-install-script.sh + self_service: true + categories: + - "💻 Productivity" + labels_include_all: + - macOS + - IT test team +``` + ##### URL `lib/software-name.package.yml`: @@ -660,7 +723,9 @@ If your server doesn't support ETags reliably, you can disable this behavior wit ##### Script-only -Script-only packages (`.sh` and `.ps1` files) are created by referencing a script file in the fleet YAML file. Script-only packages don't support `install_script` (the file contents are the install script) or automatic install (`install_software` in policies). +Script-only packages (`.sh`, `.py`, and `.ps1` files) are referenced directly inline in the fleet's YAML file. The file contents become the install script. Script packages do not support `install_script`, `uninstall_script`, `post_install_script`, `pre_install_query`, or automatic install (`install_software` in policies). + +`self_service`, `categories`, `labels`, and `icon` are specified inline in the team's YAML file. ```yaml software: diff --git a/docs/Contributing/guides/cli/fleetctl-apply.md b/docs/Contributing/guides/cli/fleetctl-apply.md index 6b93aefee2..81977ea52c 100644 --- a/docs/Contributing/guides/cli/fleetctl-apply.md +++ b/docs/Contributing/guides/cli/fleetctl-apply.md @@ -502,6 +502,9 @@ spec: - path: '/path/to/profile1.mobileconfig' - path: '/path/to/profile2.mobileconfig' - path: '/path/to/profile3.mobileconfig' + - path: '/path/to/declaration.json' + assets: + - path: '/path/to/asset.json' enable_disk_encryption: true windows_settings: configuration_profiles: diff --git a/docs/Contributing/reference/api-for-contributors.md b/docs/Contributing/reference/api-for-contributors.md index d79f20e4e0..42f89a12cd 100644 --- a/docs/Contributing/reference/api-for-contributors.md +++ b/docs/Contributing/reference/api-for-contributors.md @@ -713,6 +713,7 @@ Content-Type: application/octet-stream "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2024-10-20T00:00:00Z", "terms_expired": false, + "token_invalid": false, "macos_fleet": null, "ios_fleet": null, "ipados_fleet": null, @@ -725,6 +726,7 @@ Content-Type: application/octet-stream "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2024-10-20T00:00:00Z", "terms_expired": false, + "token_invalid": false, "macos_fleet": null, "ios_fleet": null, "ipados_fleet": null, @@ -815,6 +817,7 @@ None. "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2024-11-29T00:00:00Z", "terms_expired": false, + "token_invalid": false, "macos_fleet": 1, "ios_fleet": 2, "ipados_fleet": 3, @@ -827,6 +830,7 @@ None. "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2024-11-29T00:00:00Z", "terms_expired": false, + "token_invalid": false, "macos_fleet": 1, "ios_fleet": 2, "ipados_fleet": 3, @@ -884,6 +888,7 @@ Content-Type: application/octet-stream "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2025-10-20T00:00:00Z", "terms_expired": false, + "token_invalid": false, "macos_fleet": null, "ios_fleet": null, "ipados_fleet": null, @@ -896,6 +901,7 @@ Content-Type: application/octet-stream "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2025-10-20T00:00:00Z", "terms_expired": false, + "token_invalid": false, "macos_fleet": null, "ios_fleet": null, "ipados_fleet": null, @@ -1401,7 +1407,7 @@ Content-Type: application/octet-stream _Available in Fleet Premium_ -Returns the raw data about a DEP device's current state from the [Get Device Details](https://developer.apple.com/documentation/devicemanagement/device-details) API. Supports only Apple hosts which are, or were, assigned to Fleet in Apple Business. +Returns the raw data about a DEP device's current state from the [Get Device Details](https://developer.apple.com/documentation/devicemanagement/device-details) API. Supports only Apple hosts which are, or were, assigned to Fleet in Apple Business. If there is an error communicating with the DEP APIs, `dep_device` will be null and `dep_device_error` will contain human-readable error details. `GET /api/v1/fleet/hosts/:id/dep_assignment` @@ -1446,7 +1452,8 @@ Returns the raw data about a DEP device's current state from the [Get Device Det "ab_token_id": 1, "mdm_migration_deadline": "2025-12-05T00:00:00Z", "mdm_migration_completed": "2025-12-05T00:00:00Z" - } + }, + "dep_device_error": null } ``` @@ -2220,7 +2227,8 @@ If the `name` is not already associated with an existing fleet, this API route c | mdm.macos_updates.minimum_version | string | body | The required minimum operating system version. | | mdm.macos_updates.deadline | string | body | The required installation date for Nudge to enforce the operating system version. | | mdm.apple_settings | object | body | The Apple-specific MDM settings. | -| mdm.apple_settings.configuration_profiles | array | body | The list of objects consists of a `path` to .mobileconfig or JSON file and `labels_include_all`, `labels_include_any`, or `labels_exclude_any` list of label names. | +| mdm.apple_settings.configuration_profiles | array | body | The list of objects consists of a `path` to a .mobileconfig or JSON file and `labels_include_all`, `labels_include_any`, or `labels_exclude_any` list of label names. | +| mdm.apple_settings.assets | array | body | The list of objects consists of a `path` to a JSON asset declaration (`com.apple.asset`) file. | | mdm.windows_settings | object | body | The Windows-specific MDM settings. | | mdm.windows_settings.configuration_profiles | array | body | The list of objects consists of a `path` to XML files and `labels_include_all`, `labels_include_any`, or `labels_exclude_any` list of label names. | | scripts | array | body | A list of script files to add to this fleet so they can be executed at a later time. | @@ -2299,20 +2307,25 @@ If the `name` is not already associated with an existing fleet, this API route c "apple_settings": { "configuration_profiles": [ { - "path": "path/to/profile1.mobileconfig" + "path": "path/to/profile1.mobileconfig", "labels_include_all": ["Label 1", "Label 2"] }, { - "path": "path/to/profile2.json" + "path": "path/to/profile2.json", "labels_exclude_any": ["Label 3", "Label 4"] }, ], + "assets": [ + { + "path": "path/to/assets/asset.json" + }, + ], "enable_disk_encryption": true }, "windows_settings": { "configuration_profiles": [ { - "path": "path/to/profile3.xml" + "path": "path/to/profile3.xml", "labels_include_all": ["Label 1", "Label 2"] } ] diff --git a/docs/Contributing/reference/audit-logs.md b/docs/Contributing/reference/audit-logs.md index 89ddfc0d54..2cc1771459 100644 --- a/docs/Contributing/reference/audit-logs.md +++ b/docs/Contributing/reference/audit-logs.md @@ -902,9 +902,11 @@ This activity contains the following fields: ## edited_macos_profile -Generated when a user edits the macOS profiles of a fleet (or no fleet) via the fleetctl CLI. +Generated when a user edits the macOS profiles of a fleet (or no fleet) via the fleetctl CLI, or edits a single macOS profile via the edit profile endpoint. This activity contains the following fields: +- "profile_name": Name of the edited profile. Only present when a single profile was edited; omitted for fleetctl/GitOps batch edits. +- "profile_identifier": Identifier of the edited profile. Only present when a single profile was edited; omitted for fleetctl/GitOps batch edits. - "fleet_id": The ID of the fleet that the profiles apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). - "fleet_name": The name of the fleet that the profiles apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). @@ -912,6 +914,8 @@ This activity contains the following fields: ```json { + "profile_name": "Custom settings 1", + "profile_identifier": "com.my.profile", "team_id": 123, "team_name": "Workstations", "fleet_id": 123, @@ -1352,9 +1356,10 @@ This activity contains the following fields: ## edited_windows_profile -Generated when a user edits the Windows profiles of a fleet (or no fleet) via the fleetctl CLI. +Generated when a user edits the Windows profiles of a fleet (or no fleet) via the fleetctl CLI, or edits a single Windows profile via the edit profile endpoint. This activity contains the following fields: +- "profile_name": Name of the edited profile. Only present when a single profile was edited; omitted for fleetctl/GitOps batch edits. - "fleet_id": The ID of the fleet that the profiles apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). - "fleet_name": The name of the fleet that the profiles apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). @@ -1362,6 +1367,7 @@ This activity contains the following fields: ```json { + "profile_name": "Custom settings 1", "team_id": 123, "team_name": "Workstations", "fleet_id": 123, @@ -1489,9 +1495,11 @@ This activity contains the following fields: ## edited_declaration_profile -Generated when a user edits the macOS declarations of a fleet (or no fleet) via the fleetctl CLI. +Generated when a user edits the macOS declarations of a fleet (or no fleet) via the fleetctl CLI, or edits a single declaration via the edit profile endpoint. This activity contains the following fields: +- "profile_name": Name of the edited declaration. Only present when a single declaration was edited; omitted for fleetctl/GitOps batch edits. +- "profile_identifier": Identifier of the edited declaration. Only present when a single declaration was edited; omitted for fleetctl/GitOps batch edits. - "fleet_id": The ID of the fleet that the declarations apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). - "fleet_name": The name of the fleet that the declarations apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). @@ -1499,6 +1507,8 @@ This activity contains the following fields: ```json { + "profile_name": "Passcode requirements", + "profile_identifier": "com.my.declaration", "team_id": 123, "team_name": "Workstations", "fleet_id": 123, @@ -1550,9 +1560,10 @@ This activity contains the following fields: ## edited_android_profile -Generated when a user edits the Android profiles of a fleet (or no fleet) via the fleetctl CLI. +Generated when a user edits the Android profiles of a fleet (or no fleet) via the fleetctl CLI, or edits a single Android profile via the edit profile endpoint. This activity contains the following fields: +- "profile_name": Name of the edited profile. Only present when a single profile was edited; omitted for fleetctl/GitOps batch edits. - "fleet_id": The ID of the fleet that the profiles apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). - "fleet_name": The name of the fleet that the profiles apply to, `null` if they apply to devices that are not in a fleet ("Unassigned"). @@ -1560,6 +1571,7 @@ This activity contains the following fields: ```json { + "profile_name": "Custom settings 1", "team_id": 123, "team_name": "Workstations", "fleet_id": 123, @@ -2898,6 +2910,25 @@ This activity contains the following fields: } ``` +## edited_host_name_template + +Generated when a user edits the host name template for a fleet (or no fleet). + +This activity contains the following fields: +- "fleet_id": The ID of the fleet that the host name template applies to, `null` if it applies to devices that are not in a fleet ("Unassigned"). +- "fleet_name": The name of the fleet that the host name template applies to, `null` if it applies to devices that are not in a fleet ("Unassigned"). +- "name_template": The host name template, `null` if the template was cleared. + +#### Example + +```json +{ + "fleet_id": 123, + "fleet_name": "Workstations", + "name_template": "WS-$FLEET_VAR_HOST_HARDWARE_SERIAL" +} +``` + ## rotated_managed_local_account_password Generated when a managed local account password is rotated. @@ -3134,8 +3165,33 @@ This activity contains the following fields: ```json { - "fleet_id": 1, - "fleet_name": "💻 Workstations" + "fleet_id": 123, + "fleet_name": "Workstations" +} +``` + +## ran_custom_mdm_command + +Generated when a user runs a custom MDM command via API or the fleetctl CLI. + +This activity contains the following fields: +- "host_id": ID of the host. +- "host_display_name": Display name of the host. +- "host_uuid": UUID of the host. +- "command_uuid": UUID of the MDM command used to install the app. +- "request_type": the type of custom MDM command. +- "platform": the platform of the host ("darwin" or "windows"). + +#### Example + +```json +{ + "host_id": 1, + "host_display_name": "Anna's MacBook Pro", + "host_uuid": "1b3d5e7f-9a2c-4e6d-8b0a-1c3d5e7f9a2b", + "command_uuid": "98765432-1234-1234-1234-1234567890ab", + "request_type": "EraseDevice", + "platform": "darwin" } ``` @@ -3181,6 +3237,63 @@ This activity contains the following fields: } ``` +## created_apple_asset_declaration + +Generated when creating an Apple asset declaration. + +This activity contains the following fields: +- "fleet_id": the ID of the fleet the asset belongs to. +- "fleet_name": the name of the fleet the asset belongs to. +- "asset_name": the name of the asset. + +#### Example + +```json +{ + "fleet_id": 1, + "fleet_name": "💻 Workstations", + "asset_name": "My Asset" +} +``` + +## edited_apple_asset_declaration + +Generated when an Apple asset declaration is edited. + +This activity contains the following fields: +- "fleet_id": the ID of the fleet the asset belongs to. +- "fleet_name": the name of the fleet the asset belongs to. +- "asset_name": the name of the asset. + +#### Example + +```json +{ + "fleet_id": 1, + "fleet_name": "💻 Workstations", + "asset_name": "My Asset" +} +``` + +## deleted_apple_asset_declaration + +Generated when an Apple asset declaration is deleted. + +This activity contains the following fields: +- "fleet_id": the ID of the fleet the asset belongs to. +- "fleet_name": the name of the fleet the asset belongs to. +- "asset_name": the name of the asset. + +#### Example + +```json +{ + "fleet_id": 1, + "fleet_name": "💻 Workstations", + "asset_name": "My Asset" +} +``` + diff --git a/docs/Contributing/reference/configuration-for-contributors.md b/docs/Contributing/reference/configuration-for-contributors.md index 8d0c6112a5..24d22aa441 100644 --- a/docs/Contributing/reference/configuration-for-contributors.md +++ b/docs/Contributing/reference/configuration-for-contributors.md @@ -180,20 +180,6 @@ Whether to send anonymous usage statistics. Overrides the value set by `enable_a enable_analytics: false ``` -### microsoft_compliance_partner.proxy_api_key - -For managed cloud customers only. The Fleet team sets this key. - -Key that allows the Fleet server to communicate to the Microsoft compliance partner proxy on fleetdm.com. - -- Default value: "" -- Environment variable: `FLEET_MICROSOFT_COMPLIANCE_PARTNER_PROXY_API_KEY` -- Config file format: - ```yaml - microsoft_compliance_partner: - proxy_api_key: foobar - ``` - ### mdm.enable_custom_os_updates_and_filevault Documentation for setting has moved to the [Fleet server configuration](https://fleetdm.com/docs/configuration/fleet-server-configuration#mdm-enable-custom-os-updates-and-filevault) reference. diff --git a/docs/Deploy/single-sign-on-sso.md b/docs/Deploy/single-sign-on-sso.md index 431b341e87..5f6a98bd79 100644 --- a/docs/Deploy/single-sign-on-sso.md +++ b/docs/Deploy/single-sign-on-sso.md @@ -169,9 +169,9 @@ After generating the XML file, upload it to your identity provider according to ## Fleet configuration -To configure SSO in Fleet head to **Settings > Integrations > Single sign-on (SSO) > Fleet users**. +To configure SSO in Fleet head to **Settings > Integrations > Authentication (SSO) > Fleet users**. -If you're configuring IdP authentication for setup experience head to **Settings > Integrations > Single sign-on (SSO) > End users**. +If you're configuring end user authentication head to **Settings > Integrations > Authentication (SSO) > End users**. - **Identity provider name** - A human-readable name of the IdP. This is rendered on the login page. @@ -189,7 +189,7 @@ If you're configuring IdP authentication for setup experience head to **Settings `Applies only to Fleet Premium` -Fleet can automatically create users using just-in-time (JIT) provisioning. To enable this, go to **Settings > Integrations > Single sign-on (SSO) > Fleet users** and check **Create user and sync permissions on login**. +Fleet can automatically create users using just-in-time (JIT) provisioning. To enable this, go to **Settings > Integrations > Authentication (SSO) > Fleet users** and check **Create user and sync permissions on login**. When enabled, Fleet will automatically create an account when a user logs in for the first time with the configured SSO. The new account's email and full name are copied from the user data in the SSO response. @@ -289,7 +289,7 @@ When SCIM is configured with your IdP, Fleet automatically deletes a user's Flee Fleet requires the `userName`, `email`, `givenName`, and `familyName` attributes to be mapped from your IdP for Fleet users. In Okta, are typically mapped from `userName`, `user.email`, `user.firstName`, and `user.lastName` respectively. -If the user is later reactivated in the IdP, Fleet will automatically recreate the account on the user’s next SSO login, as long as **Create user and sync permissions on login** in **Settings > Integrations > Single sign-on (SSO)** is enabled. +If the user is later reactivated in the IdP, Fleet will automatically recreate the account on the user’s next SSO login, as long as **Create user and sync permissions on login** in **Settings > Integrations > Authentication (SSO)** is enabled. No manual intervention is required. This applies only to SSO-authenticated users. API-only and password-authenticated users are not affected. diff --git a/docs/Get started/FAQ.md b/docs/Get started/FAQ.md index 66c4f2f4bf..9640eafcb9 100644 --- a/docs/Get started/FAQ.md +++ b/docs/Get started/FAQ.md @@ -75,7 +75,7 @@ Fleet supports the following operating system versions on hosts. | macOS | 14+ (Sonoma) | | iOS/iPadOS | 17+ | | Windows | Pro and Enterprise 10 21H2 (E) (LTS)+, Server 2012+ | -| Linux | CentOS 7.1+, Ubuntu 20.04+, Fedora 38+, Amazon Linux 2+, Debian 11+, Red Hat Enterprise Linux (RHEL) 7+, openSUSE 15.6+, Arch Linux, Omarchy | +| Linux | CentOS 7.1+, Ubuntu 20.04+, Fedora 38+, Amazon Linux 2+, Debian 11+, Red Hat Enterprise Linux (RHEL) 7+, openSUSE 15.6+, Arch Linux, Omarchy, CachyOS, Zorin OS 16+ | | ChromeOS | 112.0.5615.134+ | | Android | 14+ | diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index f32ca4cd07..77ed8656e4 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -1814,6 +1814,7 @@ None. "enable_disk_encryption": true, "windows_require_bitlocker_pin": false, "apple_require_hardware_attestation": false, + "name_template": "", "macos_updates": { "minimum_version": "12.3.1", "deadline": "2022-01-01", @@ -1844,8 +1845,21 @@ None. { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] + }, + { + "path": "path/to/declaration.json", + "labels": ["Label 1", "Label 2"] } - ] + ], + "assets": [ + { + "path": "path/to/assets/asset.json" + } + ], + "managed_local_account_settings": { + "enabled": true + }, + "end_user_local_account_type": "admin" }, "windows_settings": { "custom_settings": [ @@ -1859,7 +1873,10 @@ None. "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } - ] + ], + "managed_local_account_settings": { + "enabled": true + } }, "scripts": ["path/to/script.sh"], "end_user_authentication": { @@ -1887,7 +1904,9 @@ None. "enable_end_user_authentication": false, "apple_setup_assistant": "path/to/config.json", "enable_release_device_manually": false, - "manual_agent_install": false + "manual_agent_install": false, + "enable_managed_local_account": false, + "end_user_local_account_type": "admin" }, "client_url": "https://instance.fleet.com", "apple_account_provisioning": { @@ -1923,7 +1942,6 @@ None. "tier": "premium", "organization": "fleet", "device_count": 500000, - "managed_cloud": false, "expiration": "2031-10-16T00:00:00Z", "note": "" }, @@ -2233,7 +2251,16 @@ Modifies the Fleet's configuration with the supplied information. "path": "path/to/profile3.json", "labels_include_any": ["Label 5", "Label 6"] } - ] + ], + "assets": [ + { + "path": "path/to/assets/asset.json" + } + ], + "managed_local_account_settings": { + "enabled": true + }, + "end_user_local_account_type": "admin" }, "windows_settings": { "custom_settings": [ @@ -2247,7 +2274,10 @@ Modifies the Fleet's configuration with the supplied information. "path": "path/to/profile3.xml", "labels_exclude_any": ["Label 1", "Label 2"] } - ] + ], + "managed_local_account_settings": { + "enabled": true + } }, "end_user_authentication": { "entity_id": "", @@ -2271,6 +2301,8 @@ Modifies the Fleet's configuration with the supplied information. "setup_experience": { "bootstrap_package": "", "enable_end_user_authentication": false, + "enable_managed_local_account": false, + "end_user_local_account_type": "admin", "lock_end_user_info": true, "apple_setup_assistant": "path/to/config.json" }, @@ -2843,6 +2875,7 @@ When updating conditional access config, all `conditional_access` fields must ei | windows_require_bitlocker_pin | boolean | _Available in Fleet Premium._ End users on Windows hosts that are "Unassigned" will be required to set a BitLocker PIN if set to true. `enable_disk_encryption` must be set to true. When the PIN is set, it's required to unlock Windows host during startup. | | apple_require_hardware_attestation | boolean | _Available in Fleet Premium._ Specifies whether or not to require Apple Silicon macOS hosts to complete a device attestation challenge verifying that the hardware serial matches a known host record from ABM as part of DEP enrollment. | | enable_recovery_lock_password | boolean | _Available in Fleet Premium._ Unassigned hosts will have Recovery Lock password enabled if set to true. | +| name_template | string | _Available in Fleet Premium._ Naming convention applied to "Unassigned" macOS, iOS, and iPadOS hosts. Supports the built-in host identity and IdP end-user variables and custom (`$FLEET_SECRET_*`) variables; certificate authority variables aren't supported. See the [Update host name template](#update-host-name-template) endpoint for the full list. An empty string clears the template. To set the template for a fleet, use that endpoint. | | macos_updates | object | See [`mdm.macos_updates`](#mdm-macos-updates). | | ios_updates | object | See [`mdm.ios_updates`](#mdm-ios-updates). | | ipados_updates | object | See [`mdm.ipados_updates`](#mdm-ipados-updates). | @@ -2850,6 +2883,7 @@ When updating conditional access config, all `conditional_access` fields must ei | macos_migration | object | See [`mdm.macos_migration`](#mdm-macos-migration). | | setup_experience | object | See [`mdm.setup_experience`](#mdm-setup-experience). | | macos_settings | object | See [`mdm.macos_settings`](#mdm-macos-settings). | +| apple_settings | object | See [`mdm.apple_settings`](#mdm-macos-settings). | | windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings). | | apple_server_url | string | Update this URL if you're self-hosting Fleet and you want your hosts to talk to this URL for MDM features. (If not configured, hosts will use the base URL of the Fleet instance.) | @@ -2932,13 +2966,12 @@ _Available in Fleet Premium._ `mdm.setup_experience` is an object with the following structure: -| Name | Type | Description | -| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| enable_end_user_authentication | boolean | If set to true, IdP authentication will be required during automatic MDM enrollment of new macOS devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#require-idp-authentication). | -| enable_managed_local_account | boolean | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on macOS hosts if set to true. | -| end_user_local_account_type | string | _Available in Fleet Premium._ Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | -| lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) | -| enable_managed_local_account | boolean | Whether to enforce creating managed local accounts on macOS hosts that automatically enroll. | +| Name | Type | Description | +| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| enable_end_user_authentication | boolean | If set to true, end user authentication will be required during automatic MDM enrollment of new macOS devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#end-user-authentication). | +| enable_managed_local_account | boolean | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on eligible hosts if set to true. | +| end_user_local_account_type | string | _Available in Fleet Premium._ Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | +| lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) |
@@ -2946,9 +2979,22 @@ _Available in Fleet Premium._ `mdm.macos_settings` is an object with the following structure: -| Name | Type | Description | -| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | +| Name | Type | Description | +| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | + +
+ +##### mdm.apple_settings + +`mdm.apple_settings` is an object with the following structure: + +| Name | Type | Description | +| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | +| managed_local_account_settings | object | Settings for the managed local account. | +| managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). | +| end_user_local_account_type | string | The end user account type. Requires `managed_local_account_settings.enabled` to be `true`. Options: `"admin"`, `"standard"`, `"none"` (default: `"admin"`). |
@@ -2956,9 +3002,11 @@ _Available in Fleet Premium._ `mdm.windows_settings` is an object with the following structure: -| Name | Type | Description | -| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add Windows configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | +| Name | Type | Description | +| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add Windows configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | +| managed_local_account_settings | object | Settings for the managed local account. | +| managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). |
@@ -3004,8 +3052,16 @@ _Available in Fleet Premium._ { "path": "path/to/profile2.json", "labels": ["Label 3", "Label 4"] - }, - ] + } + ], + "assets": [ + { + "path": "path/to/assets/asset.json" + } + ], + "managed_local_account_settings": { + "enabled": true + } }, "windows_settings": { "configuration_profiles": [ @@ -3013,7 +3069,10 @@ _Available in Fleet Premium._ "path": "path/to/profile3.xml", "labels": ["Label 1", "Label 2"] } - ] + ], + "managed_local_account_settings": { + "enabled": true + } }, "end_user_authentication": { "entity_id": "", @@ -4208,6 +4267,10 @@ Returns the information of the specified host. "disk_encryption": { "status": "verified", "detail": "" + }, + "host_name": { + "status": "verified", + "detail": "" } }, "profiles": [ @@ -4226,6 +4289,8 @@ Returns the information of the specified host. } ``` +`mdm.os_settings.host_name` reports the host name template enforcement status for a macOS, iOS, or iPadOS host. Its `status` is one of `pending`, `verifying`, `verified`, or `failed`, and `detail` carries the error message when the status is `failed`. The object is omitted entirely for hosts that aren't enforced (no template set on the host's fleet or on "Unassigned", non-MDM hosts, and personal (BYOD) enrollments). + `browser` and `extension_for` fields are included when set and when empty. `extension_for` shows the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. > Note: the response above assumes a [GeoIP database is configured](https://fleetdm.com/docs/deploying/configuration#geoip), otherwise the `geolocation` object won't be included. @@ -6834,10 +6899,17 @@ Deletes the label specified by ID. - [Create configuration profile](#create-configuration-profile) - [List configuration profiles](#list-configuration-profiles) - [Get or download configuration profile](#get-or-download-configuration-profile) +- [Update configuration profile](#update-configuration-profile) - [Delete configuration profile](#delete-configuration-profile) - [Batch-update configuration profiles](#batch-update-configuration-profiles) +- [Create Apple asset declaration](#create-apple-asset-declaration) +- [List Apple asset declarations](#list-apple-asset-declarations) +- [Get or download Apple asset declaration](#get-or-download-apple-asset-declaration) +- [Delete Apple asset declaration](#delete-apple-asset-declaration) - [Update disk encryption](#update-disk-encryption) - [Get disk encryption status](#get-disk-encryption-status) +- [Update host name template](#update-host-name-template) +- [Resend host name template](#resend-host-name-template) - [Update Recovery Lock](#update-recovery-lock) - [Get OS settings (configuration profiles) status](#get-os-settings-configuration-profiles-status) - [Get OS setting (configuration profile) status](#get-os-setting-configuration-profile-status) @@ -6867,7 +6939,7 @@ Add a configuration profile to enforce custom settings on macOS and Windows host | fleet_id | string | body | _Available in Fleet Premium_. The fleet ID for the profile. If specified, the profile is applied to only hosts that are assigned to the specified fleet. If not specified, the profile is applied to only hosts that are "Unassigned". | | labels_include_all | array | body | _Available in Fleet Premium_. Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. | -| labels_exclude_any | array | body | _Available in Fleet Premium_. Target hosts that that don’t have any label, specified by label name, in the array. | +| labels_exclude_any | array | body | _Available in Fleet Premium_. Target hosts that that don't have any label, specified by label name, in the array. | `labels_exclude_any` can be combined with either `labels_include_all` or `labels_include_any`, but `labels_include_all` and `labels_include_any` cannot be combined with each other. If none are specified, all hosts are targeted. @@ -7041,9 +7113,9 @@ solely on the response status code returned by this endpoint. ##### Example response headers ```http - Content-Length: 542 - Content-Type: application/octet-stream - Content-Disposition: attachment;filename="2023-03-31 Example profile.mobileconfig" +Content-Length: 542 +Content-Type: application/octet-stream +Content-Disposition: attachment;filename="2023-03-31 Example profile.mobileconfig" ``` ###### Example response body @@ -7069,6 +7141,59 @@ solely on the response status code returned by this endpoint. ``` +### Update configuration profile + +_Available in Fleet Premium._ + +Update an existing configuration profile. Use this endpoint to change which hosts a profile is applied to (labels/custom targets) and/or to upload a new profile file. + +`PATCH /api/v1/fleet/configuration_profiles/:profile_uuid` + +#### Parameters + +| Name | Type | In | Description | +| ------------------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------- | +| profile_uuid | string | url | **Required.** The UUID of the configuration profile to update. | +| profile | file | form | A replacement profile file (`.mobileconfig`, `.json`, or `.xml`). See requirements below. | +| labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | +| labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | +| labels_exclude_any | array | body | Target hosts that don't have any label, specified by label name, in the array. | + +Only one of `labels_include_all`, `labels_include_any`, or `labels_exclude_any` can be specified. If none are specified, the profile targets all hosts. + +##### Uploading a new profile file + +You can upload a new profile file to replace the contents of the existing profile. The new profile must match the identity of the existing profile: + +- **DDM (declarative management) profiles** (`.json`): The new profile must have the same **Identifier** as the existing profile. +- **.mobileconfig profiles**: The new profile must have the same **PayloadIdentifier** as the existing profile. + +If the new profile does not match the required identifiers, the request will be rejected. + +#### Example + +Update a configuration profile to target hosts with specific labels. + +`PATCH /api/v1/fleet/configuration_profiles/f663713f-04ee-40f0-a95a-7af428c351a9` + +##### Request body + +```json +{ + "labels_include_all": ["Label name 1", "Label name 2"] +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "profile_uuid": "f663713f-04ee-40f0-a95a-7af428c351a9" +} +``` + ### Delete configuration profile > [Delete custom macOS setting](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#delete-custom-macos-setting-configuration-profile) (`DELETE /api/v1/fleet/mdm/apple/profiles/:profile_id`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead. @@ -7118,7 +7243,7 @@ For Apple (macOS, iOS, iPadOS) profiles, Fleet will send only an `InstallProfile For Windows profiles, Fleet applies new profiles or updates when content changes, and deletes profiles no longer in the list. It does not send commands to remove configuration profiles from Windows hosts. -For declaration (DDM) profiles, hosts with new, updated, or removed profiles are marked “Pending,” and Fleet sends a [DeclarativeManagement command](https://developer.apple.com/documentation/devicemanagement/declarativemanagementcommand) to tell Apple (macOS, iOS, iPadOS) hosts to sync profiles. If declarations are current, no command is sent and the host is not marked "Pending." +For declaration (DDM) profiles, hosts with new, updated, or removed profiles are marked "Pending," and Fleet sends a [DeclarativeManagement command](https://developer.apple.com/documentation/devicemanagement/declarativemanagementcommand) to tell Apple (macOS, iOS, iPadOS) hosts to sync profiles. If declarations are current, no command is sent and the host is not marked "Pending." For requests with 100+ profiles, requests will take 5+ seconds. @@ -7142,7 +7267,7 @@ For requests with 100+ profiles, requests will take 5+ seconds. | profile | string | Base64 encoded configuration profile (.mobileconfig) or declaration (DDM) profile for Apple (macOS, iOS, iPadOS) hosts, JSON profile for Android hosts, or XML profile for Windows hosts. | | labels_include_all | array | _Available in Fleet Premium_. Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. | -| labels_exclude_any | array | _Available in Fleet Premium_. Target hosts that that don’t have any label, specified by label name, in the array. | +| labels_exclude_any | array | _Available in Fleet Premium_. Target hosts that that don't have any label, specified by label name, in the array. | | display_name | string | Required for Windows and declaration (DDM) profiles. It's not supported for .mobileconfig profiles. Instead, the profiles `PayloadDisplayName` is used. | For each `profile`, `labels_exclude_any` can be combined with either `labels_include_all` or `labels_include_any`, but `labels_include_all` and `labels_include_any` cannot be combined with each other. If neither is set, all hosts on the specified platform are targeted. @@ -7170,6 +7295,192 @@ For each `profile`, `labels_exclude_any` can be combined with either `labels_inc `Status: 204` +### Create Apple asset declaration + +Add an Apple asset declaration to reference in a configuration profile. + +> You need to send a request of type `multipart/form-data`. + +> This endpoint accepts a maximum request body size of 1.5MiB. + +`POST /api/v1/fleet/assets` + +#### Parameters + +| Name | Type | In | Description | +| ------------------------- | -------- | ---- | ------------------------------------------------------------------------------------------------------------- | +| asset | file | body | **Required.** The JSON asset declaration. The "Type" must be a valid Apple asset declaration type (e.g., "com.apple.asset.data"), and an "Identifier" must be defined. See [Apple's documentation](https://developer.apple.com/documentation/devicemanagement) for type-specific payload requirements. | +| fleet_id | string | body | _Available in Fleet Premium_. The fleet ID for the asset. If specified, the asset is available to only the configuration profile(s) that are assigned to the specified fleet. If not specified, the profile is applied to only hosts that are "Unassigned". | + +#### Example + +`POST /api/v1/fleet/assets` + +##### Request body + +``` +fleet_id="1" +asset="my-asset.json" +``` + +##### Example asset file (my-asset.json) +``` +{ + "Type": "com.apple.asset.data", + "Identifier": "EB13EE2B-5D63-4EBA-810F-5B81D07F5017", + "ServerToken": "E180CA9A-F089-4FA3-BBDF-94CC159C4AE8", + "Payload": { + "Reference": { + "DataURL": "https://example.com/asset-data/data/test.txt", + "ContentType": "text/plain" + }, + "Authentication": { + "Type": "MDM" + } + } +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "asset_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24" +} +``` + +### List Apple asset declarations + +Get a list of the Apple asset declarations in Fleet. + +For Fleet Premium, the list can optionally be filtered by fleet ID. If no fleet ID is specified, fleet assets are excluded from the results (i.e., only assets that are associated with "Unassigned" are listed). + +`GET /api/v1/fleet/assets` + +#### Parameters + +| Name | Type | In | Description | +| ------------------------- | ------ | ----- | ------------------------------------------------------------------------- | +| fleet_id | string | query | _Available in Fleet Premium_. The fleet id to filter profiles. | + +#### Example + +List all assets available for the "Unassigned" fleet. + +`GET /api/v1/fleet/assets` + +##### Default response + +`Status: 200` + +```json +{ + "assets": [ + { + "asset_uuid": "39f6cbbc-fe7b-4adc-b7a9-542d1af89c63", + "asset": "my-asset.json", + "identifier": "com.example.asset1", + "created_at": "2023-03-31T00:00:00Z", + "updated_at": "2023-03-31T00:00:00Z", + "checksum": "dGVzdAo=", + }, + { + "asset_uuid": "39f6cbbc-fe7b-4adc-b7a9-542d1af89c63", + "asset": "my-asset2.json", + "identifier": "com.example.asset2", + "created_at": "2023-03-31T00:00:00Z", + "updated_at": "2023-03-31T00:00:00Z", + "checksum": "dGVzdAo=", + }, + ], +} +``` + +### Get or download Apple asset declaration + +Get or download the original Apple asset declaration file that was uploaded to Fleet. + +`GET /api/v1/fleet/assets/:asset_uuid` + +#### Parameters + +| Name | Type | In | Description | +| ------------------------- | ------- | ----- | ------------------------------------------------------- | +| asset_uuid | string | url | **Required** The UUID of the asset to get. | +| alt | string | query | If specified and set to "media", downloads the asset. | + +#### Example (get asset metadata) + +`GET /api/v1/fleet/assets/954ec5ea-a334-4825-87b3-937e7e381f24` + +##### Default response + +`Status: 200` + +```json +{ + "asset_uuid": "954ec5ea-a334-4825-87b3-937e7e381f24", + "fleet_id": 0, + "asset": "my-asset.json", + "identifier": "com.example.asset1", + "created_at": "2023-03-31T00:00:00Z", + "updated_at": "2023-03-31T00:00:00Z", + "checksum": "dGVzdAo=" +} +``` + +#### Example (download an asset) + +`GET /api/v1/fleet/assets/954ec5ea-a334-4825-87b3-937e7e381f24?alt=media` + +##### Default response + +`Status: 200` + +**Note** To confirm success, it is important for clients to match content length with the response header (this is done automatically by most clients, including the browser) rather than relying solely on the response status code returned by this endpoint. + +##### Example response headers + +```http +Content-Length: 542 +Content-Type: application/octet-stream +Content-Disposition: attachment;filename="2023-03-31 my-asset.json" +``` + +###### Example response body + +```json +{ + "Type": "com.apple.asset.data", + "Identifier": "com.example.asset1", + "ServerURL": "https://example.com/assets/my-asset.json" +} +``` + +### Delete Apple asset declaration + +Deletes an Apple asset declaration. + +> If an asset is referenced in a configuration profile, you must delete the configuration profile first before being able to remove the asset. + +`DELETE /api/v1/fleet/assets/:asset_uuid` + +#### Parameters + +| Name | Type | In | Description | +| ------------------------- | ------- | ----- | ------------------------------------------------- | +| asset_uuid | string | url | **Required** The UUID of the asset to delete. | + +#### Example + +`DELETE /api/v1/fleet/assets/954ec5ea-a334-4825-87b3-937e7e381f24` + +##### Default response + +`Status: 204` + ### Resend configuration profile by Fleet Desktop token Resends a configuration profile for the specified host. Currently, macOS, iOS, iPadOS configuration profiles (.mobileconfig) are supported, as well as Windows (.xml) configuration profiles. @@ -7194,21 +7505,20 @@ Resends a configuration profile for the specified host. Currently, macOS, iOS, i ### Batch-resend configuration profile - `POST /api/v1/fleet/configuration_profiles/resend/batch` #### Parameters -| Name | Type | In | Description | -| ------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| profile_uuid | integer | body | **Required**. The UUID of the existing configuration profile you'd like to resend.| -| filters | object | body | **Required**. See [filters](#filters) | +| Name | Type | In | Description | +| ------------- | ------- | ---- | -------------------------------------------------------------------------------------- | +| profile_uuid | integer | body | **Required**. The UUID of the existing configuration profile you'd like to resend. | +| filters | object | body | **Required**. See [filters](#filters) | ##### Filters -| Name | Type | Description | +| Name | Type | Description | | -----------------------| ------- | ----------------------------------------------------------------------------------- | -| profile_status | string | Profile status. Currently, `"failed"` is supported. | +| profile_status | string | Profile status. Currently, `"failed"` is supported. | #### Example @@ -7290,6 +7600,68 @@ The summary can optionally be filtered by fleet ID. } ``` +### Update host name template + +_Available in Fleet Premium_ + +Sets a naming convention for all macOS, iOS, and iPadOS hosts in a fleet (or "Unassigned"). Fleet resolves the template per host, renames the host on the device via an Apple MDM command, and updates the host's name in Fleet. + +Sending an empty `name_template` clears the template. Clearing the template stops enforcement but doesn't rename any host. + +`POST /api/v1/fleet/host_name_template` + +#### Parameters + +| Name | Type | In | Description | +| ------------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | +| fleet_id | integer | body | The fleet ID to apply the host name template to. The template is applied to "Unassigned" hosts if the value is absent or `0`. | +| name_template | string | body | The host name template. Send an empty string to clear the template. | + +The template supports the built-in host identity variables (`$FLEET_VAR_HOST_HARDWARE_SERIAL`, `$FLEET_VAR_HOST_UUID`, `$FLEET_VAR_HOST_PLATFORM`), the IdP end-user variables (`$FLEET_VAR_HOST_END_USER_IDP_USERNAME`, `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART`, `$FLEET_VAR_HOST_END_USER_IDP_GROUPS`, `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT`, `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME`), and custom (`$FLEET_SECRET_*`) variables; each also works in its `${...}` form. Certificate authority variables (SCEP challenges and proxy URLs, DigiCert data, certificate renewal IDs, the Platform SSO device registration token) and the deprecated `$FLEET_VAR_HOST_END_USER_EMAIL_IDP` variable aren't supported and return a `422` — they resolve to secrets or certificate data that are meaningless and unsafe as a host name. + +If a host is missing the IdP data a variable needs, that host's rename fails. A referenced custom variable must already exist (an undefined one returns a `422`); custom variables are global, and a custom variable's value becomes the host's (publicly visible) name, so it isn't kept hidden as it is in scripts and configuration profiles. + +#### Example + +`POST /api/v1/fleet/host_name_template` + +##### Request body + +```json +{ + "fleet_id": 5, + "name_template": "iPad $FLEET_VAR_HOST_HARDWARE_SERIAL" +} +``` + +##### Default response + +`204` + +### Resend host name template + +_Available in Fleet Premium_ + +Resends the host name template MDM command to a host whose host name status is "failed" or "verified". The host's status returns to "pending" (shown as "Enforcing" in the UI) until the device applies the name again. + +`POST /api/v1/fleet/hosts/:id/name_template/resend` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | ------------------------------------------------------ | +| id | integer | path | **Required.** The ID of the host to resend to. | + +#### Example + +`POST /api/v1/fleet/hosts/42/name_template/resend` + +##### Default response + +`Status: 202` + +If the host has no host name template enforced, the response is `404`. If the host name status is "pending" or "verifying", the response is `409`. + ### Get OS settings (configuration profiles) status > [Get macOS settings statistics](https://github.com/fleetdm/fleet/blob/fleet-v4.40.0/docs/REST%20API/rest-api.md#get-macos-settings-statistics) (`GET /api/v1/fleet/mdm/apple/profiles/summary`) API endpoint is deprecated as of Fleet 4.41. It is maintained for backwards compatibility. Please use the below API endpoint instead. @@ -7548,10 +7920,10 @@ To enroll macOS hosts, turn on MDM features, and add [human-device mapping](http ##### Example response headers ```http - Content-Length: 542 - Content-Type: application/x-apple-aspen-config; charset=utf-8 - Content-Disposition: attachment;filename="fleet-mdm-enrollment-profile.mobileconfig" - X-Content-Type-Options: nosniff +Content-Length: 542 +Content-Type: application/x-apple-aspen-config; charset=utf-8 +Content-Disposition: attachment;filename="fleet-mdm-enrollment-profile.mobileconfig" +X-Content-Type-Options: nosniff ``` ###### Example response body @@ -7796,7 +8168,7 @@ _Available in Fleet Premium_ | require_all_software_windows | boolean | body | If set to `true`, setup will be canceled on Windows hosts if any software installs fail (the host is blocked at the Windows Enrollment Status Page until the device is reset). If `false`, the Enrollment Status Page lists the failed software and the end user can continue to the desktop and install it later via self-service. | | enable_release_device_manually | boolean | body | When enabled, you're responsible for sending the [`DeviceConfigured` command](https://developer.apple.com/documentation/devicemanagement/device-configured-command). End users will be stuck in Setup Assistant until this command is sent. | | manual_agent_install | boolean | body | If set to `true` Fleet's agent (fleetd) won't be installed as part of automatic enrollment (ADE) on macOS hosts. (Default: `false`) | -| enable_managed_local_account | boolean | body | During the Setup experience, a managed local account will be created on macOS hosts if set to true. | +| enable_managed_local_account | boolean | body | _Available in Fleet Premium._ During the Setup experience, a managed local account will be created on macOS hosts if set to true. | | end_user_local_account_type | string | body | Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | #### Example @@ -8155,16 +8527,17 @@ Delete a script that will automatically run during macOS setup. _Available in Fleet Premium_ -Edit managed local account enforcement settings for eligible macOS hosts. +Edit managed local account enforcement settings for eligible hosts. `POST /api/v1/fleet/managed_local_account` #### Parameters -| Name | Type | In | Description | -| ---------------------------- | ------ | ---- | -------------------------------------------------------------------------------------| -| fleet_id | integer | body | The fleet ID to apply the settings to. If omitted, settings apply to unassigned hosts.| -| enable_managed_local_account | boolean | body | Whether to enforce creating managed local accounts on eligible hosts. | +| Name | Type | In | Description | +| ------------------------------------ | ------ | ---- | -------------------------------------------------------------------------------------| +| fleet_id | integer | body | The fleet ID to apply the settings to. If omitted, settings apply to unassigned hosts.| +| enable_managed_local_account | boolean | body | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on eligible hosts if set to true. | +| end_user_local_account_type | string | body | Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | #### Example @@ -8177,7 +8550,8 @@ Edit managed local account enforcement settings for eligible macOS hosts. ```json { "fleet_id": 3, - "enable_managed_local_account": true + "enable_managed_local_account": true, + "end_user_local_account_type": "admin" } ``` @@ -8450,37 +8824,38 @@ None. "mdm_server_url": "https://example.com/mdm/apple/mdm", "renew_date": "2023-11-29T00:00:00Z", "terms_expired": false, + "token_invalid": false, "macos_team": { "name": "💻 Workstations", - "team_id": 1 + "id": 1 }, "macos_fleet": { "name": "💻 Workstations", - "fleet_id": 1 + "id": 1 }, "ios_team": { "name": "📱🏢 Company-owned iPhones", - "team_id": 2 + "id": 2 }, "ios_fleet": { "name": "📱🏢 Company-owned iPhones", - "fleet_id": 2 + "id": 2 }, "ipados_team": { "name": "🔳🏢 Company-owned iPads", - "team_id": 3 + "id": 3 }, "ipados_fleet": { "name": "🔳🏢 Company-owned iPads", - "fleet_id": 3 + "id": 3 }, "byod_team": { "name": "📱 BYOD iPhones", - "team_id": 4 + "id": 4 }, "byod_fleet": { "name": "📱 BYOD iPhones", - "fleet_id": 4 + "id": 4 } } ] @@ -9431,7 +9806,7 @@ A passing host answers "yes" to a policy if the host returns results for a polic A failing host answers "no" to a policy if the host does not return results for a policy's query. -For example, a policy might ask “Is Gatekeeper enabled on macOS devices?“ This policy's osquery query might look like the following: `SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;` +For example, a policy might ask "Is Gatekeeper enabled on macOS devices?" This policy's osquery query might look like the following: `SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;` ### List policies @@ -11899,6 +12274,24 @@ Get a list of all software. "vulnerabilities": null } ], + "packages": [ + { + "name": "Slack-4.50.128-macOS.pkg", + "automatic_install_policies": null, + "version": "4.50.128", + "platform": "darwin", + "self_service": false, + "package_url": "" + }, + { + "name": "Slack-4.51.133-macOS.pkg", + "automatic_install_policies": null, + "version": "4.51.133", + "platform": "darwin", + "self_service": true, + "package_url": "" + } + ], "software_package": { "name": "Slack-4.50.128-macOS.pkg", "automatic_install_policies": null, @@ -11930,6 +12323,7 @@ Get a list of all software. "vulnerabilities": null } ], + "packages": null, "software_package": null, "app_store_app": null, "bundle_identifier": "com.raycast.macos", @@ -11945,6 +12339,8 @@ Get a list of all software. `browser` and `extension_for` fields are included when set and when empty. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. +A software title can have more than one package. The `packages` array lists all packages added for the title. `software_package` is kept for backwards compatibility and contains the oldest (first added) package; it's `null` when no package is available. + ### List software versions Get a list of all software versions. @@ -12150,6 +12546,79 @@ Returns information about the specified software. By default, `versions` are sor } ], "counts_updated_at": "2026-06-04T17:23:45Z", + "packages": [ + { + "team_id": 310, + "title_id": 2792, + "name": "Slack-4.50.128-macOS.pkg", + "icon_url": null, + "version": "4.50.128", + "platform": "darwin", + "uploaded_at": "2026-06-04T17:29:09.155424Z", + "installer_id": 36817, + "install_script": "#!/bin/sh\n\ninstaller -pkg \"$INSTALLER_PATH\" -target /\n", + "pre_install_query": "", + "post_install_script": "", + "uninstall_script": "#!/bin/sh\n\n# Fleet extracts and saves package IDs.\npkg_ids=(\n 'com.tinyspeck.slackmacgap'\n)\n", + "hash_sha256": "f7e4cba7676dacb03ac4cdbe5a99cc1d80ef751c484a13c6a7cf6a93de4a494e", + "status": { + "installed": 0, + "pending_install": 1, + "failed_install": 0, + "pending_uninstall": 0, + "failed_uninstall": 0 + }, + "self_service": false, + "url": "", + "fleet_maintained_app_id": null, + "automatic_install_policies": null, + "labels_include_any": null, + "labels_exclude_any": null, + "labels_include_all": null, + "categories": null, + "display_name": "", + "patch_policy": null, + "fleet_id": 310 + }, + { + "team_id": 310, + "title_id": 2792, + "name": "Slack-4.51.133-macOS.pkg", + "icon_url": null, + "version": "4.51.133", + "platform": "darwin", + "uploaded_at": "2026-06-10T09:14:51.482217Z", + "installer_id": 36901, + "install_script": "#!/bin/sh\n\ninstaller -pkg \"$INSTALLER_PATH\" -target /\n", + "pre_install_query": "", + "post_install_script": "", + "uninstall_script": "#!/bin/sh\n\n# Fleet extracts and saves package IDs.\npkg_ids=(\n 'com.tinyspeck.slackmacgap'\n)\n", + "hash_sha256": "a1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f70819203a4b5c6d7e8f9", + "status": { + "installed": 0, + "pending_install": 0, + "failed_install": 0, + "pending_uninstall": 0, + "failed_uninstall": 0 + }, + "self_service": true, + "url": "", + "fleet_maintained_app_id": null, + "automatic_install_policies": null, + "labels_include_any": null, + "labels_exclude_any": null, + "labels_include_all": [ + { + "id": 12, + "name": "IT test team" + } + ], + "categories": null, + "display_name": "", + "patch_policy": null, + "fleet_id": 310 + } + ], "software_package": { "team_id": 310, "title_id": 2792, @@ -12192,30 +12661,37 @@ Returns information about the specified software. By default, `versions` are sor `browser` and `extension_for` fields are included when set and when empty, at the same level as `source`. `extension_for` will show the browser or Visual Studio Code fork associated with the extension, allowing for differentiation between e.g. an extension installed on Visual Studio Code and one installed on Cursor. `browser` is deprecated, and only shows this information for browser plugins. -For Fleet-maintained apps, the `software_package` object includes two additional fields: +A software title can have more than one package. The `packages` array lists all packages added for the title, including per-package `self_service`, `categories`, and labels (`labels_include_any`, `labels_exclude_any`, `labels_include_all`). `software_package` is kept for backwards compatibility and contains the oldest (first added) package. + +> Install, pending, and failed counts in `packages.status` are combined across policy automations, setup experience, and manual installs. + +For Fleet-maintained apps, software package objects include two additional fields: - `pinned_version`: The version the app is pinned to — a specific version (e.g. `"149.0.7827.54"`) or a caret major-version constraint (e.g. `"^147"`). Omitted when the app automatically updates to the latest version. - `fleet_maintained_versions`: The versions Fleet has cached and that are available to pin or roll back to. Each entry includes `id`, `version`, and `uploaded_at`. For example: + ```json -"software_package": { - "name": "GoogleChrome.pkg", - "version": "149.0.7827.54", - "platform": "darwin", - "fleet_maintained_app_id": 12, - "pinned_version": "149.0.7827.54", - "fleet_maintained_versions": [ - { - "id": 36818, - "version": "149.0.7827.54", - "uploaded_at": "2026-06-04T17:47:23Z" - }, - { - "id": 36817, - "version": "148.0.7794.0", - "uploaded_at": "2026-05-21T11:02:55Z" - } - ] -} +"packages": [ + { + "name": "GoogleChrome.pkg", + "version": "149.0.7827.54", + "platform": "darwin", + "fleet_maintained_app_id": 12, + "pinned_version": "149.0.7827.54", + "fleet_maintained_versions": [ + { + "id": 36818, + "version": "149.0.7827.54", + "uploaded_at": "2026-06-04T17:47:23Z" + }, + { + "id": 36817, + "version": "148.0.7794.0", + "uploaded_at": "2026-05-21T11:02:55Z" + } + ] + } +] ``` For in-house iOS apps, the `software_package` field is populated with package information. @@ -12422,7 +12898,7 @@ Operating systems other than Windows, macOS, and Linux do not report vulnerabili _Available in Fleet Premium._ -Add a package (.pkg, .msi, .exe, .deb, .rpm, .tar.gz, .ipa) to install on Apple (macOS/iOS/iPadOS), Windows, or Linux hosts. Also supports adding a custom script (.sh, .ps1) to run on Windows or Linux hosts. +Add a package (.pkg, .msi, .exe, .deb, .rpm, .tar.gz, .ipa) to install on Apple (macOS/iOS/iPadOS), Windows, or Linux hosts. Also supports adding a custom script (.sh and .py for macOS and Linux, .ps1 for Windows). > You need to send a request of type `multipart/form-data`. @@ -12434,9 +12910,9 @@ Add a package (.pkg, .msi, .exe, .deb, .rpm, .tar.gz, .ipa) to install on Apple | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | -| software | file | body | **Required**. Installer package file or custom script file. Supported packages are `.pkg`, `.msi`, `.exe`, `.deb`, `.rpm`, `.tar.gz`, `.ipa`, `.sh`, and `.ps1`. | +| software | file | body | **Required**. Installer package file or custom script file. Supported packages are `.pkg`, `.msi`, `.exe`, `.deb`, `.rpm`, `.tar.gz`, `.ipa`, `.sh`, `.py`, and `.ps1`. | | fleet_id | integer | body | The fleet ID. Adds a software package to the specified fleet. If not specified, it will add the software for "Unassigned" hosts. | -| install_script | string | body | Script that Fleet runs to install software. If not specified Fleet runs the [default install script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type if one exists. Required for `.tar.gz` and `.exe` (no default script). Not supported for `.sh` and `.ps1`. | +| install_script | string | body | Script that Fleet runs to install software. If not specified Fleet runs the [default install script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type if one exists. Required for `.tar.gz` and `.exe` (no default script). Not supported for `.sh`, `.py`, and `.ps1`. | | uninstall_script | string | body | Script that Fleet runs to uninstall software. If not specified Fleet runs the [default uninstall script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type if one exists. Required for `.tar.gz` and `.exe` (no default script). | | pre_install_query | string | body | Query that is pre-install condition. If the query doesn't return any result, Fleet won't proceed to install. | | post_install_script | string | body | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. | @@ -12444,7 +12920,7 @@ Add a package (.pkg, .msi, .exe, .deb, .rpm, .tar.gz, .ipa) to install on Apple | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | body | Target hosts that don't have any label, specified by label name, in the array. | -| automatic_install | boolean | body | Specifies whether to create a policy that triggers a software install only on hosts missing the software. Not supported for iOS, iPadOS, Android, or for `.sh` and `.ps1`. | +| automatic_install | boolean | body | Specifies whether to create a policy that triggers a software install only on hosts missing the software. Not supported for iOS, iPadOS, Android, or for `.sh`, `.py`, and `.ps1`. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. @@ -12521,11 +12997,11 @@ Update a package to install on macOS, Windows, Linux, iOS, or iPadOS hosts. | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | | id | integer | path | ID of the software title being updated. | -| software | file | body | Installer package file or custom script file. Supported packages are `.pkg`, `.msi`, `.exe`, `.deb`, `.rpm`, `.tar.gz`, `.ipa`, `.sh`, and `.ps1`. | +| software | file | body | Installer package file or custom script file. Supported packages are `.pkg`, `.msi`, `.exe`, `.deb`, `.rpm`, `.tar.gz`, `.ipa`, `.sh`, `.py`, and `.ps1`. | | fleet_id | integer | body | **Required**. The fleet ID. Updates a software package in the specified fleet. | | display_name | string | body | Optional override for the default `name`. | | categories | array | body | Zero or more [self-service category](#list-self-service-categories) names defined on the fleet, used to group self-service software on your end users' **Fleet Desktop > My device** page. Each value must match a category that exists on the fleet. Software with no categories will still be shown under **All**. | -| install_script | string | body | Command that Fleet runs to install software. If not specified Fleet runs the [default install command](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type. Not supported for `.sh` and `.ps1`. | +| install_script | string | body | Command that Fleet runs to install software. If not specified Fleet runs the [default install command](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) for each package type. Not supported for `.sh`, `.py`, and `.ps1`. | | pre_install_query | string | body | Query that is pre-install condition. If the query doesn't return any result, the package will not be installed. | | post_install_script | string | body | The contents of the script to run after install. If the specified script fails (exit code non-zero) software install will be marked as failed and rolled back. | | self_service | boolean | body | Whether this is optional self-service software that can be installed by the end user. | @@ -13223,7 +13699,7 @@ To get the results of an Apple App Store app install, use the [List MDM commands "host_id": 123, "host_display_name": "Marko's MacBook Pro", "status": "failed_install", - "output": "Installing software...\nError: The operation can’t be completed because the item “Falcon” is in use.", + "output": "Installing software...\nError: The operation can’t be completed because the item "Falcon" is in use.", "pre_install_query_output": "Query returned result\nSuccess", "post_install_script_output": "Running script...\nExit code: 1 (Failed)\nRolling back software install...\nSuccess" } @@ -13905,8 +14381,23 @@ _Available in Fleet Premium_ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] + }, + { + "path": "path/to/declaration.json", + "labels": ["Label 1", "Label 2"] + }, + { + "path": "path/to/assets/asset.json" } - ] + ], + "assets": [ + { + "path": "path/to/assets/asset.json" + } + ], + "managed_local_account_settings": { + "enabled": true + }, }, "windows_settings": { "custom_settings": [ @@ -13920,7 +14411,10 @@ _Available in Fleet Premium_ "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } - ] + ], + "managed_local_account_settings": { + "enabled": true + }, }, "macos_setup": { "bootstrap_package": "", @@ -13932,6 +14426,8 @@ _Available in Fleet Premium_ "setup_experience": { "bootstrap_package": "", "enable_end_user_authentication": false, + "enable_managed_local_account": false, + "end_user_local_account_type": "admin", "apple_setup_assistant": "path/to/config.json", "enable_release_device_manually": false, "manual_agent_install": false @@ -14260,6 +14756,7 @@ Returned when the requested name only differs from another fleet's name by lette | ipados_updates | object | See [`mdm.ipados_updates`](#mdm-ipados-updates2). | | windows_updates | object | See [`mdm.windows_updates`](#mdm-windows-updates2). | | macos_settings | object | See [`mdm.macos_settings`](#mdm-macos-settings2). | +| apple_settings | object | See [`mdm.apple_settings`](#mdm-apple-settings2). | | windows_settings | object | See [`mdm.windows_settings`](#mdm-windows-settings2). | | setup_experience | object | See [`mdm.setup_experience`](#mdm-setup-experience2). | @@ -14321,32 +14818,47 @@ Returned when the requested name only differs from another fleet's name by lette | Name | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | +
+ + +##### mdm.apple_settings + +`mdm.apple_settings` is an object with the following structure: + +| Name | Type | Description | +| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add macOS configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | +| managed_local_account_settings | object | Settings for the managed local account. | +| managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). | +| end_user_local_account_type | string | The end user account type. Requires `managed_local_account_settings.enabled` to be `true`. Options: `"admin"`, `"standard"`, `"none"` (default: `"admin"`). |
+ ##### mdm.windows_settings `mdm.windows_settings` is an object with the following structure: -| Name | Type | Description | -| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add Windows configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | - +| Name | Type | Description | +| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| custom_settings | array | Only intended to be used by [Fleet's YAML](https://fleetdm.com/docs/configuration/yaml-files). To add Windows configuration profiles using Fleet's API, use the [Create configuration profile](#create-configuration-profile) endpoint instead. | +| managed_local_account_settings | object | Settings for the managed local account. | +| managed_local_account_settings.enabled | boolean | Whether to create the managed local account (default: `false`). |
+ ##### mdm.setup_experience `mdm.setup_experience` is an object with the following structure: -| Name | Type | Description | -| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| enable_end_user_authentication | boolean | If set to true, IdP authentication will be required during automatic MDM enrollment of new macOS hosts. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#require-idp-authentication). -| lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) | -| enable_managed_local_account | boolean | Whether to enforce creating managed local accounts on eligible hosts. | - -
+| Name | Type | Description | +| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| enable_end_user_authentication | boolean | If set to true, IdP authentication will be required during automatic MDM enrollment of new macOS hosts. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#require-idp-authentication). +| lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) | +| enable_managed_local_account | boolean | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on eligible hosts if set to true. | +| end_user_local_account_type | string | body | Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | ##### Example request body @@ -14379,7 +14891,18 @@ Returned when the requested name only differs from another fleet's name by lette "path": "path/to/profile2.json", "labels": ["Label 3", "Label 4"] }, - ] + { + "path": "path/to/assets/asset.json" + }, + ], + "assets": [ + { + "path": "path/to/assets/asset.json" + } + ], + "managed_local_account_settings": { + "enabled": true + } }, "windows_settings": { "custom_settings": [ @@ -14393,7 +14916,10 @@ Returned when the requested name only differs from another fleet's name by lette "path": "path/to/profile3.xml", "labels": ["Label 1", "Label 2"] } - ] + ], + "managed_local_account_settings": { + "enabled": true + } }, "setup_experience": { "enable_end_user_authentication": false @@ -14548,8 +15074,23 @@ _Available in Fleet Premium_ { "path": "path/to/profile1.mobileconfig", "labels": ["Label 1", "Label 2"] + }, + { + "path": "path/to/declaration.json", + "labels": ["Label 1", "Label 2"] + }, + { + "path": "path/to/assets/asset.json" } - ] + ], + "assets": [ + { + "path": "path/to/assets/asset.json" + } + ], + "managed_local_account_settings": { + "enabled": true + } }, "windows_settings": { "custom_settings": [ @@ -14563,7 +15104,10 @@ _Available in Fleet Premium_ "path": "path/to/profile2.xml", "labels": ["Label 3", "Label 4"] } - ] + ], + "managed_local_account_settings": { + "enabled": true + } }, "macos_setup": { "bootstrap_package": "", @@ -16011,7 +16555,7 @@ At least one field is required. Ratios outside the `[0, 1]` range are rejected. ### List custom variables -Lists all custom variables that can be used in scripts and profiles prefixed with `$FLEET_SECRET_`. +Lists all custom variables that can be used in scripts, configuration profiles, and host name templates prefixed with `$FLEET_SECRET_`. `GET /api/v1/fleet/custom_variables` @@ -16055,7 +16599,7 @@ Lists all custom variables that can be used in scripts and profiles prefixed wit ### Create custom variable -Creates a custom variable that can be used in scripts and profiles prefixed with `$FLEET_SECRET_`. +Creates a custom variable that can be used in scripts, configuration profiles, and host name templates prefixed with `$FLEET_SECRET_`. `POST /api/v1/fleet/custom_variables` diff --git a/docs/solutions/macos/configuration-profiles/fleet-sso-extension-example.mobileconfig b/docs/solutions/macos/configuration-profiles/fleet-sso-extension-example.mobileconfig new file mode 100644 index 0000000000..a5dc573e4b --- /dev/null +++ b/docs/solutions/macos/configuration-profiles/fleet-sso-extension-example.mobileconfig @@ -0,0 +1,93 @@ + + + + + PayloadContent + + + ExtensionData + + BaseURL + https://fleet.example.com + + ExtensionIdentifier + com.fleetdm.fleet-desktop.pssoextension + PayloadDisplayName + Fleet Extensible Single Sign-On + PayloadIdentifier + com.apple.extensiblesso.AF68D4CF-1250-4FF4-AFFB-1176DB539C49 + PayloadType + com.apple.extensiblesso + PayloadUUID + AF68D4CF-1250-4FF4-AFFB-1176DB539C49 + PayloadVersion + 1 + PlatformSSO + + AuthenticationMethod + Password + UseSharedDeviceKeys + + EnableRegistrationDuringSetup + + TokenToUserMapping + + AccountName + accountName + FullName + name + + + RegistrationToken + $FLEET_VAR_PSSO_DEVICE_REGISTRATION_TOKEN + ScreenLockedBehavior + DoNotHandle + TeamIdentifier + 8VBZ3948LU + Type + Redirect + URLs + + https://fleet.example.com + + + + PayloadType + com.apple.associated-domains + PayloadIdentifier + com.apple.associated-domains.4D68D4CF-1250-4FF4-AFFB-1176DB539C49 + PayloadUUID + 4D68D4CF-1250-4FF4-AFFB-1176DB539C49 + Configuration + + + ApplicationIdentifier + 8VBZ3948LU.com.fleetdm.fleet-desktop + AssociatedDomains + + authsrv:fleet.example.com + + + + ApplicationIdentifier + 8VBZ3948LU.com.fleetdm.fleet-desktop.pssoextension + AssociatedDomains + + authsrv:fleet.example.com + + + + + + PayloadDisplayName + Fleet Platform SSO + PayloadIdentifier + com.fleetdm.platformsso.fleet.A72B07D0-2E08-45CE-9423-1FCAFFAEC390 + PayloadType + Configuration + PayloadUUID + A72B07D0-2E08-45CE-9423-1FCAFFAEC390 + PayloadVersion + 1 + + diff --git a/handbook/company/pricing-features-table.yml b/handbook/company/pricing-features-table.yml index 6264f9315c..3573b4232d 100644 --- a/handbook/company/pricing-features-table.yml +++ b/handbook/company/pricing-features-table.yml @@ -337,6 +337,25 @@ jamfProHasFeature: yes jamfProtectHasFeature: yes # +# ╔═╗╔═╗╔═╗╔═╗╦ ╦╔╗╔╔╦╗ ╔═╗╦═╗╔═╗╔═╗╔╦╗╦╔═╗╔╗╔ ╔═╗╔═╗╔═╗╔═╗╦ ╦╔═╗╦═╗╔╦╗ ╔═╗╦ ╦╔╗╔╔═╗ +# ╠═╣║ ║ ║ ║║ ║║║║ ║ ║ ╠╦╝║╣ ╠═╣ ║ ║║ ║║║║ & ╠═╝╠═╣╚═╗╚═╗║║║║ ║╠╦╝ ║║ ╚═╗╚╦╝║║║║ +# ╩ ╩╚═╝╚═╝╚═╝╚═╝╝╚╝ ╩ ╚═╝╩╚═╚═╝╩ ╩ ╩ ╩╚═╝╝╚╝ ╩ ╩ ╩╚═╝╚═╝╚╩╝╚═╝╩╚══╩╝ ╚═╝ ╩ ╝╚╝╚═╝ +- industryName: Account creation & password sync + description: Automatically create macOS local accounts and sync passwords with any IdP that supports OAuth ROPG (e.g. Okta), so end users have one password for their Mac and third-party tools. + documentationUrl: https://fleetdm.com/docs/deploying-apple-account-provisioning-with-fleet + productCategories: [Device management] + pricingTableCategories: [Device management] + usualDepartment: IT + tier: Premium + jamfProHasFeature: no + jamfProtectHasFeature: no + isExperimental: yes + waysToUse: + - description: Create macOS local accounts during zero-touch setup using IdP credentials. + moreInfoUrl: https://github.com/fleetdm/fleet/issues/45524 + - description: Sync macOS local account passwords with IdP credentials from any IdP that supports OAuth ROPG. + moreInfoUrl: https://github.com/fleetdm/fleet/issues/45524 +# # ╦ ╦╦ ╦╔╦╗╔═╗╔╗╔ ╔═╗╔╗╔╔╦╗╔═╗╔═╗╦╔╗╔╔╦╗ ╔╦╗╔═╗╔═╗╔═╗╦╔╗╔╔═╗ # ╠═╣║ ║║║║╠═╣║║║───║╣ ║║║ ║║╠═╝║ ║║║║║ ║ ║║║╠═╣╠═╝╠═╝║║║║║ ╦ # ╩ ╩╚═╝╩ ╩╩ ╩╝╚╝ ╚═╝╝╚╝═╩╝╩ ╚═╝╩╝╚╝ ╩ ╩ ╩╩ ╩╩ ╩ ╩╝╚╝╚═╝ diff --git a/server/api_endpoints/api_endpoints.yml b/server/api_endpoints/api_endpoints.yml index 229f42df92..d6b4ff50fd 100644 --- a/server/api_endpoints/api_endpoints.yml +++ b/server/api_endpoints/api_endpoints.yml @@ -1,6 +1,18 @@ - method: "GET" path: "/api/v1/fleet/activities" display_name: "List activities" +- method: "POST" + path: "/api/v1/fleet/assets" + display_name: "Create Apple asset declaration" +- method: "GET" + path: "/api/v1/fleet/assets" + display_name: "List Apple asset declarations" +- method: "DELETE" + path: "/api/v1/fleet/assets/:asset_uuid" + display_name: "Delete Apple asset declaration" +- method: "GET" + path: "/api/v1/fleet/assets/:asset_uuid" + display_name: "Get or download Apple asset declaration" - method: "POST" path: "/api/v1/fleet/certificate_authorities" display_name: "Connect certificate authority (CA)"