search

fleetdm / fleet

Open-source platform for IT, security, and infrastructure teams. (Linux, macOS, Chrome, Windows, cloud, data center)
https://fleetdm.com
Other
3.01k stars 418 forks source link

Enrollment profile: enroll BYOD hosts to specific team #21019

Closed ddribeiro closed 1 week ago

ddribeiro commented 2 months ago

Goal

User story
As a IT admin who manually enrolls macOS, iOS, and iPadOS hosts w/ an enrollment profile before installing fleetd,
I want to specify the host's team in Fleet in the enrollment profile
so that the host gets the right configuration profiles at enrollment (I don't have to transfer these hosts to a team before installing fleetd).

Context

Public Google doc on how we arrived at solution is here.

Changes

Product

<?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://dogfood.fleetdm.com/api/fleet/ota_enrollment?enroll_secret=foo</string>
      <key>DeviceAttributes</key>
      <array>
        <string>UDID</string>
        <string>VERSION</string>
        <string>PRODUCT</string>
    <string>SERIAL</string>
      </array>
    </dict>
    <key>PayloadOrganization</key>
    <string>{{ .Organization }}</string>
    <key>PayloadDisplayName</key>
    <string>{{ .Organization }} 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>

How this affects the enrollment flows supported in Fleet:

Engineering

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

Manual testing steps

  1. Step 1
  2. Step 2
  3. Step 3

Testing notes

Confirmation

  1. [ ] Engineer (@____): Added comment to user story confirming successful completion of QA.
  2. [ ] QA (@____): Added comment to user story confirming successful completion of QA.
JoStableford commented 2 months ago

Related to a Slack conversation

ddribeiro commented 2 months ago

Customer: Apple's documentation on MDM enrollment profile: https://developer.apple.com/documentation/devicemanagement/mdm

We might want to include a CheckInURL to make this work. Currently we are only including a ServerURL in our enrollment profile. The documentation says only ServerURL is a required field and is used if CheckInURL is not specified.

noahtalerman commented 2 months ago

Hey @lukeheath, @zayhanlon, @ddribeiro and I just met w/ customer-deebradel.

We learned that this problem is a blocker for them rolling out their white label solution build on Fleet in early Sept.

I added the P2 label. I think this one we'll have to make space for this one in the current sprint (we can't wait). Next steps are design + estimation. Getting this ready for estimation will be the top priority for the MDM team.

Luke, any concerns? Happy to jump on a call if it's helpful.

lukeheath commented 2 months ago

👍 On expedited drafting.

@ddribeiro @noahtalerman Question for later: How could we have caught this sooner to avoid expedited drafting?

I'm concerned about capacity for the MDM team, so this may make more sense to send over to Endpoint Ops. Their P2s look a little lighter. Up to @georgekarrv

lukeheath commented 2 months ago

FYI This will be the last story I approve to come into the current sprint as any additional disruptions risks the entire sprint.

noahtalerman commented 2 months ago

Hey @ddribeiro heads up, I updated this issue to user story format and moved your great issue description below here for safekeeping:

Problem

As an IT admin, I'd like to deploy Fleet to macOS hosts by having end users download and install a manual enrollment profile. Once the device is enrolled in MDM, the customer can build an automation to install fleetd as a bootstrap package to complete the enrollment in 1 step to the end user.

The issue is, this method of enrollment always assigns the host to "No team" in Fleet. This means a customer will have to manually assign devices to teams after they are enrolled. This can cause confusion and lead to a disorganized Fleet instance if many devices enroll at once.

What have you tried?

Fleet deploys a configuration profile named Fleetd configuration that contains a payload that includes the EnrollmentSecret based on the Team the host is assigned to.

I tried to create a custom MDM enrollment profile that contains this team specific payload, hoping it would assign my host to the correct team upon enrollment. Unfortunately, this does not work as it seems the profile is pushed based on Team assignment on the server. Fleet does not read the contents of the payload to determine Team membership.

Potential solutions

Fleet's current manual enrollment profile contains a ServerURL key directing the host to the MDM server:

<key>ServerURL</key>
<string>https://dogfood.fleetdm.com/mdm/apple/mdm</string>

A potential solution might be to build a team specific enrollment profile that has the current ServerURL with query parameters with Team specific information like:

<key>ServerURL</key>
<string>https://dogfood.fleetdm.com/mdm/apple/mdm?team_id=1</string>

Fleet might be able to assign the device to the proper team based on the query string in the URL. I believe other MDM's might do something similar but I'm not sure how this is achieved in practice.

What is the expected workflow as a result of your proposal?

As a result of this proposal, a Fleet admin would create Teams to organize their hosts in accordance with Fleet's best practices. Then, they could enroll their hosts simply by distributing Team specific MDM enrollment profiles to their end users to install. The host would immediately be assigned to the desired Team in Fleet. Fleet would then install `fleetd` as a bootstrap package via an MDM command to complete the enrollment. This workflow is not possible today as installing the manual MDM enrollment profile before `fleetd` is installed always assigned the host to "No Team"
noahtalerman commented 2 months ago

How this affects the enrollment flows supported in Fleet:

Assuming we go w/ the SeverURL approach, I updated the issue description with my understanding on the above.

  • Automatic (DEP):

    • (???) Use enroll secret in “fleetd configuration” profile

Hey @roperzh when you get the chance, I'm still struggling to understand the "fleet configuration" profile in the automatic enrollment flow. Recorded a Loom here.

Can you please take a look? Thanks!

noahtalerman commented 2 months ago

@georgekarrv, @roperzh, and @ddribeiro I updated the issue description w/ the plan we discussed.

Please let me know if I'm missing anything.

Still TODO:

cc @lukeheath

roperzh commented 2 months ago

pasting from Slack:

I was thinking about OTA https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/OTASecurity/OTASecurity.html#//[…]SW1 The diagram looks scary but we're doing 90% of it (just as part of normal enrollment). The new steps would be 4 and 5 under "Phase 1", where we could associate the host to the right team. This is what I have seen other MDM solutions do

noahtalerman commented 1 month ago

Update on this story.

I'm getting the feeling that we want to draft/design "Enroll BYOD iOS/iPadOS hosts" (#19448) before we start writing code for this story.

I'm confident we're headed in the right direction (solution in the issue description) but it's worth taking the extra time to connect the pieces.

The plan is to have designs for #19448 ready by Weds design review so we can estimate that day (2024-08-14).

@roperzh I added you to that call to bounce some technical questions.

Heads up @zayhanlon that this might affect our ability to ship this [customer-deebradel](https://github.com/fleetdm/fleet/labels/customer-deebradel) blocker as part of the current release (2024-08-26) unless we pause other work. Will give you a more detailed update when we estimate on Weds.

cc @georgekarrv

roperzh commented 1 month ago

@marko-lisica for design review today:

  1. Here's a video that shows the end user experience.
  2. I noticed a gotcha while filming it: enroll secrets can contain characters that are invalid XML, and need to be escaped. This affects the IT admin experience if they're building a profile themselves.
georgekarrv commented 1 month ago

Hey team! Please add your planning poker estimate with Zenhub @dantecatalfamo @gillespi314 @jahzielv @mna @roperzh

roperzh commented 1 month ago

This is how this flow looks like e2e:

https://github.com/user-attachments/assets/130f95da-f55a-4465-b3ba-55d87f3658d3

Regarding the extra prompts due to the profile being unverified, per @marko-lisica on Slack:

image

PezHub commented 3 weeks ago

QA Notes: confirmed admins can enroll BYOD hosts to specific teams by leveraging enrollment urls generated from the UI from the desired team page.

Steps:

  1. Navigate to the Hosts tab in the FleetUI
  2. Choose desired team from the drop down list
  3. Click add hosts button in the top right
  4. click the iOS & iPadOS tab and copy the URL
  5. Enroll the mobile device using that enroll url
  6. observe once enrolled in Fleet, the device gets added to the correct team Screenshot 2024-09-13 at 3 01 21 PM

macOS - I confirmed the copy change when Turning on MDM. the additional steps (5 & 6) to enter your password have been added.

noahtalerman commented 1 week ago
  • [ ] Reference documentation changes: Update reference docs or create a new page on if/how Fleet uses all the keys in the enrollment profile and what the best practice is for modifying the keys.
    • UPDATE: Instead, let's move the new API endpoint to the REST API docs b/c it's intended for use in automations (we don't want to break it)

TODO @noahtalerman

UPDATE: PR is here: https://github.com/fleetdm/fleet/pull/22457

fleet-release commented 1 week ago

Enrollment profile, Guides devices to their team, Smooth as river stream.