Reference docs for v4.57.0 (#22319)

Co-authored-by: Rachael Shaw <r@rachael.wtf> Co-authored-by: mostlikelee <tim@mostlikelee.com> Co-authored-by: Tim Lee <timlee@fleetdm.com> Co-authored-by: Marko Lisica <markol.lisica@gmail.com> Co-authored-by: Ian Littman <iansltx@gmail.com> Co-authored-by: Luke Heath <luke@fleetdm.com>
fleetdm · Sep 23, 2024 · adf19c4 · adf19c4
1 parent dd583f0
commit adf19c4
Show file tree

Hide file tree

Showing 4 changed files with 413 additions and 23 deletions.
diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md
@@ -6,14 +6,16 @@ To learn how to set up a GitOps workflow see the [Fleet GitOps repo](https://git
 
 ## File structure
 
-- `default.yml`- File where you define the queries, policies, controls, and agent options for all hosts. If you're using Fleet Premium, this file updates queries and policies that run on all hosts ("All teams"). Controls and agent options are defined for hosts on "No team."
-- `teams/` - Folder where you define your teams in Fleet. These `teams/team-name.yml` files define the controls, queries, policies, and agent options for hosts assigned to the specified team. Teams are available in Fleet Premium.
+- `default.yml` - File where you define the queries, policies and agent options for all hosts. If you're using Fleet Premium, this file updates queries and policies that run on all hosts ("All teams"). 
+- `teams/no-team.yml` - File where you define the policies, controls, and software for hosts on "No team". Available in Fleet Premium. 
+- `teams/` - Folder where you define your teams in Fleet. These `teams/team-name.yml` files define the controls, queries, policies, software, and agent options for hosts assigned to the specified team. Available in Fleet Premium.
 - `lib/` - Folder where you define policies, queries, configuration profiles, scripts, and agent options. These files can be referenced in top level keys in the `default.yml` file and the files in the `teams/` folder.
 - `.github/workflows/workflow.yml` - The GitHub workflow file where you can add [environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow).
 
-The following files are responsible for running the GitHub action. Most users don't need to edit these files.
+The following files are responsible for running the GitHub action or GitLab CI/CD. Most users don't need to edit these files.
 - `gitops.sh` - The bash script that applies the latest configuration to Fleet. This script is used in the GitHub action file.
 - `.github/gitops-action/action.yml` - The GitHub action that runs `gitops.sh`. This action is used in the GitHub workflow file. It can also be used in other workflows.
+- `.gitlab-ci.yml` - The GitLab CI/CD file that applies the latest configuration to Fleet.
 
 ## Configuration options
 
@@ -24,8 +26,7 @@ name: # Only teams/team-name.yml. To edit a team's name, change `name` but don't
 policies:
 queries:
 agent_options:
-controls:
-software:
+controls: # Can be defined in teams/no-team.yml too.
 org_settings: # Only default.yml
 team_settings: # Only teams/team-name.yml
 ```
@@ -40,6 +41,8 @@ team_settings: # Only teams/team-name.yml
 ### policies
 
 Polcies can be specified inline in your `default.yml` file or `teams/team-name.yml` files. They can also be specified in separate files in your `lib/` folder.
+Policies defined in `default.yml` run on **all** hosts.
+Policies defined in `teams/no-team.yml` run on hosts that belong to "No team".
 
 #### Options
 
@@ -81,9 +84,16 @@ policies:
   platform: darwin
   critical: false
   calendar_event_enabled: false
+- name: Firefox on Linux installed and up to date
+  platform: linux
+  description: "This policy checks that Firefox is installed and up to date."
+  resolution: "Install Firefox version 129.0.2 or higher."
+  query: "SELECT 1 FROM deb_packages WHERE name = 'firefox' AND version_compare(version, '129.0.2') >= 0;"
+  install_software:
+    package_path: "../lib/linux-firefox.deb.package.yml"
 ```
 
-`default.yml` or `teams/team-name.yml`
+`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml`
 
 ```yaml
 policies:
@@ -210,6 +220,8 @@ queries:
 
 The `controls` section allows you to configure scripts and device management (MDM) features in Fleet.
 
+Controls for hosts that are in "No team" can be defined in `default.yml` or in `teams/no-team.yml` (but not in both files).
+
 - `scripts` is a list of paths to macOS, Windows, or Linux scripts.
 - `windows_enabled_and_configured` specifies whether or not to turn on Windows MDM features (default: `false`). Can only be configured for all teams (`default.yml`).
 - `enable_disk_encryption` specifies whether or not to enforce disk encryption on macOS and Windows hosts (default: `false`).
@@ -304,11 +316,15 @@ Can only be configure for all teams (`default.yml`).
 > **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.
 
 The `software` section allows you to configure packages and Apple App Store apps that you want to install on your hosts.
+Software for hosts that belong to "No team" have to be defined in `teams/no-team.yml`.
+Software can also be specified in separate files in your `lib/` folder.
 
 - `packages` is a list of software packages (.pkg, .msi, .exe, or .deb) and software specific options.
 - `app_store_apps` is a list of Apple App Store apps.
 
-##### Example
+#### Example
+
+##### Inline
 
 ```yaml
 software:
@@ -326,20 +342,49 @@ software:
    - app_store_id: '1091189122'
 ```
 
-#### packages
+##### packages
 
 - `url` specifies the URL at which the software is located. Fleet will download the software and upload it to S3 (default: `""`).
 - `install_script.path` specifies the command Fleet will run on hosts to install software. The [default script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) is dependent on the software type (i.e. .pkg).
 - `pre_install_query.path` is the osquery query Fleet runs before installing the software. Software will be installed only if the [query returns results](https://fleetdm.com/tables/account_policy_data) (default: `""`).
 - `post_install_script.path` is the script Fleet will run on hosts after intalling software (default: `""`).
 - `self_service` specifies whether or not end users can install from **Fleet Desktop > Self-service**.
 
-#### app_store_apps
+##### app_store_apps
 
 - `app_store_id` is the ID of the Apple App Store app. You can find this at the end of the app's App Store URL. For example, "Bear - Markdown Notes" URL is "https://apps.apple.com/us/app/bear-markdown-notes/id1016366447" and the `app_store_id` is `1016366447`.
 
 > Make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string. 
 
+##### Separate file
+
+`lib/software-name.package.yml`:
+
+```yaml
+url: https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe
+install_script:
+  path: ../lib/software/tailscale-install-script.ps1
+self_service: true
+```
+
+`lib/software/tailscale-install-script.ps1`
+
+```yaml
+$exeFilePath = "${env:INSTALLER_PATH}"
+$installProcess = Start-Process $exeFilePath `
+  -ArgumentList "/quiet /norestart" `
+    -PassThru -Verb RunAs -Wait
+```
+
+`default.yml`, `teams/team-name.yml`, or `teams/no-team.yml`
+
+```yaml
+software:
+  packages:
+    - path: ../lib/software-name.package.yml
+# path is relative to default.yml or teams/team-name.yml
+```
+
 ### org_settings and team_settings
 
 #### features
@@ -640,6 +685,19 @@ Once the IdP settings are configured, you can use the [`controls.macos_setup.ena
 
 Can only be configured for all teams (`org_settings`).
 
+##### end_user_authentication
+
+The `end_user_authentication` section lets you define the identity provider (IdP) settings used for end user authentication during Automated Device Enrollment (ADE). Learn more about end user authentication in Fleet [here](https://fleetdm.com/guides/macos-setup-experience#end-user-authentication-and-eula).
+
+Once the IdP settings are configured, you can use the [`controls.macos_setup.enable_end_user_authentication`](#macos_setup) key to control the end user experience during ADE.
+
+- `idp_name` is the human-friendly name for the identity provider that will provide single sign-on authentication (default: `""`).
+- `entity_id` is the entity ID: a Uniform Resource Identifier (URI) that you use to identify Fleet when configuring the identity provider. It must exactly match the Entity ID field used in identity provider configuration (default: `""`).
+- `metadata` is the metadata (in XML format) provided by the identity provider. (default: `""`)
+- `metadata_url` is the URL that references the identity provider metadata. Only one of  `metadata` or `metadata_url` is required (default: `""`).
+
+Can only be configured for all teams (`org_settings`).
+
 <meta name="title" value="YAML files">
 <meta name="description" value="Reference documentation for Fleet's GitOps workflow. See examples and configuration options.">
 <meta name="pageOrderInSection" value="1500">
diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md
@@ -543,11 +543,13 @@ The MDM endpoints exist to support the related command-line interface sub-comman
 - [Batch-apply MDM custom settings](#batch-apply-mdm-custom-settings)
 - [Initiate SSO during DEP enrollment](#initiate-sso-during-dep-enrollment)
 - [Complete SSO during DEP enrollment](#complete-sso-during-dep-enrollment)
+- [Over the air enrollment](#over-the-air-enrollment)
 - [Preassign profiles to devices](#preassign-profiles-to-devices)
 - [Match preassigned profiles](#match-preassigned-profiles)
 - [Get FileVault statistics](#get-filevault-statistics)
 - [Upload VPP content token](#upload-vpp-content-token)
 - [Disable VPP](#disable-vpp)
+- [Get an over the air (OTA) enrollment profile](#get-an-over-the-air-ota-enrollment-profile)
 
 
 ### Generate Apple Business Manager public key (ADE)
@@ -1029,6 +1031,34 @@ If the credentials are valid, the server redirects the client to the Fleet UI. T
 - `profile_token` is a token that can be used to download an enrollment profile (.mobileconfig).
 - `eula_token` (optional) if an EULA was uploaded, this contains a token that can be used to view the EULA document.
 
+### Over the air enrollment
+
+This endpoint handles over the air (OTA) MDM enrollments
+
+`POST /api/v1/fleet/ota_enrollment`
+
+#### Parameters
+
+| Name                | Type   | In   | Description                                                                                                                                                                                                                                                                                        |
+| ------------------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| enroll_secret       | string | url  | **Required** Assigns the host to a team with a matching enroll secret                                                                                                                                                                                                                 |
+| XML device response | XML    | body | **Required**. The XML response from the device. Fields are documented [here](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/ConfigurationProfileExamples/ConfigurationProfileExamples.html#//apple_ref/doc/uid/TP40009505-CH4-SW7) |
+
+> Note: enroll secrets can contain special characters. Ensure any special characters are [properly escaped](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
+
+#### Example
+
+`POST /api/v1/fleet/ota_enrollment?enroll_secret=0Z6IuKpKU4y7xl%2BZcrp2gPcMi1kKNs3p`
+
+##### Default response
+
+`Status: 200`
+
+Per [the spec](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/Introduction/Introduction.html#//apple_ref/doc/uid/TP40009505-CH1-SW1), the response is different depending on the signature of the XML device response:
+
+- If the body is signed with a certificate that can be validated by our root SCEP certificate, it returns an enrollment profile.
+- Otherwise, it returns a SCEP payload.
+
 ### Preassign profiles to devices
 
 _Available in Fleet Premium_
@@ -1453,12 +1483,14 @@ NOTE: when updating a policy, team and platform will be ignored.
       "name": "new policy",
       "description": "This will be a new policy because a policy with the name 'new policy' doesn't exist in Fleet.",
       "query": "SELECT * FROM osquery_info",
+      "team": "No team",
       "resolution": "some resolution steps here",
       "critical": false
     },
     {
       "name": "Is FileVault enabled on macOS devices?",
       "query": "SELECT 1 FROM disk_encryption WHERE user_uuid IS NOT “” AND filevault_status = ‘on’ LIMIT 1;",
+      "team": "Workstations",
       "description": "Checks to make sure that the FileVault feature is enabled on macOS devices.",
       "resolution": "Choose Apple menu > System Preferences, then click Security & Privacy. Click the FileVault tab. Click the Lock icon, then enter an administrator name and password. Click Turn On FileVault.",
       "platform": "darwin",
@@ -3320,7 +3352,24 @@ If both `team_id` and `team_name` parameters are included, this endpoint will re
 
 ##### Default response
 
-`Status: 204`
+`Status: 200`
+
+```json
+{
+  "packages": [
+    {
+      "team_id": 3,
+      "software_title_id": 6690,
+      "url": "https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe"
+    },
+    {
+      "team_id": 3,
+      "software_title_id": 10412,
+      "url": "https://ftp.mozilla.org/pub/firefox/releases/129.0.2/win64/en-US/Firefox%20Setup%20129.0.2.msi"
+    }
+  ]
+}
+```
 
  ### Run live script
 
@@ -3420,3 +3469,71 @@ Content-Disposition: attachment
 Content-Length: <length>
 Body: <blob>
 ```
+
+### Get an over the air (OTA) enrollment profile
+
+`GET /api/v1/fleet/enrollment_profiles/ota`
+
+The returned value is a signed `.mobileconfig` OTA profile.
+
+#### Parameters
+
+| Name              | Type    | In    | Description                                                                      |
+|-------------------|---------|-------|----------------------------------------------------------------------------------|
+| enroll_secret     | string  | query | **Required**. The enroll secret of the team this host will be assigned to.       |
+
+#### Example
+
+`GET /api/v1/fleet/enrollment_profiles/ota?enroll_secret=foobar`
+
+##### 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/x-apple-aspen-config; charset=urf-8
+  Content-Disposition: attachment;filename="fleet-mdm-enrollment-profile.mobileconfig"
+  X-Content-Type-Options: nosniff
+```
+
+###### Example response body
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple Inc//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>PayloadContent</key>
+    <dict>
+      <key>URL</key>
+      <string>https://foo.example.com/api/fleet/ota_enrollment?enroll_secret=foobar</string>
+      <key>DeviceAttributes</key>
+      <array>
+        <string>UDID</string>
+        <string>VERSION</string>
+        <string>PRODUCT</string>
+	<string>SERIAL</string>
+      </array>
+    </dict>
+    <key>PayloadOrganization</key>
+    <string>Acme Inc.</string>
+    <key>PayloadDisplayName</key>
+    <string>Acme Inc. enrollment</string>
+    <key>PayloadVersion</key>
+    <integer>1</integer>
+    <key>PayloadUUID</key>
+    <string>fdb376e5-b5bb-4d8c-829e-e90865f990c9</string>
+    <key>PayloadIdentifier</key>
+    <string>com.fleetdm.fleet.mdm.apple.ota</string>
+    <key>PayloadType</key>
+    <string>Profile Service</string>
+  </dict>
+</plist>
+```