diff --git a/articles/config-less-fleetd-agent-deployment.md b/articles/config-less-fleetd-agent-deployment.md index eb37159fdcf5..2ca3b5cd7c93 100644 --- a/articles/config-less-fleetd-agent-deployment.md +++ b/articles/config-less-fleetd-agent-deployment.md @@ -4,7 +4,7 @@ Deploying Fleet's agent across a diverse range of devices often involves the crucial step of enrolling each device. Traditionally, this involves [packaging](https://fleetdm.com/docs/using-fleet/fleetd#packaging) `fleetd` with configuration including the enroll secret and server URL. While effective, an alternative offers more flexibility in your deployment process. This guide introduces a different approach for deploying Fleet's agent without embedding configuration settings directly into `fleetd`. Ideal for IT administrators who prefer to generate a single package and maintain greater control over the distribution of enrollment secrets and server URLs, this method simplifies the enrollment process across macOS and Windows hosts. -Emphasizing adaptability and convenience, this approach allows for a more efficient way to manage device enrollments. Let’s dive into how to deploy Fleet's agent using this alternative method, ensuring a more open and flexible deployment process. +This approach emphasizes adaptability and convenience and allows for a more efficient way to manage device enrollments. Let’s explore how to deploy Fleet's agent using this alternative method, ensuring a more open and flexible deployment process. ## For macOS: @@ -44,6 +44,18 @@ fleetctl package --type=pkg --use-system-configuration --fleet-desktop PayloadVersion 1 + + EndUserEmail + END_USER_EMAIL_HERE + PayloadIdentifier + com.fleetdm.fleet.mdm.apple.mdm + PayloadType + com.apple.mdm + PayloadUUID + 29713130-1602-4D27-90C9-B822A295E44E + PayloadVersion + 1 + PayloadDisplayName Fleetd configuration @@ -56,11 +68,38 @@ fleetctl package --type=pkg --use-system-configuration --fleet-desktop PayloadVersion 1 PayloadDescription - Default configuration for the fleetd agent. + Configuration for the fleetd agent. ``` +You can optionally specify the `END_USER_EMAIL` that will be added to the host's [human-device mapping](https://fleetdm.com/docs/rest-api/rest-api#get-human-device-mapping): + +```xml + + + + + PayloadContent + + ... + + EndUserEmail + END_USER_EMAIL + PayloadIdentifier + com.fleetdm.fleet.mdm.apple.mdm + PayloadType + com.apple.mdm + PayloadUUID + 29713130-1602-4D27-90C9-B822A295E44E + PayloadVersion + 1 + + + ... + + +``` ## For Windows: diff --git a/docs/Contributing/API-for-contributors.md b/docs/Contributing/API-for-contributors.md index 074c3338b4c2..64caabc4cbf6 100644 --- a/docs/Contributing/API-for-contributors.md +++ b/docs/Contributing/API-for-contributors.md @@ -549,7 +549,6 @@ The MDM endpoints exist to support the related command-line interface sub-comman - [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) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 0a760c32d5fc..a42ec1865781 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -5573,6 +5573,7 @@ solely on the response status code returned by this endpoint. ``` ###### Example response body + ```xml @@ -5720,6 +5721,7 @@ Get aggregate status counts of profiles for to macOS and Windows hosts that are - [Set custom MDM setup enrollment profile](#set-custom-mdm-setup-enrollment-profile) - [Get custom MDM setup enrollment profile](#get-custom-mdm-setup-enrollment-profile) - [Delete custom MDM setup enrollment profile](#delete-custom-mdm-setup-enrollment-profile) +- [Get Over-the-Air (OTA) enrollment profile](#get-over-the-air-ota-enrollment-profile) - [Get manual enrollment profile](#get-manual-enrollment-profile) - [Upload a bootstrap package](#upload-a-bootstrap-package) - [Get metadata about a bootstrap package](#get-metadata-about-a-bootstrap-package) @@ -5827,10 +5829,83 @@ Deletes the custom MDM setup enrollment profile assigned to a team or no team. `Status: 204` +### Get Over-the-Air (OTA) enrollment profile + +`GET /api/v1/fleet/enrollment_profiles/ota` + +The returned value is a signed `.mobileconfig` OTA enrollment profile. Install this profile on macOS, iOS, or iPadOS hosts to enroll them to a specific team in Fleet and turn on MDM features. + +To enroll macOS hosts, turn on MDM features, and add [human-device mapping](#get-human-device-mapping), install the [manual enrollment profile](#get-manual-enrollment-profile) instead. + +Learn more about OTA profiles [here](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/OTASecurity/OTASecurity.html). + +#### 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 + + + + + PayloadContent + + URL + https://foo.example.com/api/fleet/ota_enrollment?enroll_secret=foobar + DeviceAttributes + + UDID + VERSION + PRODUCT + SERIAL + + + PayloadOrganization + Acme Inc. + PayloadDisplayName + Acme Inc. enrollment + PayloadVersion + 1 + PayloadUUID + fdb376e5-b5bb-4d8c-829e-e90865f990c9 + PayloadIdentifier + com.fleetdm.fleet.mdm.apple.ota + PayloadType + Profile Service + + +``` + + ### Get manual enrollment profile Retrieves an unsigned manual enrollment profile for macOS hosts. Install this profile on macOS hosts to turn on MDM features manually. +To add [human-device mapping](#get-human-device-mapping), add the end user's email to the enrollment profle. Learn how [here](https://fleetdm.com/guides/config-less-fleetd-agent-deployment#basic-article). + `GET /api/v1/fleet/enrollment_profiles/manual` ##### Example