Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

API docs: OTA enrollment profile #22457

Merged
merged 8 commits into from
Oct 1, 2024
Merged

API docs: OTA enrollment profile #22457

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ed5faad
Bring in OTA
noahtalerman Sep 27, 2024
f41fd8b
Add more
noahtalerman Sep 27, 2024
aaa4947
Fix spacing
noahtalerman Sep 27, 2024
639480b
Update config-less-fleetd-agent-deployment.md
noahtalerman Sep 27, 2024
989ae0c
Update config-less-fleetd-agent-deployment.md
noahtalerman Sep 27, 2024
d9f2d6a
Grammar and phrasing tweaks
spokanemac Sep 27, 2024
f814b79
Update docs/REST API/rest-api.md
rachaelshaw Sep 27, 2024
b1189c5
Update rest-api.md
noahtalerman Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 41 additions & 2 deletions articles/config-less-fleetd-agent-deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -44,6 +44,18 @@ fleetctl package --type=pkg --use-system-configuration --fleet-desktop
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
<dict>
<key>EndUserEmail</key>
<string>END_USER_EMAIL_HERE</string>
<key>PayloadIdentifier</key>
<string>com.fleetdm.fleet.mdm.apple.mdm</string>
<key>PayloadType</key>
<string>com.apple.mdm</string>
<key>PayloadUUID</key>
<string>29713130-1602-4D27-90C9-B822A295E44E</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</array>
<key>PayloadDisplayName</key>
<string>Fleetd configuration</string>
Expand All @@ -56,11 +68,38 @@ fleetctl package --type=pkg --use-system-configuration --fleet-desktop
<key>PayloadVersion</key>
<integer>1</integer>
<key>PayloadDescription</key>
<string>Default configuration for the fleetd agent.</string>
<string>Configuration for the fleetd agent.</string>
</dict>
</plist>
```

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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array>
...
<dict>
<key>EndUserEmail</key>
<string>END_USER_EMAIL</string>
<key>PayloadIdentifier</key>
<string>com.fleetdm.fleet.mdm.apple.mdm</string>
<key>PayloadType</key>
<string>com.apple.mdm</string>
<key>PayloadUUID</key>
<string>29713130-1602-4D27-90C9-B822A295E44E</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</array>
...
</dict>
</plist>
```

## For Windows:

Expand Down
1 change: 0 additions & 1 deletion docs/Contributing/API-for-contributors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
77 changes: 77 additions & 0 deletions docs/REST API/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5573,6 +5573,7 @@ solely on the response status code returned by this endpoint.
```

###### Example response body

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -5827,10 +5829,85 @@ 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 turn 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.
Copy link
Member

Choose a reason for hiding this comment

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

@noahtalerman should this be either "turn on" or "enroll"? Or is "turn enroll" some special terminology?

Copy link
Member Author

Choose a reason for hiding this comment

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

Whoops! That's a typo. This should be "enroll." I fixed it.


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.
rachaelshaw marked this conversation as resolved.
Show resolved Hide resolved

##### 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>
```


### 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
Expand Down
Loading