mirror of
https://github.com/fleetdm/fleet
synced 2026-04-21 13:37:30 +00:00
Preview of v4.83.0 doc changes (#39805)
This PR will remain in draft as a preview of upcoming documentation changes for 4.83.0 --------- Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com> Co-authored-by: Jordan Montgomery <elijah.jordan.montgomery@gmail.com> Co-authored-by: melpike <79950145+melpike@users.noreply.github.com> Co-authored-by: kiloconnect[bot] <240665456+kiloconnect[bot]@users.noreply.github.com> Co-authored-by: Victor Lyuboslavsky <2685025+getvictor@users.noreply.github.com> Co-authored-by: Scott Gress <scottmgress@gmail.com> Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Co-authored-by: Jonathan Katz <44128041+jkatz01@users.noreply.github.com> Co-authored-by: kilo-code-bot[bot] <240665456+kilo-code-bot[bot]@users.noreply.github.com> Co-authored-by: Carlo <1778532+cdcme@users.noreply.github.com>
This commit is contained in:
Rachael Shaw
GitHub
parent
daa3acd97c
commit
1ad8b03337
17 changed files with 632 additions and 66 deletions
|
|
@ -9,7 +9,7 @@ Fleet will automatically renew certificates on Apple (macOS, iOS, iPadOS), Windo
|
|||
Currently, these are supported platforms for each certificate authority:
|
||||
- **Okta**: macOS, iOS, and iPadOS
|
||||
- **DigiCert**: macOS, iOS, and iPadOS
|
||||
- **Microsoft NDES**: macOS, iOS, iPadOS and Windows (coming soon)
|
||||
- **Microsoft NDES**: macOS, iOS, iPadOS and Windows
|
||||
- **Smallstep**: macOS, iOS, and iPadOS
|
||||
- **Hydrant**: Linux
|
||||
- **Custom SCEP server**: macOS, Windows, iOS, iPadOS, and Android
|
||||
|
|
@ -148,7 +148,69 @@ When Fleet delivers the profile to your hosts, Fleet will replace the variables.
|
|||
|
||||
The following steps show how to deploy [Microsoft NDES](https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/network-device-enrollment-service-overview) certificates.
|
||||
|
||||
### Step 1: Connect Fleet to NDES
|
||||
### Step 1: Prerequisites for Windows hosts
|
||||
|
||||
If you’re deploying NDES certificates to Windows hosts, complete the following prerequisites. If you’re deploying certificates to hosts on other platforms, you can skip this and head to [step 2](#step-2-connect-fleet-to-ndes).
|
||||
|
||||
#### Deploy root CA certificate
|
||||
|
||||
Windows hosts joined to Active Directory (AD) automatically receive the enterprise root CA certificate through Group Policy (GPO). Hosts that aren’t joined to AD (e.g. cloud-only or BYOD devices) won’t get this certificate automatically, so certificate delivery will fail because the host can’t validate the registration authority (RA) certificate chain.
|
||||
|
||||
For non-AD-joined hosts, deploy the root CA certificate using the configuration profile below. Scope it to only non-AD-joined hosts using a label or other targeting method.
|
||||
|
||||
Configuration profile:
|
||||
|
||||
```xml
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/RootCATrustedCertificates/Root/<YOURCA>/EncodedCertificate</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">b64</Format>
|
||||
</Meta>
|
||||
<Data><BASE64_ENCODED_ROOT_CA_CERT></Data>
|
||||
</Item>
|
||||
</Add>
|
||||
```
|
||||
|
||||
Replace `<YOURCA>` in the `LocURI` with a unique identifier for your CA (e.g. `MyOrgRootCA`). See the [RootCATrustedCertificates CSP documentation](https://learn.microsoft.com/en-us/windows/client-management/mdm/rootcacertificates-csp) for more details.
|
||||
|
||||
Replace `<BASE64_ENCODED_ROOT_CA_CERT>` with your root CA certificate encoded as a Base64 string by first retrieving the certificate from your NDES server using the SCEP `GetCACert` operation:
|
||||
|
||||
```
|
||||
curl -o ca-certs.p7b "https://<NDES_SERVER>/certsrv/mscep/mscep.dll?operation=GetCACert"
|
||||
openssl pkcs7 -inform DER -in ca-certs.p7b -print_certs -out certs.pem
|
||||
```
|
||||
|
||||
This returns a bundle with multiple certificates. Then, open `certs.pem` and copy the root CA certificate (the one where subject and issuer are the same). Last, save it to `root-ca.pem` and Base64-encode the DER form:
|
||||
|
||||
```
|
||||
openssl x509 -in root-ca.pem -outform DER -out root-ca.der
|
||||
base64 -i root-ca.der
|
||||
```
|
||||
|
||||
#### Make the CRL reachable over HTTP
|
||||
|
||||
By default, NDES puts LDAP URLs in certificates for the CRL (certificate revocation list) location. Hosts that are joined to AD can reach these LDAP endpoints, but hosts that aren’t joined to AD cannot. When a host can’t reach the CRL location, it can’t validate the certificate and will reject the SCEP response with a certificate validity error.
|
||||
|
||||
To fix this, configure NDES to publish the CRL over HTTP so any device can reach it. See Microsoft's [documentation](https://learn.microsoft.com/en-us/windows-server/networking/core-network-guide/cncg/server-certs/configure-the-cdp-and-aia-extensions-on-ca1) for instructions.
|
||||
|
||||
For testing, you can use the [quick CRL workaround](#quick-crl-workaround-for-testing-ndes-on-windows).
|
||||
|
||||
#### Make sure the CA server clock is correct
|
||||
|
||||
If the CA server’s clock is incorrect, certificates may have `notBefore` timestamps in the future. When this happens, the host rejects the certificate because it appears not valid yet, even though the CA issued it successfully.
|
||||
|
||||
There are many reasons a CA server’s clock can drift (e.g. misconfigured time sources, virtualization clock skew, Group Policy conflicts). We recommend working with your infrastructure team to ensure the CA server is using a reliable time synchronization method (e.g. NTP).
|
||||
|
||||
For testing, you can force the clock to the current time by running the following on the CA server in PowerShell:
|
||||
|
||||
```powershell
|
||||
Set-Date -Date "2026-03-16 12:00:00"
|
||||
```
|
||||
|
||||
### Step 2: Connect Fleet to NDES
|
||||
|
||||
1. In Fleet, head to **Settings > Integrations > Certificates**.
|
||||
2. Select the **Add CA** button and select **Okta CA or Microsoft NDES** in the dropdown.
|
||||
|
|
@ -159,19 +221,26 @@ The example paths end with `/certsrv/mscep/mscep.dll` and `/certsrv/mscep_admin/
|
|||
|
||||
When saving the configuration, Fleet will attempt to connect to the SCEP server to verify the connection, including retrieving a one-time challenge password. This validation also occurs when adding a new SCEP configuration or updating an existing one via API and GitOps, including dry runs. Please ensure the NDES password cache size is large enough to accommodate this validation.
|
||||
|
||||
### Step 2: Add SCEP configuration profile to Fleet
|
||||
> The default NDES password cache holds only 5 one-time challenge passwords. Each failed enrollment attempt consumes a password. We recommend increasing the cache size on the NDES server for production use.
|
||||
|
||||
### Step 3: Add SCEP configuration profile to Fleet
|
||||
|
||||
1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use `$FLEET_VAR_NDES_SCEP_CHALLENGE`. For `URL`, use `$FLEET_VAR_NDES_SCEP_PROXY_URL`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`.
|
||||
|
||||
2. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [supported variables](https://fleetdm.com/docs/configuration/yaml-files#variables).
|
||||
2. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can use [Fleet's host variables](https://fleetdm.com/docs/configuration/yaml-files#variables) such as `$FLEET_VAR_HOST_HARDWARE_SERIAL`. For Apple hosts, you can also use any of the [supported variables](https://fleetdm.com/docs/configuration/yaml-files#variables)..
|
||||
|
||||
3. In Fleet, head to **Controls > OS settings > Custom settings** and add the configuration profile to deploy certificates to your hosts.
|
||||
3. For Windows profiles, you also need to set `CAThumbprint` to the SHA1 fingerprint of your **root CA certificate** (not the RA signing certificate). See [How to get the CAThumbprint for Windows SCEP profiles](#how-to-get-the-cathumbprint-for-windows-scep-profiles).
|
||||
|
||||
4. In Fleet, head to **Controls > OS settings > Custom settings** and add the configuration profile to deploy certificates to your hosts.
|
||||
|
||||
When the profile is delivered to your hosts, Fleet will replace the variables. If something fails, errors will appear on each host's **Host details > OS settings**.
|
||||
|
||||
|
||||
|
||||
#### Example configuration profile
|
||||
#### Example configuration profiles
|
||||
|
||||
<details>
|
||||
<summary>Apple configuration profile (macOS)</summary>
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
|
@ -235,6 +304,127 @@ When the profile is delivered to your hosts, Fleet will replace the variables. I
|
|||
</plist>
|
||||
```
|
||||
|
||||
</details>
|
||||
<details>
|
||||
<summary>Windows configuration profile (device-scope)</summary>
|
||||
|
||||
All options in the example profile are required. Replace `<CA_THUMBPRINT>` with your root CA's SHA1 fingerprint. See [How to get the CAThumbprint for Windows SCEP profiles](#how-to-get-the-cathumbprint-for-windows-scep-profiles).
|
||||
|
||||
You can add any other options listed under Device/SCEP in the [Microsoft ClientCertificateInstall CSP documentation](https://learn.microsoft.com/en-us/windows/client-management/mdm/clientcertificateinstall-csp).
|
||||
|
||||
```xml
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">node</Format>
|
||||
</Meta>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/ServerURL</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">chr</Format>
|
||||
</Meta>
|
||||
<Data>$FLEET_VAR_NDES_SCEP_PROXY_URL</Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/Challenge</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">chr</Format>
|
||||
</Meta>
|
||||
<Data>$FLEET_VAR_NDES_SCEP_CHALLENGE</Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/SubjectName</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">chr</Format>
|
||||
</Meta>
|
||||
<Data>CN=$FLEET_VAR_HOST_HARDWARE_SERIAL NDES Device Cert,OU=$FLEET_VAR_SCEP_RENEWAL_ID</Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/KeyUsage</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">int</Format>
|
||||
</Meta>
|
||||
<Data>160</Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/KeyLength</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">int</Format>
|
||||
</Meta>
|
||||
<Data>2048</Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/HashAlgorithm</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">chr</Format>
|
||||
</Meta>
|
||||
<Data>SHA-2</Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/CAThumbprint</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">chr</Format>
|
||||
</Meta>
|
||||
<Data><CA_THUMBPRINT></Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Add>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/EKUMapping</LocURI>
|
||||
</Target>
|
||||
<Meta>
|
||||
<Format xmlns="syncml:metinf">chr</Format>
|
||||
</Meta>
|
||||
<!-- 1.3.6.1.5.5.7.3.2 is the OID for Client Authentication -->
|
||||
<Data>1.3.6.1.5.5.7.3.2</Data>
|
||||
</Item>
|
||||
</Add>
|
||||
<Exec>
|
||||
<Item>
|
||||
<Target>
|
||||
<LocURI>./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/Enroll</LocURI>
|
||||
</Target>
|
||||
</Item>
|
||||
</Exec>
|
||||
```
|
||||
|
||||
To create a **user-scope** profile, replace `./Device/` with `./User/` in all `<LocURI>` elements. User-scope profiles require the Windows device to have an Azure AD (Entra ID) user association. Devices with device-only MDM enrollment cannot process user-scope commands.
|
||||
|
||||
</details>
|
||||
|
||||
## Smallstep
|
||||
|
||||
The following steps show how to deploy [Smallstep](https://smallstep.com/) certificates.
|
||||
|
|
@ -784,6 +974,8 @@ You can deploy a user-scoped certificate on macOS and Windows hosts using a user
|
|||
|
||||
For macOS hosts, user-scoped certificates only work if the `login` keychain is unlocked. If it's locked, MDM commands to install the certificate configuration profile will always return `NotNow`. To check whether the `login` keychain is unlocked, open Keychain Access on the Mac. An unlocked icon should appear to the left of the `login` keychain under **Default keychains**. If it's locked, right-click on the `login` keychain to unlock it.
|
||||
|
||||
For Windows hosts, user-scoped profiles require the device to have an Azure AD (Entra ID) user association. Devices with device-only MDM enrollment do not have a user context and will reject all `./User/` CSP commands. Azure AD-joined devices with user enrollment support user-scope profiles.
|
||||
|
||||
### Editing certificate configuration profiles on Apple (macOS, iOS, iPadOS) hosts
|
||||
|
||||
When you edit a certificate configuration profile for Apple hosts, via GitOps, a new certificate will be added to each hosts' Keychain and the old certificate will be removed. It takes a couple minutes for the old certificate to be removed.
|
||||
|
|
@ -818,13 +1010,23 @@ fetch_cert -ca <EST-CA-ID> -fleeturl "<Fleet-server-URL>" -csr CustomerUserNetwo
|
|||
|
||||
### Assumptions and limitations
|
||||
|
||||
* NDES SCEP proxy is currently supported for macOS devices via Apple config profiles. Support for DDM (Declarative Device Management) is coming soon, as is support for iOS, iPadOS, Windows, and Linux.
|
||||
* NDES SCEP proxy is currently supported for macOS and Windows devices. Support for DDM (Declarative Device Management) is coming soon, as is support for iOS, iPadOS, and Linux.
|
||||
* Fleet server assumes a one-time challenge password expiration time of 60 minutes.
|
||||
* 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 custom SCEP proxy to deploy certificates, Fleet removes it, allowing you to use non-NDES SCEP servers.
|
||||
* 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 will not remove deployed certificates when configuration profiles are removed from Fleet or when host is transfered to another team.
|
||||
|
||||
### Troubleshooting NDES on Windows
|
||||
|
||||
If SCEP enrollment fails on a Windows device, the error `0x800B0101` ("A required certificate is not within its validity period") can indicate any of three issues:
|
||||
|
||||
1. **Root CA not trusted**: The device doesn't trust the CA that issued the NDES RA certificates. Fix: deploy the root CA certificate to the device's Trusted Root Certification Authorities store via an MDM profile.
|
||||
2. **CRL not reachable**: The device can't fetch the Certificate Revocation List because the CA only publishes CRLs via LDAP. Fix: configure the CA to publish CRLs via an HTTP endpoint. See [Step 1: Prerequisites for Windows hosts](#step-1-prerequisites-for-windows-hosts).
|
||||
3. **CA clock skew**: The CA server's clock is ahead of the device, causing certificates to have `notBefore` timestamps in the future. Fix: synchronize the CA server's clock via NTP.
|
||||
|
||||
If NDES returns `pkiStatus=FAILURE, failInfo=badRequest`, the NDES password cache may be full. Increase the cache size on the NDES server (see [Step 1: Prerequisites for Windows hosts](#step-1-prerequisites-for-windows-hosts)).
|
||||
|
||||
### How the SCEP proxy works
|
||||
|
||||
Fleet acts as a middleman between the host and the NDES or custom SCEP server. When a host requests a certificate from Fleet, Fleet requests a certificate from the NDES or custom SCEP server, retrieves the certificate, and sends it back to the host.
|
||||
|
|
@ -860,6 +1062,29 @@ An example CAThumprint looks like this: `2133EC6A3CFB8418837BB395188D1A62CA2B96A
|
|||
3. It will return the SHA1 Thumbprint without colons and text. Copy this.
|
||||
4. Use the copied value for `./Device/Vendor/MSFT/ClientCertificateInstall/SCEP/$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID/Install/CAThumbprint` option.
|
||||
|
||||
### Quick CRL workaround for testing NDES on Windows
|
||||
|
||||
For production, your CA should publish CRLs via HTTP (see [Step 1: Prerequisites for Windows hosts](#step-1-prerequisites-for-windows-hosts)). For testing, you can manually distribute the CRL to the device instead.
|
||||
|
||||
1. On the NDES/CA server, find the CRL files at `C:\Windows\System32\CertSrv\CertEnroll\`. You'll see a base CRL (`<CA-name>.crl`) and possibly a delta CRL (`<CA-name>+.crl`).
|
||||
|
||||
2. Copy the CRL files to the Windows test device and install them:
|
||||
|
||||
```powershell
|
||||
certutil -addstore CA C:\path\to\ca.crl
|
||||
certutil -addstore CA C:\path\to\ca_delta.crl
|
||||
```
|
||||
|
||||
3. Verify that revocation checking now passes:
|
||||
|
||||
```powershell
|
||||
certutil -verify C:\path\to\ra_cert.cer
|
||||
```
|
||||
|
||||
The output should end with `CertUtil: -verify command completed successfully.`
|
||||
|
||||
> CRLs expire (typically after about a week). You will need to repeat this process when the CRL expires. This workaround does not scale beyond a few test devices.
|
||||
|
||||
<meta name="articleTitle" value="Deploy certificates to connect end users to third-party tools">
|
||||
<meta name="authorFullName" value="Victor Lyuboslavsky">
|
||||
<meta name="authorGitHubUsername" value="getvictor">
|
||||
|
|
|
|||
|
|
@ -83,15 +83,13 @@ Currently, when editing a profile using Fleet's GitOps workflow, it can take 30
|
|||
|
||||
### Verified
|
||||
|
||||
> For some Windows configuration profiles, [verification doesn't work](https://github.com/fleetdm/fleet/issues/38833). Fleet will [remove verification](https://github.com/fleetdm/fleet/issues/31921) for Windows profiles in 4.83 (coming soon).
|
||||
Hosts that applied all OS settings.
|
||||
|
||||
Hosts that applied all OS settings.
|
||||
|
||||
For macOS configuration profiles and device-scoped Windows profiles, Fleet verified by running a report. It can take up to 1 hour ([configurable](https://fleetdm.com/docs/configuration/fleet-server-configuration#osquery-detail-update-interval)) for these profiles to move from "Verifying" to "Verified".
|
||||
For macOS configuration profiles, Fleet verified by running an osquery query. It can take up to 1 hour ([configurable](https://fleetdm.com/docs/configuration/fleet-server-configuration#osquery-detail-update-interval)) for these profiles to move from "Verifying" to "Verified".
|
||||
|
||||
macOS declarations profiles are verified with a [DDM StatusReport](https://developer.apple.com/documentation/devicemanagement/statusreport).
|
||||
|
||||
User-scoped Windows profiles are "Verified" after Fleet gets a [200 response](https://learn.microsoft.com/en-us/windows/client-management/oma-dm-protocol-support#syncml-response-status-codes) from the Windows MDM protocol.
|
||||
All Windows profiles are "Verified" after Fleet gets a [200 response](https://learn.microsoft.com/en-us/windows/client-management/oma-dm-protocol-support#syncml-response-status-codes) from the Windows MDM protocol.
|
||||
|
||||
iOS and iPadOS hosts are "Verified" after they acknowledge all MDM commands to apply OS settings. Android hosts are "Verified" after Fleet verifies that the settings is applied in the next [status report](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices).
|
||||
|
||||
|
|
@ -99,8 +97,6 @@ iOS and iPadOS hosts are "Verified" after they acknowledge all MDM commands to a
|
|||
|
||||
Hosts that acknowledged all MDM commands to apply OS settings. Fleet is verifying. If the profile wasn't delivered, Fleet will redeliver the profile.
|
||||
|
||||
For Windows profiles, when Fleet gets a [200 response](https://learn.microsoft.com/en-us/windows/client-management/oma-dm-protocol-support#syncml-response-status-codes) from the Windows MDM protocol, device-scoped profiles are "Verifying" but, currently, user-scoped Windows profiles go straight to "Verified."
|
||||
|
||||
### Pending
|
||||
|
||||
Hosts that are running MDM commands or will run MDM commands to apply OS settings when they come online.
|
||||
|
|
@ -133,7 +129,7 @@ SELECT data FROM registry WHERE path = 'HKEY_LOCAL_MACHINE\Software\Policies\emp
|
|||
|
||||
> If your Windows profile fails with the following error: "The MDM protocol returned a success but the result couldn’t be verified by osquery", and the profile includes `[!CDATA []]` sections, [escape the XML](https://www.freeformatter.com/xml-escape.html) instead of using CDATA. For example, `[!CDATA[<enabled/>]]>` should be changed to `<enabled/>`.
|
||||
|
||||
### Special Android behvaior
|
||||
### Special Android behavior
|
||||
|
||||
On Android, if some settings from the profile fail (e.g. incompatible device), other settings from the profile will still be applied. Failed settings will be surfaced on **Host > OS settings**.
|
||||
Also, some settings from the profile might be overridden by another configuration profile, which means if multiple profiles include the same setting, the profile that is delivered most recently will be applied.
|
||||
|
|
|
|||
|
|
@ -24,13 +24,9 @@ Learn more about automatically installing software [the Automatically install so
|
|||
* 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.
|
||||
* If you check the **Automatic install** box, Fleet will create a policy that checks for the existence of the software and will automatically trigger an install on hosts where the software does not exist.
|
||||
|
||||
> **Note:** Automatic install is not supported for script-only packages (`.sh` and `.ps1` files).
|
||||
* To allow users to install the software from Fleet Desktop, check the **Self-service** checkbox.
|
||||
* To customize installer behavior, click on **Advanced options**.
|
||||
|
||||
> After the initial package upload, all options, except for automatic install, can be modified. This includes the self-service setting, 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. If you want to enable automatic installs after initial package upload, follow the steps in our [automatic software install guide](https://fleetdm.com/guides/automatic-software-install-in-fleet) to add an automatic install policy.
|
||||
> 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).
|
||||
|
||||
### Package metadata extraction
|
||||
|
||||
|
|
@ -149,6 +145,6 @@ Please refer to the documentation for [managing software with GitOps](https://fl
|
|||
<meta name="authorFullName" value="Roberto Dip">
|
||||
<meta name="authorGitHubUsername" value="roperzh">
|
||||
<meta name="category" value="guides">
|
||||
<meta name="publishedOn" value="2025-05-05">
|
||||
<meta name="publishedOn" value="2026-03-26">
|
||||
<meta name="articleImageUrl" value="../website/assets/images/articles/deploy-security-agents-1600x900@2x.png">
|
||||
<meta name="description" value="This guide will walk you through adding and editing software packages in Fleet.">
|
||||
|
|
|
|||
|
|
@ -122,7 +122,7 @@ Save the profile to your computer so you can upload it to Fleet in the next sect
|
|||
### Deploy the configuration profile to your hosts
|
||||
Now that we have a configuration profile with our desired settings, we can upload it to Fleet to deploy it to our hosts and activate the Platform SSO extension.
|
||||
|
||||
On your Fleet server, select the fleet you want to deploy Platform SSO to. Navigate to Controls > OS Settings > Custom settings. Click the Add profile button, then find the `platform-sso-settings.mobileconfig` profile on your computer and upload it to Fleet.
|
||||
On your Fleet server, select the team you want to deploy Platform SSO to. Navigate to Controls > OS Settings > Custom settings. Click the Add profile button, then find the `platform-sso-settings.mobileconfig` profile on your computer and upload it to Fleet.
|
||||
|
||||
Uploading the profile to a fleet will automatically deliver it to all macOS hosts enrolled in that fleet. If you wish to have more control over which hosts on the fleet receive the profile, you can use labels to target or exclude specific hosts.
|
||||
|
||||
|
|
|
|||
|
|
@ -50,7 +50,9 @@ If you set a past date (ex. yesterday) as the deadline, the end user will immedi
|
|||
|
||||
You can require hosts that automatically enroll via ADE to update to the latest version before they enroll to Fleet (during Setup Assistant).
|
||||
|
||||
For macOS hosts, in Fleet, head to **Controls > OS updates** and check the **Update new hosts to latest** checkbox.
|
||||
For macOS hosts, in Fleet, head to **Controls > OS updates** and check the **Update new hosts to latest** checkbox.
|
||||
|
||||
If **Update new hosts to latest** is checked, hosts below the minimum version are updated to the latest version during Setup Assistant. If a minimum version isn’t set, all hosts get updated.
|
||||
|
||||
For iOS/iPadOS hosts, set a minimum version and deadline. New iOS/iPadOS hosts will always update to the latest version (not the minimum version specified). On already enrolled hosts, updates are only enforced if the host is [below the minimum version](#apple-macos-ios-and-ipados-end-user-experience).
|
||||
|
||||
|
|
|
|||
|
|
@ -47,6 +47,8 @@ You can install a Fleet-maintained app three ways:
|
|||
|
||||
You can track the installation process in the **Activities** section on the **Details** tab of this **Host Details** page.
|
||||
|
||||
To keep the app up to date automatically, add a [patch policy](https://fleetdm.com/guides/how-to-use-policies-for-patch-management-in-fleet).
|
||||
|
||||
## Uninstall the app
|
||||
|
||||
To remove the app, navigate to the **Host Details** page for the appropriate host, then to the **Software** tab. Find the app, then click on the **Actions** drop-down, then **Uninstall**.
|
||||
|
|
@ -65,6 +67,18 @@ To get the latest version of a Fleet-maintained app,
|
|||
|
||||
A streamlined flow for pulling the latest version of a Fleet-maintained app is [coming soon](https://github.com/fleetdm/fleet/issues/32993).
|
||||
|
||||
With a [patch policy](https://fleetdm.com/guides/how-to-use-policies-for-patch-management-in-fleet) and [GitOps](https://fleetdm.com/docs/configuration/yaml-files#patch-policy), the query automatically updates to include the latest version each time specs are applied. Combined with install automation, outdated hosts receive the update automatically.
|
||||
|
||||
## Keep apps up to date with patch policies
|
||||
|
||||
You can create a **patch policy** for a Fleet-maintained app to automatically detect hosts running outdated versions. With [GitOps](https://fleetdm.com/docs/configuration/yaml-files#patch-policy), the patch policy query automatically updates to include the latest version each time specs are applied.
|
||||
|
||||
To add a patch policy, open the app's details page under **Software**, then select **Actions > Patch**.
|
||||
|
||||
To automatically install updates when the policy fails, enable the automation at **Policies > Manage automations > Install software**.
|
||||
|
||||
For a detailed walkthrough, see the [patch management guide](https://fleetdm.com/guides/how-to-use-policies-for-patch-management-in-fleet).
|
||||
|
||||
## Manage apps with GitOps
|
||||
|
||||
To manage Fleet-maintained apps using Fleet's best practice GitOps, check out `fleet_maintained_apps`, found under the
|
||||
|
|
|
|||
|
|
@ -44,6 +44,7 @@ Below is the JSON payload that is sent to Fleet Device Management Inc:
|
|||
"oktaConditionalAccessConfigured": true,
|
||||
"conditionalAccessBypassDisabled": false,
|
||||
"numHostsFleetDesktopEnabled": 999,
|
||||
"anyFleetRecoveryLockPasswordEnabled": true,
|
||||
"fleetMaintainedAppsMacOS": [
|
||||
"1password/darwin",
|
||||
"slack/darwin",
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
|
||||
|
||||
Policies in Fleet enable IT admins to report on devices and get quick yes or no answers about the status of their endpoints. Powered by the flexibility of osquery, the policies engine has become an invaluable part of the IT toolkit, simplifying the management of devices at scale.
|
||||
Policies in Fleet enable IT admins to report on devices and get quick yes or no answers about the status of their endpoints. Powered by the flexibility of osquery, the policies engine has become an invaluable part of the IT toolkit, simplifying the management of devices at scale. This guide covers two approaches: **patch policies**, which automate everything for Fleet-maintained apps, and **manual policies** for custom packages.
|
||||
|
||||
Initially, Fleet’s policies allowed for automated responses, like firing a webhook on a policy failure or creating a ticket in your ITSM system. While effective, these actions were limited by the capabilities of your existing tools to process and act on these notifications.
|
||||
|
||||
|
|
@ -10,7 +10,9 @@ Initially, Fleet’s policies allowed for automated responses, like firing a web
|
|||
|
||||
Fleet’s policy capabilities have evolved beyond notification-based responses. With the release of Fleet v4.57, the policies engine now supports a game-changing feature: automated software installation on a policy failure. This addition transforms the policies engine into a dynamic tool for streamlined patch management.
|
||||
|
||||
In this article, we’ll explore how to leverage this new feature to automate patching across your environment. This will free up valuable IT resources to focus on high-impact tasks while enhancing end-user support.
|
||||
With Fleet v4.83, patch management gets even simpler with **patch policies** for [Fleet-maintained apps](https://fleetdm.com/guides/fleet-maintained-apps). Patch policies eliminate the need to write osquery queries — Fleet auto-generates the correct query for each app. When managed via GitOps, the query automatically updates to include the latest version each time specs are applied.
|
||||
|
||||
In this article, we’ll explore how to leverage these features to automate patching across your environment. This will free up valuable IT resources to focus on high-impact tasks while enhancing end-user support.
|
||||
|
||||
## Why it matters
|
||||
|
||||
|
|
@ -20,9 +22,50 @@ Regular updates often include bug fixes that improve stability and enhance user
|
|||
|
||||
Additionally, updated software often includes new features that can ultimately help teams work more efficiently and effectively.
|
||||
|
||||
## Let’s get started
|
||||
## Patch policies for Fleet-maintained apps
|
||||
|
||||
In this article, we will be using Google Chrome to demonstrate the functionality, and I already have the latest version’s .pkg downloaded locally.
|
||||
_Available in Fleet Premium_
|
||||
|
||||
A patch policy automatically checks whether a Fleet-maintained app is up to date on your hosts. Unlike manual policies, you don’t need to write or update osquery queries — Fleet handles it for you.
|
||||
|
||||
Key benefits:
|
||||
- **Automatic query generation** — Fleet creates the correct query for the app and platform.
|
||||
- **Fail only if outdated** — The policy only fails if the app IS installed AND running an older version. Hosts without the app installed pass the policy.
|
||||
|
||||
### In the Fleet UI
|
||||
|
||||
1. Navigate to **Software** and select your team.
|
||||
2. Click on a Fleet-maintained app to open its details.
|
||||
3. From the **Actions** dropdown, select **Patch**.
|
||||
4. Click **Add** in the confirmation modal.
|
||||
|
||||
To automatically install updates when the policy fails, navigate to **Policies > Manage automations > Install software** and enable the automation for the new patch policy.
|
||||
|
||||
### Via GitOps
|
||||
|
||||
Add a policy with `type: patch` and specify the `fleet_maintained_app_slug`. With GitOps, the patch policy query automatically updates to include the latest version each time specs are applied:
|
||||
|
||||
```yaml
|
||||
policies:
|
||||
- name: Zoom up to date
|
||||
description: Outdated software might introduce security vulnerabilities or compatibility issues.
|
||||
resolution: Install the latest version from self-service.
|
||||
type: patch
|
||||
fleet_maintained_app_slug: zoom/darwin
|
||||
install_software: true
|
||||
```
|
||||
|
||||
For all available options, see the [GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#patch-policy).
|
||||
|
||||
### Via the API
|
||||
|
||||
Set `type` to `"patch"` and provide `patch_software_title_id` when [adding a team policy](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy).
|
||||
|
||||
## Manual policies for custom packages
|
||||
|
||||
If you’re deploying custom software packages (not Fleet-maintained apps), you can write your own policy query and pair it with install automation.
|
||||
|
||||
In this example, we will be using Google Chrome to demonstrate the functionality, and I already have the latest version’s .pkg downloaded locally.
|
||||
|
||||
Select the fleet you want the policy to run on. Navigate to **Software > Add Software**. Here you can use one of Fleet’s maintained apps, add from VPP or Custom Package. We will use Custom Package in this example and upload the Google Chrome.pkg mentioned previously. After upload, there are a couple of options for pre/post-install queries and scripts - you can read more about those options in our [guide on deploying software](https://fleetdm.com/guides/deploy-software-packages).
|
||||
|
||||
|
|
@ -48,9 +91,19 @@ The module will show the policies available for that fleet. Check the box to tur
|
|||
|
||||
And that’s it! Policies are evaluated across all online hosts every hour, or when a device is refetched manually. Any machine that fails this policy will install the Chrome version that was set in the policy.
|
||||
|
||||
## When to use each approach
|
||||
|
||||
| | Patch policies | Manual policies |
|
||||
| --- | --- | --- |
|
||||
| **Best for** | Fleet-maintained apps | Custom packages, VPP apps |
|
||||
| **Query management** | Automatic | You write and maintain the query |
|
||||
| **Version updates** | Automatic with GitOps; re-create via UI for new versions | Manual |
|
||||
| **Behavior when app is missing** | Policy passes | Depends on your query |
|
||||
| **Platforms** | macOS, Windows | macOS, Windows, Linux |
|
||||
|
||||
## What else can we do?
|
||||
|
||||
This functionality unlocks many use cases for an IT admin to help manage their fleet. Another use case for this feature is to support a zero-touch deployment of devices and ensure that critical business and productivity software is installed from the first boot.
|
||||
This functionality unlocks many use cases for an IT admin to help manage their fleet. Another use case for this feature is to support a zero-touch deployment of devices and ensure that critical business and productivity software is installed from the first boot.
|
||||
|
||||
A simple query like such:
|
||||
|
||||
|
|
@ -60,17 +113,22 @@ SELECT 1 FROM apps WHERE bundle_identifier = ‘com.tinyspeck.slackmacgap’
|
|||
|
||||
would deploy Slack to your endpoints the moment it comes out of the box, ensuring your users are ready to hit the ground running from day 1.
|
||||
|
||||
> If the app is available as a Fleet-maintained app (like Slack), you can also add a [patch policy](#patch-policies-for-fleet-maintained-apps) to keep it updated automatically — no query maintenance required.
|
||||
|
||||
## Via the API
|
||||
|
||||
Fleet Premium customers can leverage the REST API to upload software packages and set policy automations using the software_title_id field.
|
||||
Fleet Premium customers can leverage the REST API for both approaches:
|
||||
|
||||
Info about the [Upload software](https://fleetdm.com/docs/rest-api/rest-api#add-package) and [Team policy](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy) API docs are available in the documentation.
|
||||
- **Patch policies**: Set `type` to `"patch"` with `patch_software_title_id` when [adding a team policy](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy).
|
||||
- **Manual policies**: Use `software_title_id` to link a policy to software that installs on failure.
|
||||
|
||||
See the [Upload software](https://fleetdm.com/docs/rest-api/rest-api#add-package) and [Team policy](https://fleetdm.com/docs/rest-api/rest-api#add-team-policy) API docs.
|
||||
|
||||
## Curious about GitOps?
|
||||
|
||||
Fleet's flexible API and support for a GitOps life cycle means this entire process can be stored and managed in code, further unlocking audibility, collaboration, and security. Know who made changes, when, and why—without being tied to vendor-specific methods.
|
||||
|
||||
Nest an **install_software** block in the policy you want to automate and ensure the path to the software matches the same path referenced in the fleet configuration file under the software block. Check out the [GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#policies) for more details.
|
||||
For manual policies, nest an **install_software** block in the policy you want to automate and ensure the path to the software matches the same path referenced in the fleet configuration file under the software block. For patch policies, set `type` to `patch` and specify `fleet_maintained_app_slug`. Check out the [GitOps reference documentation](https://fleetdm.com/docs/configuration/yaml-files#policies) for more details.
|
||||
|
||||
## Want to know more?
|
||||
|
||||
|
|
@ -81,6 +139,6 @@ Reach out for more information and a demo, or explore Fleet's detailed [document
|
|||
<meta name="authorFullName" value="Harrison Ravazzolo">
|
||||
<meta name="authorGitHubUsername" value="harrisonravazzolo">
|
||||
<meta name="category" value="guides">
|
||||
<meta name="publishedOn" value="2024-11-07">
|
||||
<meta name="publishedOn" value="2026-03-27">
|
||||
<meta name="articleImageUrl" value="../website/assets/images/articles/sysadmin-diaries-1600x900@2x.png">
|
||||
<meta name="description" value="This guide explores automating patching across your environment.">
|
||||
<meta name="description" value="This guide explores automating patching using patch policies for Fleet-maintained apps and manual policies for custom packages.">
|
||||
|
|
|
|||
|
|
@ -30,6 +30,24 @@ You can also manage which Google Play Store apps are available for self-service
|
|||
|
||||
3. Select **Add software > App store**, choose the Android platform, then enter the application ID.
|
||||
|
||||
#### Install Android web app (web clip)
|
||||
|
||||
> Before deploying web apps, make sure to [add Google Chrome](#google-play-android) first. This applies to both work profile (BYO) and fully-managed Android devices. If Chrome isn’t installed, the end user will be prompted to install it and redirected to the managed Play Store.
|
||||
|
||||
To add an Android web app, first create the web app using the Fleet API. Send a request to the [`Create Android web app`](https://fleetdm.com/docs/rest-api/rest-api#create-android-web-app).
|
||||
|
||||
The response includes an `app_store_id` (e.g. `com.google.enterprise.webapp.x1c41e22ab611cb98`). Use this ID as the application ID in **Add software > App store** (step 3 above).
|
||||
|
||||
**Example request**
|
||||
|
||||
```sh
|
||||
curl -X POST https://<your_fleet_server_url>/api/v1/fleet/software/web_apps \
|
||||
-H "Authorization: Bearer <your_fleet_api_token>" \
|
||||
-F 'title=Acme web app' \
|
||||
-F 'url=https://app.acme.com' \
|
||||
-F 'icon=@/path/to/app-icon.png'
|
||||
```
|
||||
|
||||
## Edit or delete the app
|
||||
|
||||
1. In Fleet, head to the **Software** page and select a fleet in the fleets dropdown.
|
||||
|
|
|
|||
|
|
@ -142,9 +142,14 @@ Once disabled on the Okta side, you can delete the conditional access configurat
|
|||
|
||||
## Bypassing conditional access
|
||||
|
||||
End users can temporarily bypass conditional access from their **My device** page if their host is failing a policy. To trigger a bypass, click a failing policy labeled **Action required**, select **Resolve later**, and confirm in the following modal. The bypass allows the user to complete a single login even with failing policies and is consumed immediately upon successful login.
|
||||
End users can temporarily bypass conditional access from their **My device** page if their host is not failing any critical policies. To trigger a bypass, click a non-critical failing policy labeled **Action required**, select **Resolve later**, and confirm in the following modal. The bypass allows the user to complete a single login even with failing policies and is consumed immediately upon successful login.
|
||||
|
||||
If a host is failing multiple conditional access policies, the bypass option is only available if **no** failing policy is marked critical. If any one of the failing policies is marked critical, the end user will not see the option to bypass and must resolve the issue to regain access. (You can update a policy's `critical` setting on the **Edit policy** page.)
|
||||
|
||||
This feature is enabled by default, but can be disabled by checking the **Disable bypass** checkbox in **Settings** > **Integrations** > **Conditional access**.
|
||||
|
||||
|
||||
|
||||
This feature is enabled by default, but can be disabled by checking the **Disable bypass** checkbox in **Settings** > **Integrations** > **Conditional access**.
|
||||
|
||||
### Per-policy bypass
|
||||
|
||||
|
|
|
|||
|
|
@ -99,6 +99,8 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines.
|
|||
| View, edit, and delete Volume Purchasing Program (VPP) connections | | | | | ✅ | |
|
||||
| Connect Android Enterprise | | | | | ✅ | |
|
||||
| View disk encryption key for macOS, Windows, and Linux hosts | ✅ | ✅ | ✅ | ✅ | ✅ | |
|
||||
| View Recovery Lock password for macOS hosts | ✅ | ✅ | ✅ | ✅ | ✅ | |
|
||||
| Rotate Recovery Lock password for macOS hosts | | | | ✅ | ✅ | |
|
||||
| Edit OS updates for macOS, Windows, iOS, and iPadOS hosts | | | | | ✅ | ✅ |
|
||||
| Create, edit, resend and delete configuration profiles for Apple (macOS/iOS/iPadOS), Windows, and Android hosts | | | | ✅ | ✅ | ✅ |
|
||||
| View and resend configuration profiles for Apple (macOS/iOS/iPadOS), Windows, and Android hosts | | | ✅ | ✅ | ✅ | ✅ |
|
||||
|
|
@ -182,6 +184,8 @@ Users with access to multiple fleets can be assigned different roles for each fl
|
|||
| Edit agent options | | | | | ✅ | ✅ |
|
||||
| Initiate [file carving](https://fleetdm.com/docs/using-fleet/rest-api#file-carving) | | | | ✅ | ✅ | |
|
||||
| View disk encryption key for macOS hosts | ✅ | ✅ | ✅ | ✅ | ✅ | |
|
||||
| View Recovery Lock password for macOS hosts | ✅ | ✅ | ✅ | ✅ | ✅ | |
|
||||
| Rotate Recovery Lock password for macOS hosts | | | | ✅ | ✅ | |
|
||||
| Edit OS updates for macOS, Windows, iOS, and iPadOS hosts | | | | | ✅ | ✅ |
|
||||
| Create, edit, resend and delete configuration profiles for Apple (macOS/iOS/iPadOS), Windows, and Android hosts | | | | ✅ | ✅ | ✅ |
|
||||
| View and resend configuration profiles for Apple (macOS/iOS/iPadOS), Windows, and Android hosts | | | ✅ | ✅ | ✅ | ✅ |
|
||||
|
|
|
|||
|
|
@ -23,12 +23,12 @@ You can enforce end user authentication during automatic enrollment (ADE) for Ap
|
|||
1. Create a new SAML app in your IdP. In your new app, use `https://<your_fleet_url>/api/v1/fleet/mdm/sso/callback` for the SSO URL. If this URL is set incorrectly, end users won't be able to enroll. On iOS hosts, they'll see a "This screen size is not supported yet" error message.
|
||||
|
||||
2. In your new SAML app, set **Name ID** to email (required). Fleet will trim this email and use it
|
||||
to populate and lock the macOS local account **Account Name**. For example, a
|
||||
to populate the macOS local account **Account Name**. For example, a
|
||||
"johndoe@example.com" email will turn into a "johndoe" account name.
|
||||
|
||||
> If the host is restarted during automatic enrollment (DEP), the macOS local account fields won't be populated with the user's IDP email and username.
|
||||
|
||||
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 and lock the macOS local account **Full Name** with any of these.
|
||||
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 end user authentication by heading to **Controls > Setup experience > End user authentication**. Alternatively, you can use [Fleet's GitOps workflow](https://github.com/fleetdm/fleet-gitops) to configure your IdP integration and enable end user authentication.
|
||||
|
||||
|
|
|
|||
|
|
@ -120,12 +120,34 @@ Policies can be specified inline in your `default.yml`, `fleets/fleet-name.yml`,
|
|||
|
||||
### Options
|
||||
|
||||
For possible options, see the parameters for the [Create policy API endpoint](https://fleetdm.com/docs/rest-api/rest-api#create-policy)
|
||||
For available options, see the parameters for the [Create policy](https://fleetdm.com/docs/rest-api/rest-api#create-policy) and [Create team policy](https://fleetdm.com/docs/rest-api/rest-api#create-team-policy) API endpoints.
|
||||
|
||||
In Fleet Premium you can trigger software installs or script runs on policy failure:
|
||||
#### Patch policy
|
||||
|
||||
- For software installs, specify either `install_software.package_path` or `install_software.hash_sha256` in your YAML. If `install_software.package_path` only one package can be specified in the package YAML.
|
||||
- For script runs, specify `run_script.path`.
|
||||
_Available in Fleet Premium_
|
||||
|
||||
You can create a patch policy by setting `type` to `patch` and specifying `fleet_maintained_app_slug`.
|
||||
|
||||
A patch policy's `query` automatically updates. Hosts will fail this policy if they’re not running the latest version found in [the app's metadata](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs). If `version` is set for `fleet_maintained_apps`, that version is included in the query.
|
||||
|
||||
To automatically install the app when this policy fails, you can add an automation by setting `install_software` to `true`.
|
||||
#### Automations
|
||||
|
||||
##### Install software
|
||||
|
||||
_Available in Fleet Premium_
|
||||
|
||||
To trigger software install, when policy fails, specify one of:
|
||||
- `install_software.package_path` is the path to a custom package YAML. Only one package can be specified in the package YAML.
|
||||
- `install_software.hash_sha256` is [SHA256 hash](https://fleetdm.com/docs/configuration/yaml-files#hash) of a custom package.
|
||||
|
||||
#### Run script
|
||||
|
||||
_Available in Fleet Premium_
|
||||
|
||||
To trigger script run, when policy fails, specify:
|
||||
|
||||
- `run_script.path` is a path to a script YAML.
|
||||
|
||||
> Specifying one package without a list is deprecated as of Fleet 4.73. It is maintained for backwards compatibility. Please use a list instead even if you're only specifying one package.
|
||||
|
||||
|
|
@ -188,6 +210,12 @@ policies:
|
|||
install_software:
|
||||
package_path: ./linux-firefox.deb.package.yml
|
||||
# app_store_id: "1487937127" (for App Store apps)
|
||||
- name: Zoom up to date
|
||||
description: Outdated software might introduce security vulnerabilities or compatibility issues.
|
||||
resolution: Install the latest version from self-service.
|
||||
type: patch
|
||||
fleet_maintained_app_slug: zoom/darwin
|
||||
install_software: true
|
||||
```
|
||||
|
||||
`default.yml` (for policies that neither install software nor run scripts), `fleets/fleet-name.yml`, or `fleet/unassigned.yml`
|
||||
|
|
@ -330,6 +358,7 @@ The `controls` section allows you to configure scripts and device management (MD
|
|||
- `windows_migration_enabled` specifies whether or not to automatically migrate Windows hosts connected to another MDM solution. If `false`, MDM is only turned on after hosts are unenrolled from your old MDM solution. `enable_turn_on_windows_mdm_manually` must be set to `false`. (default: `false`). Can only be configured for "All fleets" (`default.yml`).
|
||||
- `enable_disk_encryption` specifies whether or not to enforce disk encryption on macOS, Windows, and Linux hosts (default: `false`).
|
||||
- `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`).
|
||||
- `enable_recovery_lock_password` specifies whether or not to enforce Recovery Lock password on eligible macOS hosts (default: `false`).
|
||||
|
||||
#### Example
|
||||
|
||||
|
|
@ -345,6 +374,7 @@ controls:
|
|||
enable_turn_on_windows_mdm_manually: false # Available in Fleet Premium
|
||||
windows_migration_enabled: true # Available in Fleet Premium
|
||||
enable_disk_encryption: true # Available in Fleet Premium
|
||||
enable_recovery_lock_password: true # Available in Fleet Premium
|
||||
macos_updates: # Available in Fleet Premium
|
||||
deadline: "2024-12-31"
|
||||
minimum_version: "15.1"
|
||||
|
|
@ -480,7 +510,8 @@ The `macos_setup` section lets you control the out-of-the-box [setup experience]
|
|||
|
||||
- `bootstrap_package` is the URL to a bootstrap package. Fleet will download the bootstrap package. Applies to macOS only (default: `""`).
|
||||
- `manual_agent_install` specifies whether Fleet's agent (fleetd) will be installed as part of setup experience. Applies to macOS only (default: `false`)
|
||||
- `enable_end_user_authentication` specifies whether or not to require end user authentication when the user first sets up their host. Applies to macOS, Windows, Linux, iOS/iPadOS, and Android.
|
||||
- `enable_end_user_authentication` specifies whether or not to require end user authentication when the user first sets up their host. Applies to macOS, Windows, Linux, iOS/iPadOS, and Android.
|
||||
- `lock_end_user_info` specifies whether or not to enable end user to edit the local account Account Name and Full Name in macOS Setup Assistant. (default: `true`)
|
||||
- `require_all_software` specifies whether to cancel setup on a macOS host if any software installs fail.
|
||||
- `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 Manager (ABM).
|
||||
- `macos_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.
|
||||
|
|
@ -495,6 +526,7 @@ macos_setup:
|
|||
bootstrap_package: "https://your-storage/package.pkg"
|
||||
manual_agent_install: false
|
||||
enable_end_user_authentication: true
|
||||
lock_end_user_info: true
|
||||
enable_release_device_manually: false
|
||||
macos_setup_assistant: "./setup_assistant.json"
|
||||
script: "./post_setup.sh"
|
||||
|
|
|
|||
|
|
@ -2369,6 +2369,23 @@ This activity contains the following fields:
|
|||
}
|
||||
```
|
||||
|
||||
## read_host_recovery_lock_password
|
||||
|
||||
Generated when a user views the Recovery Lock password for a host.
|
||||
|
||||
This activity contains the following fields:
|
||||
- "host_id": ID of the host.
|
||||
- "host_display_name": Display name of the host.
|
||||
|
||||
#### Example
|
||||
|
||||
```json
|
||||
{
|
||||
"host_id": 1,
|
||||
"host_display_name": "Anna's MacBook Pro"
|
||||
}
|
||||
```
|
||||
|
||||
## edited_enroll_secrets
|
||||
|
||||
Generated when global or team enroll secrets are edited.
|
||||
|
|
@ -2381,8 +2398,59 @@ This activity contains the following fields:
|
|||
|
||||
```json
|
||||
{
|
||||
"team_id": 1,
|
||||
"team_name": "Workstations",
|
||||
"team_id": 123,
|
||||
"team_name": "Workstations"
|
||||
}
|
||||
```
|
||||
|
||||
## escrowed_recovery_lock_password
|
||||
|
||||
Generated when a Recovery Lock password is escrowed.
|
||||
|
||||
This activity contains the following fields:
|
||||
- "host_id": ID of the host.
|
||||
- "host_display_name": Display name of the host.
|
||||
|
||||
#### Example
|
||||
|
||||
```json
|
||||
{
|
||||
"host_id": 123,
|
||||
"host_display_name": "Anna's MacBook Pro"
|
||||
}
|
||||
```
|
||||
|
||||
## enabled_recovery_lock_password
|
||||
|
||||
Generated when a user turns on Recovery Lock password for a team (or no team).
|
||||
|
||||
This activity contains the following fields:
|
||||
- "team_id": The ID of the team that Recovery Lock password applies to, `null` if it applies to devices that are not in a team.
|
||||
- "team_name": The name of the team that Recovery Lock password applies to, `null` if it applies to devices that are not in a team.
|
||||
|
||||
#### Example
|
||||
|
||||
```json
|
||||
{
|
||||
"team_id": 123,
|
||||
"team_name": "Workstations"
|
||||
}
|
||||
```
|
||||
|
||||
## disabled_recovery_lock_password
|
||||
|
||||
Generated when a user turns off Recovery Lock password for a team (or no team).
|
||||
|
||||
This activity contains the following fields:
|
||||
- "team_id": The ID of the team that Recovery Lock password applies to, `null` if it applies to devices that are not in a team.
|
||||
- "team_name": The name of the team that Recovery Lock password applies to, `null` if it applies to devices that are not in a team.
|
||||
|
||||
#### Example
|
||||
|
||||
```json
|
||||
{
|
||||
"team_id": 123,
|
||||
"team_name": "Workstations"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -200,13 +200,13 @@ For this to work correctly make sure that:
|
|||
Users created via JIT provisioning can be assigned Fleet roles using SAML custom attributes that are sent by the IdP in `SAMLResponse`s during login.
|
||||
Fleet will attempt to parse SAML custom attributes with the following format:
|
||||
- `FLEET_JIT_USER_ROLE_GLOBAL`: Specifies the global role to use when creating the user.
|
||||
- `FLEET_JIT_USER_ROLE_TEAM_<TEAM_ID>`: Specifies fleet role for fleet with ID `<TEAM_ID>` to use when creating the user.
|
||||
- `FLEET_JIT_USER_ROLE_FLEET_<FLEET_ID>`: Specifies fleet-level role for fleet with ID `<FLEET_ID>` to use when creating the user.
|
||||
|
||||
Currently supported values for the above attributes are: `admin`, `maintainer`, `observer`, `observer_plus`, `technician` and `null`.
|
||||
A role attribute with value `null` will be ignored by Fleet. (This is to support limitations on some IdPs which do not allow you to choose what keys are sent to Fleet when creating a new user.)
|
||||
SAML supports multi-valued attributes, Fleet will always use the last value.
|
||||
|
||||
NOTE: Setting both `FLEET_JIT_USER_ROLE_GLOBAL` and `FLEET_JIT_USER_ROLE_TEAM_<TEAM_ID>` will cause an error during login as Fleet users cannot be Global users and belong to fleets.
|
||||
NOTE: Setting both `FLEET_JIT_USER_ROLE_GLOBAL` and `FLEET_JIT_USER_ROLE_FLEET_<FLEET_ID>` will cause an error during login as users cannot be both global users and belong to fleets.
|
||||
|
||||
Following is the behavior that will take place on every SSO login:
|
||||
|
||||
|
|
@ -256,10 +256,10 @@ Here's a `SAMLResponse` sample to set the role of SSO users to `observer` in fle
|
|||
</saml2:Subject>
|
||||
[...]
|
||||
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
|
||||
<saml2:Attribute Name="FLEET_JIT_USER_ROLE_TEAM_1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
|
||||
<saml2:Attribute Name="FLEET_JIT_USER_ROLE_FLEET_1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
|
||||
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">observer</saml2:AttributeValue>
|
||||
</saml2:Attribute>
|
||||
<saml2:Attribute Name="FLEET_JIT_USER_ROLE_TEAM_2" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
|
||||
<saml2:Attribute Name="FLEET_JIT_USER_ROLE_FLEET_2" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
|
||||
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">maintainer</saml2:AttributeValue>
|
||||
</saml2:Attribute>
|
||||
</saml2:AttributeStatement>
|
||||
|
|
|
|||
|
|
@ -1838,6 +1838,7 @@ Modifies the Fleet's configuration with the supplied information.
|
|||
"enable_turn_on_windows_mdm_manually": false,
|
||||
"enable_disk_encryption": true,
|
||||
"windows_require_bitlocker_pin": false,
|
||||
"enable_recovery_lock_password": true,
|
||||
"macos_updates": {
|
||||
"minimum_version": "12.3.1",
|
||||
"deadline": "2022-01-01",
|
||||
|
|
@ -1893,6 +1894,7 @@ Modifies the Fleet's configuration with the supplied information.
|
|||
"macos_setup": {
|
||||
"bootstrap_package": "",
|
||||
"enable_end_user_authentication": false,
|
||||
"lock_end_user_info": true,
|
||||
"macos_setup_assistant": "path/to/config.json"
|
||||
},
|
||||
"apple_server_url": "https://instance.fleet.com"
|
||||
|
|
@ -2426,6 +2428,7 @@ When updating conditional access config, all `conditional_access` fields must ei
|
|||
| enable_turn_on_windows_mdm_manually | boolean | _Available in Fleet Premium._ Specifies whether or not to require end users to manually turn on MDM in **Settings > Access work or school**. If `false`, MDM is automatically turned on for all Windows hosts that aren't connected to any MDM solution. |
|
||||
| enable_disk_encryption | boolean | _Available in Fleet Premium._ Hosts that are "Unassigned" will have disk encryption enabled if set to true. |
|
||||
| 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. |
|
||||
| enable_recovery_lock_password | boolean | _Available in Fleet Premium._ Unassigned hosts will have Recovery Lock password enabled if set to true. |
|
||||
| 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). |
|
||||
|
|
@ -2516,6 +2519,7 @@ _Available in Fleet Premium._
|
|||
| 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). |
|
||||
| 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`) |
|
||||
|
||||
<br/>
|
||||
|
||||
|
|
@ -2561,6 +2565,7 @@ _Available in Fleet Premium._
|
|||
"enable_turn_on_windows_mdm_manually": false,
|
||||
"enable_disk_encryption": true,
|
||||
"windows_require_bitlocker_pin": false,
|
||||
"enable_recovery_lock_password": true,
|
||||
"macos_updates": {
|
||||
"minimum_version": "12.3.1",
|
||||
"deadline": "2022-01-01",
|
||||
|
|
@ -2604,6 +2609,7 @@ _Available in Fleet Premium._
|
|||
"macos_setup": {
|
||||
"bootstrap_package": "",
|
||||
"enable_end_user_authentication": false,
|
||||
"lock_end_user_info": true,
|
||||
"macos_setup_assistant": "path/to/config.json"
|
||||
}
|
||||
}
|
||||
|
|
@ -2893,6 +2899,7 @@ None.
|
|||
- [Get host's software](#get-hosts-software)
|
||||
- [Get hosts report in CSV](#get-hosts-report-in-csv)
|
||||
- [Get host's disk encryption key](#get-hosts-disk-encryption-key)
|
||||
- [Get host's Recovery Lock password](#get-hosts-recovery-lock-password)
|
||||
- [Get host's certificates](#get-hosts-certificates)
|
||||
- [Lock host](#lock-host)
|
||||
- [Unlock host](#unlock-host)
|
||||
|
|
@ -2945,7 +2952,7 @@ the `software` table.
|
|||
| after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. **Note:** Use `page` instead of `after` |
|
||||
| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. |
|
||||
| status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. |
|
||||
| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an '@', no space, etc.). |
|
||||
| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4`, and end user email addresses. |
|
||||
| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's `additional` object. This query is populated by the `additional_queries` in the `features` section of the configuration YAML. |
|
||||
| fleet_id | integer | query | _Available in Fleet Premium_. Filters to only include hosts in the specified fleet. Use `0` to filter by "Unassigned" hosts. |
|
||||
| policy_id | integer | query | The ID of the policy to filter hosts by. |
|
||||
|
|
@ -3252,7 +3259,7 @@ Response payload with the `munki_issue_id` filter provided:
|
|||
| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. |
|
||||
| after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. |
|
||||
| status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. |
|
||||
| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an '@', no space, etc.). |
|
||||
| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4`, and end user email addresses. |
|
||||
| fleet_id | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts in the specified fleet. |
|
||||
| policy_id | integer | query | The ID of the policy to filter hosts by. |
|
||||
| policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. |
|
||||
|
|
@ -4936,8 +4943,8 @@ requested by a web browser.
|
|||
| order_key | string | query | What to order results by. Can be any column in the hosts table. |
|
||||
| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. |
|
||||
| status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. |
|
||||
| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an `@`, no space, etc.). |
|
||||
| fleet_id | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts in the specified fleet. |
|
||||
| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4`, and end user email addresses. |
|
||||
| fleet_id | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts in the specified fleet. |
|
||||
| policy_id | integer | query | The ID of the policy to filter hosts by. |
|
||||
| policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. **Note: If `policy_id` is specified _without_ including `policy_response`, this will also return hosts where the policy is not configured to run or failed to run.** |
|
||||
| software_version_id | integer | query | The ID of the software version to filter hosts by. |
|
||||
|
|
@ -5005,6 +5012,60 @@ The host will only return a key if its disk encryption status is "Verified." Get
|
|||
}
|
||||
}
|
||||
```
|
||||
### Get host's Recovery Lock password
|
||||
|
||||
Retrieves the Recovery Lock password for a host.
|
||||
|
||||
The host will only return a password if its Recovery Lock password status is "Verified."
|
||||
|
||||
`GET /api/v1/fleet/hosts/:id/recovery_lock_password`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
| ---- | ------- | ---- | ---------------------------------------------------------------------- |
|
||||
| id | integer | path | **Required** The id of the host to get the Recovery Lock password for. |
|
||||
|
||||
|
||||
#### Example
|
||||
|
||||
`GET /api/v1/fleet/hosts/8/recovery_lock_password`
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```json
|
||||
{
|
||||
"host_id": 8,
|
||||
"recovery_lock_password": {
|
||||
"password": "test-123",
|
||||
"updated_at": "2026-02-01T05:31:43Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rotate host's Recovery Lock password
|
||||
|
||||
_Available in Fleet Premium_
|
||||
|
||||
Rotates the Recovery Lock password for a host.
|
||||
|
||||
`POST /api/v1/fleet/hosts/:id/recovery_lock_password/rotate`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
| ----------------------------- | ------ | ---- | -------------------------------------------------------------------------------------- |
|
||||
| id | integer | path | The host ID to rotate Recovery Lock password for. |
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/fleet/hosts/123/recovery_lock_password/rotate`
|
||||
|
||||
##### Default response
|
||||
|
||||
`204`
|
||||
|
||||
### Get host's certificates
|
||||
|
||||
|
|
@ -6123,6 +6184,7 @@ Deletes the label specified by ID.
|
|||
- [Batch-update custom OS settings (configuration profiles)](#batch-update-custom-os-settings-configuration-profiles)
|
||||
- [Update disk encryption](#update-disk-encryption)
|
||||
- [Get disk encryption status](#get-disk-encryption-status)
|
||||
- [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)
|
||||
- [Resend custom OS setting (configuration profile)](#resend-custom-os-setting-configuration-profile)
|
||||
|
|
@ -6513,7 +6575,7 @@ Resends a configuration profile for the specified host. Currently, macOS, iOS, i
|
|||
|
||||
### Update disk encryption
|
||||
|
||||
> The `PATCH /api/v1/fleet/mdm/apple/settings` API endpoint is deprecated as of Fleet 4.45. It is maintained for backward compatibility. Please use the new API endpoint below. You can view [archived docuementation for the deprecated endpoint](https://github.com/iansltx/fleet/blob/d1791518a43c9d290192dbf992bcea290c8158a3/docs/REST%20API/rest-api.md#update-disk-encryption-enforcement).
|
||||
> The `PATCH /api/v1/fleet/mdm/apple/settings` API endpoint is deprecated as of Fleet 4.45. It is maintained for backward compatibility. Please use the new API endpoint below. You can view [archived documentation for the deprecated endpoint](https://github.com/iansltx/fleet/blob/d1791518a43c9d290192dbf992bcea290c8158a3/docs/REST%20API/rest-api.md#update-disk-encryption-enforcement).
|
||||
|
||||
_Available in Fleet Premium_
|
||||
|
||||
|
|
@ -6571,12 +6633,34 @@ The summary can optionally be filtered by fleet ID.
|
|||
}
|
||||
```
|
||||
|
||||
### Update Recovery Lock
|
||||
|
||||
_Available in Fleet Premium_
|
||||
|
||||
Edit Recovery Lock password enforcement settings for eligible macOS hosts.
|
||||
|
||||
`POST /api/v1/fleet/recovery_lock_password`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
| ----------------------------- | ------ | ---- | -------------------------------------------------------------------------------------- |
|
||||
| team_id | integer | body | The team ID to apply the settings to. If omitted, settings apply to unassigned hosts. |
|
||||
| enable_recovery_lock_password | boolean | body | Whether to enforce Recovery Lock password on eligible hosts. |
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/fleet/recovery_lock_password`
|
||||
|
||||
##### Default response
|
||||
|
||||
`204`
|
||||
|
||||
### 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.
|
||||
|
||||
Get aggregate status counts of all OS settings (configuration profiles and disk encryption) enforced on hosts.
|
||||
Get aggregate status counts of all OS settings (configuration profiles, Recovery Lock passwords, and disk encryption) enforced on hosts.
|
||||
|
||||
For Fleet Premium users, the counts can
|
||||
optionally be filtered by `fleet_id`. If no `fleet_id` is specified, fleet profiles are excluded from the results (i.e., only profiles that are associated with "Unassigned" are listed).
|
||||
|
|
@ -7035,6 +7119,7 @@ _Available in Fleet Premium_
|
|||
| ------------- | ------ | ---- | -------------------------------------------------------------------------------------- |
|
||||
| fleet_id | integer | body | The fleet ID to apply the settings to. Settings are applied to "Unassigned" hosts if absent. |
|
||||
| enable_end_user_authentication | boolean | body | When enabled, require end users to authenticate with your identity provider (IdP) when they set up their new macOS hosts. |
|
||||
| lock_end_user_info | boolean | body | When enabled, 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`) |
|
||||
| require_all_software_macos | boolean | body | If set to `true`, setup will be canceled on macOS hosts if any software installs fail. |
|
||||
| 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`) |
|
||||
|
|
@ -7880,6 +7965,7 @@ _Available in Fleet Premium_
|
|||
| query | string | query | Search query keywords. Searchable fields include `name`. |
|
||||
| page | integer | query | Page number of the results to fetch. |
|
||||
| per_page | integer | query | Results per page. |
|
||||
| automation_type | string | query | Filters by automation type. Supported values are "software", "scripts", "calendar", "conditional_access", and "other". |
|
||||
|
||||
|
||||
#### Example (default usage)
|
||||
|
|
@ -7898,6 +7984,7 @@ _Available in Fleet Premium_
|
|||
"name": "Gatekeeper enabled",
|
||||
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
|
||||
"description": "Checks if gatekeeper is enabled on macOS devices",
|
||||
"type": "dynamic",
|
||||
"critical": true,
|
||||
"author_id": 42,
|
||||
"author_name": "John",
|
||||
|
|
@ -7920,6 +8007,7 @@ _Available in Fleet Premium_
|
|||
"query": "SELECT 1 FROM bitlocker_info WHERE protection_status = 1;",
|
||||
"description": "Checks if the hard disk is encrypted on Windows devices",
|
||||
"critical": false,
|
||||
"type": "dynamic",
|
||||
"author_id": 43,
|
||||
"author_name": "Alice",
|
||||
"author_email": "alice@example.com",
|
||||
|
|
@ -7941,10 +8029,11 @@ _Available in Fleet Premium_
|
|||
},
|
||||
{
|
||||
"id": 3,
|
||||
"name": "macOS - install/update Adobe Acrobat",
|
||||
"query": "SELECT 1 FROM apps WHERE name = \"Adobe Acrobat.app\" AND bundle_short_version != \"24.002.21005\";",
|
||||
"name": "macOS - Adobe Acrobat up to date",
|
||||
"query": "SELECT 1 FROM apps WHERE bundle_identifier = 'com.adobe.Reader' AND version_compare(bundle_short_version, '23.001.20687') >= 0;",
|
||||
"description": "Checks if the hard disk is encrypted on Windows devices",
|
||||
"critical": false,
|
||||
"type": "patch",
|
||||
"author_id": 43,
|
||||
"author_name": "Alice",
|
||||
"author_email": "alice@example.com",
|
||||
|
|
@ -7959,7 +8048,7 @@ _Available in Fleet Premium_
|
|||
"calendar_events_enabled": false,
|
||||
"conditional_access_enabled": false,
|
||||
"install_software": {
|
||||
"name": "Adobe Acrobat.app",
|
||||
"name": "Adobe Acrobat",
|
||||
"software_title_id": 1234
|
||||
}
|
||||
}
|
||||
|
|
@ -8104,6 +8193,7 @@ _Available in Fleet Premium_
|
|||
| fleet_id | integer | path | **Required.** Defines what fleet ID to operate on
|
||||
| query | string | query | Search query keywords. Searchable fields include `name`. |
|
||||
| merge_inherited | boolean | query | If `true`, will include inherited ("All fleets") policies in the count. |
|
||||
| automation_type | string | query | Filters by automation type. Supported values are "software", "scripts", "calendar", "conditional_access", and "other". |
|
||||
|
||||
#### Example
|
||||
|
||||
|
|
@ -8193,6 +8283,7 @@ _Available in Fleet Premium_
|
|||
"query": "SELECT 1 FROM gatekeeper WHERE assessments_enabled = 1;",
|
||||
"description": "Checks if gatekeeper is enabled on macOS devices",
|
||||
"critical": true,
|
||||
"type": "dynamic",
|
||||
"author_id": 42,
|
||||
"author_name": "John",
|
||||
"author_email": "john@example.com",
|
||||
|
|
@ -8206,9 +8297,13 @@ _Available in Fleet Premium_
|
|||
"host_count_updated_at": null,
|
||||
"calendar_events_enabled": true,
|
||||
"conditional_access_enabled": false,
|
||||
"conditional_access_bypass_enabled": false,
|
||||
"fleet_maintained": false,
|
||||
"labels_include_any": ["Macs on Sonoma"],
|
||||
"patch_software": {
|
||||
"display_name": "",
|
||||
"name": "Adobe Acrobat.app",
|
||||
"software_title_id": 1234,
|
||||
},
|
||||
"install_software": {
|
||||
"name": "Adobe Acrobat.app",
|
||||
"software_title_id": 1234
|
||||
|
|
@ -8310,7 +8405,9 @@ The semantics for creating a fleet policy are the same as for global policies, s
|
|||
| description | string | body | The policy's description. |
|
||||
| resolution | string | body | The resolution steps for the policy. |
|
||||
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
|
||||
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
|
||||
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. Critical policies can never bypass conditional access. |
|
||||
| type | string | body | The type of the policy. Options are `"dynamic"` (classic policy with an editable query) or `"patch"` (tied to `patch_software_title_id` and automatically updated to include the newest Fleet-maintained app version). If not specified, defaults to `"dynamic"`. |
|
||||
| patch_software_title_id | integer | body | _Available in Fleet Premium_. ID of the software title (Fleet-maintained only) to create a patch policy for. Required if `type` is `patch`. |
|
||||
| software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. If `software_title_id` is specified and the software has `labels_include_any` or `labels_exclude_any` defined, the policy will inherit this target in addition to specified `platform`. |
|
||||
| script_id | integer | body | _Available in Fleet Premium_. ID of script to run if the policy fails. |
|
||||
| labels_include_any | array | form | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. |
|
||||
|
|
@ -8518,9 +8615,7 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
|
|||
|
||||
_Available in Fleet Premium_
|
||||
|
||||
> **Experimental features.**
|
||||
> + The `conditional_access_bypass_enabled` setting is experimental, and will be replaced with a reference to the policy's `critical` setting in Fleet 4.83.0. To ensure a seamless upgrade, please avoid enabling bypass for policies marked `critical`.
|
||||
> + Software related features (like install software policy automation) are undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
|
||||
> **Experimental feature.** Software related features (like install software policy automation) are undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
|
||||
|
||||
`PATCH /api/v1/fleet/fleets/:fleet_id/policies/:policy_id`
|
||||
|
||||
|
|
@ -8535,7 +8630,7 @@ _Available in Fleet Premium_
|
|||
| description | string | body | The query's description. |
|
||||
| resolution | string | body | The resolution steps for the policy. |
|
||||
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
|
||||
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
|
||||
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. Critical policies can never bypass conditional access. |
|
||||
| calendar_events_enabled | boolean | body | _Available in Fleet Premium_. Whether to trigger calendar events when policy is failing. |
|
||||
| conditional_access_enabled | boolean | body | _Available in Fleet Premium_. Whether to block single sign-on for end users whose hosts fail this policy. |
|
||||
| conditional_access_bypass_enabled | boolean | body | _Available in Fleet Premium_. Additional option to allow end users to bypass conditional access for this policy for a single Okta login. This setting is ignored if `conditional_access_enabled` is `false`, if Okta conditional access is not configured, or if bypass is disabled in org settings. (Default: `true`.) |
|
||||
|
|
@ -8589,7 +8684,6 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
|
|||
"host_count_updated_at": null,
|
||||
"calendar_events_enabled": true,
|
||||
"conditional_access_enabled": false,
|
||||
"conditional_access_bypass_enabled": false,
|
||||
"fleet_maintained": false,
|
||||
"install_software": {
|
||||
"name": "Adobe Acrobat.app",
|
||||
|
|
@ -10111,10 +10205,15 @@ Get a list of all software.
|
|||
"name": "FirefoxInstall.pkg",
|
||||
"version": "125.6",
|
||||
"self_service": true,
|
||||
"patch_policy": {
|
||||
"id": 122,
|
||||
"name": "Firefox up to date"
|
||||
},
|
||||
"automatic_install_policies": [
|
||||
{
|
||||
"id": 343,
|
||||
"name": "[Install software] Firefox.app",
|
||||
"type": "dynamic",
|
||||
}
|
||||
],
|
||||
},
|
||||
|
|
@ -10477,7 +10576,8 @@ Returns information about the specified software. By default, `versions` are sor
|
|||
"automatic_install_policies": [
|
||||
{
|
||||
"id": 343,
|
||||
"name": "[Install software] Crowdstrike Agent"
|
||||
"name": "[Install software] Crowdstrike Agent",
|
||||
"type": "dynamic"
|
||||
}
|
||||
],
|
||||
"status": {
|
||||
|
|
@ -10551,6 +10651,7 @@ Returns information about the specified software. By default, `versions` are sor
|
|||
{
|
||||
"id": 345,
|
||||
"name": "[Install software] Logic Pro",
|
||||
"type": "dynamic"
|
||||
}
|
||||
],
|
||||
"status": {
|
||||
|
|
@ -11313,6 +11414,7 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
|
|||
{
|
||||
"id": 345,
|
||||
"name": "[Install software] Logic Pro",
|
||||
"type": "dynamic"
|
||||
}
|
||||
],
|
||||
"status": {
|
||||
|
|
@ -11478,6 +11580,49 @@ Add the `X-Fleet-Scripts-Encoded: base64` header line to parse `install_script`,
|
|||
}
|
||||
```
|
||||
|
||||
### Create Android web app
|
||||
|
||||
> **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
|
||||
|
||||
_Available in Fleet Premium._
|
||||
|
||||
Creates web app (web clip). This endpoint returns the application ID that can be used to [add an Android app](#add-app-store-app) to Fleet.
|
||||
|
||||
> You need to send a request of type `multipart/form-data`.
|
||||
|
||||
`POST /api/v1/fleet/software/web_apps`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
| ---- | ---- | -- | ----------- |
|
||||
| title | string | body | **Required.** It is displayed to the end user under the app icon. |
|
||||
| url | string | body | **Required.** The URL of the web app. What the end user sees when they open this app. |
|
||||
| icon | file | body | The app icon. The icon must be a PNG file and square, with dimensions of at least 512 x 512px. |
|
||||
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/fleet/software/web_apps`
|
||||
|
||||
##### Request body
|
||||
|
||||
```http
|
||||
title="Acme web app"
|
||||
url="https://app.acme.com"
|
||||
icon="app-icon-512x512.png"
|
||||
```
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```json
|
||||
{
|
||||
"app_store_id": "com.google.enterprise.webapp.x1c41e22ab611cb98"
|
||||
}
|
||||
```
|
||||
|
||||
### Download software
|
||||
|
||||
> **Experimental feature**. This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
|
||||
|
|
@ -12527,7 +12672,8 @@ _Available in Fleet Premium_
|
|||
|
||||
| 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 hosts. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#end-user-authentication). |
|
||||
| enable_end_user_authentication | boolean | If set to true, end user 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#end-user-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`) |
|
||||
|
||||
<br/>
|
||||
|
||||
|
|
|
|||
1
website/config/routes.js
vendored
1
website/config/routes.js
vendored
|
|
@ -1234,6 +1234,7 @@ module.exports.routes = {
|
|||
'GET /learn-more-about/recovery-lock-passwords': 'https://developer.apple.com/documentation/devicemanagement/set-recovery-lock-command',
|
||||
'GET /learn-more-about/startup-security-macos': 'https://support.apple.com/guide/deployment/startup-security-dep5810e849c',
|
||||
'GET /learn-more-about/unlock-ios-ipados': 'https://fleetdm.com/guides/lock-wipe-hosts#how-to-unlock-offline-ios-and-ipados-hosts',
|
||||
'GET /learn-more-about/android-web-apps-chrome-required': 'https://fleetdm.com/guides/install-app-store-apps#install-android-web-app-web-clip',
|
||||
'GET /learn-more-about/generate-fleets-agent': 'https://fleetdm.com/guides/enroll-hosts#ui',
|
||||
'GET /learn-more-about/certificates': '/guides/connect-end-user-to-wifi-with-certificate',
|
||||
'GET /learn-more-about/enrollment-profiles': 'https://developer.apple.com/documentation/devicemanagement/profile?changes=l_11_5',
|
||||
|
|
|
|||
Loading…
Reference in a new issue