Implement API endpoint for MDM manual enrollment profile download

ghernandez345 commented 1 year ago

We need an endpoint that enables the downloading of an enrolment profile for manual MDM enrolment.

Requirements

create an endpoint that enables downloading of an enrolment profile

Design

UI

https://www.figma.com/file/qbjRu8jf01BzEfdcge1dgu/Fleet-style-guide-2022-(WIP)?node-id=213%3A30333&t=YR1JSBx88ugXllm2-0

Tasks

1

[x] Implement new API endpoint to download the enrollment profile
- GET /fleet/device/{token}/mdm/apple/manual_enrollment_profile (rationale: the prefix up to /mdm is consistent with all device-authenticated endpoints, and then it's the structure used for mdm-related endpoints. Maybe we could do without /apple/ and auto-detect based on the device's OS, but the My Device page already has to know this as the callout is only shown if the host is macos for now - see figma https://www.figma.com/file/hdALBDsrti77QuDNSzLdkx/%F0%9F%9A%A7-Fleet-EE-(dev-ready%2C-scratchpad)?node-id=10058%3A317839&t=HxIvSLi6gH4EJE59-0).
- Headers must be set so that the browser triggers downloading of the response (see e.g. GET /fleet/hosts/report, we add a Content-Disposition header and some other headers such as Content-Type).
- The enrollment profile is generated in server/service/apple_mdm.go, function generateEnrollmentProfileMobileconfig.
- This is to be called from the "My Device" page in Fleet Desktop, so this is a device-token-authenticated endpoint.

2

[x] Document the new API
- This is a device-token-authenticated route, so it should be documented along with other such routes in docs/Contributing/API-for-contributors.md

ghernandez345 commented 1 year ago

@mna not much detail here but i dont think this has many requirements other than having an endpoint that sends back an enrolment profile.

mna commented 1 year ago

@lukeheath @noahtalerman Couple questions to clarify the specs:

Is there an equivalent ticket (even epic) that covers uploading/setting the enrollment profile? I haven't found one, closest thing I've seen is https://github.com/fleetdm/fleet/issues/8360 but that's for the macos profile after the host is enrolled, I believe - that is, we will have 2 profiles, one for enrollment and one for the settings to enforce. As it stands, I don't know where the enrollment profile to download should be read from.
Is there any special authorization associated with that endpoint? I'm guessing not, because every user should be able to download the enrollment profile to manually enroll their host, so as long as the request is authenticated it should be allowed?

mna commented 1 year ago

@lukeheath @noahtalerman

nevermind regarding 1. above, I found the enrollment profile generation in the prototype code, it's in server/service/apple_mdm.go, function generateEnrollmentProfileMobileconfig.

lukeheath commented 1 year ago

@mna

Is there any special authorization associated with that endpoint? I'm guessing not, because every user should be able to download the enrollment profile to manually enroll their host, so as long as the request is authenticated it should be allowed?

Correct, this is my understanding. Let's spec with this assumption and confirm with Noah when this ticket is estimated.

roperzh commented 1 year ago

That's correct, having the URL with the correct token is what "authorizes" you to access the profile.

@mna while some settings can be tweaked, I don't think we want to give the user any control on that (at least for now.) The current settings we're sending are also OK.

roperzh commented 1 year ago

@lukeheath @noahtalerman @mna in regards to my previous comment 👆

Authentication

The request to get the profile needs to be authenticated in some way, my previous comment assumes that the IT admin will have the ability to share a URL to download the token, but on second thought it actually depends on the workflows we want to support:

If we will only allow manual enrollment through the "My Device" page, then the URL doesn't need a special token (we use the device token, similarly to all other requests on that page)
If we want to support admins sharing a link to download the profile, then we need to keep the token in the URL

Generation

Currently, the IT admin has to run at some point the following command to create the profile:

$ fleetctl apple-mdm enrollment-profiles create-manual

For manual profiles, this is just to generate the token (DEP profiles are different), so if we just want to support workflow 1 above, maybe we could also skip this step?

lukeheath commented 1 year ago

@roperzh I know we will want item 1, manual enrollment via the "My Device" page. I have yet to see any flows that indicate the admin shares a link to download the profile, but let's confirm with @zhumo. He will be back on Friday this week. Martin will be back next Monday.

zhumo commented 1 year ago

@lukeheath @roperzh my understanding is that the admin should ask users to install Fleetd w/ Fleet Desktop enabled.

mna commented 1 year ago

@roperzh @lukeheath Yeah from the figma associated with the UI part of this ticket, the manual enrollment is via the "My Device" page so it would be the case 1. in Roberto's comment. I'll go ahead and estimate+start working on this ticket for the "My Device" scenario.

mna commented 1 year ago

@noahtalerman One thing I want to point out, to generate the manual enrollment profile we need the SCEP challenge key (https://github.com/fleetdm/fleet/blob/main/server/service/apple_mdm.go#L807-L818). AFAIK, we haven't covered this configuration option for the "official" MDM feature - it still uses the configuration option that was created for the prototype (the yaml key is mdm_apple.scep.challenge).

Wanted to let you know because for the official feature, we've used mdm instead of mdm_apple as parent key, so it would likely need to be changed to mdm.apple_scep_challenge?

@roperzh correct me if I'm wrong regarding the scep challenge being required?

roperzh commented 1 year ago

@mna that sounds correct, the plan is to get rid of that config option and use dynamic SCEP challenges (#8477)

mna commented 1 year ago

@roperzh @noahtalerman oh gotcha, thanks Roberto! So my understanding is:

We will eventually remove the scep challenge fleet flag, we don't need to rename it/migrate it to the "new" MDM config flag format
The challenge will eventually be dynamically generated and the manual enrollment profile adjusted accordingly
There's already a ticket that covers this change, so the current ticket can be considered done when the PR is merged
Until that dynamic scep challenge ticket is addressed, it's ok for now to continue using the scep challenge prototype flag in the enrollment profile

roperzh commented 1 year ago

that matches my understanding, thanks for the summary!

noahtalerman commented 1 year ago

@roperzh @mna my understanding is that the user won't have to configure a SCEP challenge. Is this still the case?

roperzh commented 1 year ago

@noahtalerman yes, that's correct. It'll be automatically generated

mna commented 1 year ago

@noahtalerman regarding what happens with the profile once downloaded (related to its content-type of application/x-apple-aspen-config that Apple knows about), @RachelElysia was able to demo it to me now that the frontend is calling the endpoint, and what it does is:

it downloads the profile under the name we agreed upon in the PR
when you click on the profile, a notification pops up telling the user to check their system settings/profile if they want to install it
we still have to do that manually (open settings, find "profile" section), and then we can do something about the profile (in our case, the profile was invalid, but that may be due to using a test environment with fake scep certificates and all, we'll have a better idea of whether or not we need to tweak the profile's content in QA/dogfood).

So all in all I think it does a bit of a better job than what we expected (the user doesn't have to deal with the file beyond clicking on it after download), but not as good as I thought it would (it just pops a notification, you have to manually navigate to the settings/profile window to continue).

noahtalerman commented 1 year ago

we still have to do that manually (open settings, find "profile" section)

the user doesn't have to deal with the file beyond clicking on it after download

@mna got it 👍 This is what I've seen too. Thanks for the follow up.

it just pops a notification, you have to manually navigate to the settings/profile window to continue

Right. The directions on the My device page (screenshot below) are for walking the end user through this part. Curious, if you've had a chance to see this screen, to hear how this felt as an end user.

Screenshot 2023-01-16 at 3 14 06 PM

noahtalerman commented 1 year ago

Curious, if you've had a chance to see this screen, to hear how this felt as an end user.

cc @RachelElysia

mna commented 1 year ago

@noahtalerman @RachelElysia those instructions look great, as I recall it that's exactly what Rachel did to get to it (although a lot of scrolling had to be done to access the "Profiles" section, despite searching for it in section settings? Rachel might be able to better describe/show what happened there).

One nit on step 4, would it be worth mentioning "Enter your macOS password"? I.e. not your Fleet password. Might not be obvious to all users?

noahtalerman commented 1 year ago

One nit on step 4, would it be worth mentioning "Enter your macOS password"? I.e. not your Fleet password. Might not be obvious to all users?

@mna ah, interesting. These instructions are for end users only (My device page). End users won't have Fleet passwords. I'm curious if this changes your thinking...

mna commented 1 year ago

@noahtalerman

These instructions are for end users only (My device page). End users won't have Fleet passwords.

Oh! That's true, sorry, I did not think that through.

fleet-release commented 1 year ago

Gain control with ease
Device enrollment profile
Fleet's helping hands

fleetdm / fleet