empayre/fleet
14
0
Fork 0
mirror of https://github.com/empayre/fleet.git synced 2024-11-06 08:55:24 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

MDM docs: Add end user migration workflow (#13261)

Browse Source 
- Add instructions for setting up end user migration workflow
- Break out a separate section to default migration workflow for
automatically enrolled (DEP hosts)
- Break out separate end user instructions for manually enrolled hosts,
automatically enrolled hosts - default migration workflow, and
automatically enrolled hosts - end user migration workflow.
This commit is contained in:
Noah Talerman 2023-08-15 22:32:46 -04:00 committed by GitHub
parent 08af35d294
commit a36cb76733
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 146 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/Get started/FAQ.md
View File

@ -347,7 +347,7 @@ In the Fleet UI, you can turn off MDM for a host by selecting **Actions > Turn o
When you turn off MDM for a host, Fleet removes the enforcement of all macOS settings for that host. Also, the host will stop receiving macOS update reminders via Nudge. Turning MDM off doesn't remove the fleetd agent from the host. To remove the fleetd agent, share [these guided instructions](#how-can-i-uninstall-the-osquery-agent) with the end user.
To enforce macOS settings and send macOS update reminders, the host has to turn MDM back on. To turn MDM on, share [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-migration-guide#instructions-for-end-users) with the end user. Turning MDM back on for a host requires end user action.
To enforce macOS settings and send macOS update reminders, the host has to turn MDM back on. Turning MDM back on for a host requires end user action.
### What does "package root files: heat failed" mean?
We've found this error when you try to build an MSI on Docker 4.17. The underlying issue has been fixed in Docker 4.18, so we recommend upgrading. More information [here](https://github.com/fleetdm/fleet/issues/10700)

200
docs/Using Fleet/MDM-migration-guide.md
View File

@ -7,45 +7,173 @@ This section provides instructions for migrating your hosts away from your old M
1. A [deployed Fleet instance](../Deploying/Introduction.md)
2. [Fleet connected to Apple](./MDM-setup.md)
## Preparing to migrate manually enrolled hosts
## Migrate manually enrolled hosts
1. [Enroll](./Adding-hosts.md) your hosts to Fleet with [Fleetd and Fleet Desktop](https://fleetdm.com/docs/using-fleet/adding-hosts#including-fleet-desktop)
2. Ensure your end users have access to an admin account on their Mac. End users won't be able to migrate on their own if they have a standard account.
3. In your old MDM solution, unenroll the hosts to be migrated. MacOS does not allow multiple MDMs to be installed at once.
4. Send [these guided instructions](#instructions-for-end-users) to your end users to complete the final few steps via Fleet Desktop.
4. Send [these guided instructions](#how-to-turn-on-mdm) to your end users to complete the final few steps via Fleet Desktop.
* Note that there will be a gap in MDM coverage between when the host is unenrolled from the old MDM and when the host turns on MDM in Fleet.
## Preparing to migrate automatically enrolled (DEP) hosts
### End user experience
1. On their **My device** page, once an end user's device is unenrolled from the old MDM solution, the end user will be given the option to manually download the MDM enrollment profile.
2. Once downloaded, the user will receive a system notification that the Device Enrollment profile needs to be installed in their **System Settings > Profiles** section.
3. After installation, the MDM enrollment profile can be removed by the end user at any time.
### How to turn on MDM
1. Select the Fleet icon in your menu bar and select **My device**.
![Fleet icon in menu bar](https://raw.githubusercontent.com/fleetdm/fleet/main/website/assets/images/articles/fleet-desktop-says-hello-world-cover-1600x900@2x.jpg)
2. On your **My device** page, select the **Turn on MDM** button in the yellow banner and follow the instructions.
- If you don’t see the yellow banner or the **Turn on MDM** button, select the purple **Refetch** button at the top of the page.
- If you still don't see the **Turn on MDM** button or the **My device** page presents you with an error, please contact your IT administrator.
<img width="1400" alt="My device page - turn on MDM" src="https://user-images.githubusercontent.com/5359586/229950406-98343bf7-9653-4117-a8f5-c03359ba0d86.png">
## Migrate automatically enrolled (DEP) hosts
> Automatic enrollment is available in Fleet Premium or Ultimate
To migrate automatically enrolled hosts, we will do the following steps:
1. Prepare to migrate hosts
2. Choose migration workflow and migrate hosts
### Step 1: prepare to migrate hosts
1. Connect Fleet to Apple Business Manager (ABM). Learn how [here](./MDM-setup.md#apple-business-manager-abm).
2. [Enroll](./Adding-hosts.md) your hosts to Fleet with [Fleetd and Fleet Desktop](https://fleetdm.com/docs/using-fleet/adding-hosts#including-fleet-desktop)
3. Ensure your end users have access to an admin account on their Mac. End users won't be able to migrate on their own if they have a standard account.
4. Migrate your hosts to Fleet in ABM:
1. In ABM, unassign the existing hosts' MDM server from the old MDM solution: In ABM, select **Devices** and then select **All Devices**. Then, select **Edit** next to **Edit MDM Server**, select **Unassign from the current MDM**, and select **Continue**.
2. In ABM, assign these hosts' MDM server to Fleet: In ABM, select **Devices** and then select **All Devices**. Then, select **Edit** next to **Edit MDM Server**, select **Assign to the following MDM:**, select your Fleet server in the dropdown, and select **Continue**.
5. In your old MDM solution, unenroll the hosts to be migrated. MacOS does not allow multiple MDMs to be installed at once.
6. Send [these guided instructions](#instructions-for-end-users) to your end users to complete the final few steps via Fleet Desktop.
* Note that there will be a gap in MDM coverage between when the host is unenrolled from the old
MDM and when the host turns on MDM in Fleet. Use Fleet's [end user migration workflow](#end-user-migration-workflow) to reduce the gap in MDM coverage.
### End user migration workflow
### Step 2: choose migration workflow and migrate hosts
There are two migration workflows in Fleet: default and end user.
The default migration workflow requires that the IT admin unenrolls hosts from the old MDM solution before the end user can complete migration. This will result in a gap in MDM coverage until the end user completes migration.
The end user migration workflow allows the end user to kick-off migration by unenrolling from the old MDM solution on their own. Once the user is unenrolled, they're prompted to turn on MDM features in Fleet. This reduces the gap in MDM coverage.
Configuring the end user migration workflow requires a few additional steps.
#### Default workflow
1. In your old MDM solution, unenroll the hosts to be migrated. MacOS does not allow multiple MDMs to be installed at once.
2. Send [these guided instructions](#how-to-turn-on-mdm-default) to your end users to complete the final few steps via Fleet Desktop.
* Note that there will be a gap in MDM coverage between when the host is unenrolled from the old MDM and when the host turns on MDM in Fleet.
##### End user experience
1. The end user will receive a "Device Enrollment: &lt;organization&gt; can automatically configure your Mac." system notification within the macOS Notifications Center.
2. After the end user clicks on the system notification, macOS will open the **System Setting > Profiles** and ask the user to "Allow Device Enrollment: &lt;organization&gt; can automatically configure your Mac based on settings provided by your System Administrator."
3. If the end user does not install the profile, the system notification will continue to prompt the end user until the setting has been allowed.
4. Once this setting has been approved, the MDM enrollment profile cannot be removed by the end user.
##### How to turn on MDM (default)
1. Select the Fleet icon in your menu bar and select **My device**.
![Fleet icon in menu bar](https://raw.githubusercontent.com/fleetdm/fleet/main/website/assets/images/articles/fleet-desktop-says-hello-world-cover-1600x900@2x.jpg)
2. On your **My device** page, select the **Turn on MDM** button in the yellow banner and follow the instructions.
* If you don’t see the yellow banner or the **Turn on MDM** button, select the purple **Refetch** button at the top of the page.
* If you still don't see the **Turn on MDM** button or the **My device** page presents you with an error, please contact your IT administrator.
<img width="1400" alt="My device page - turn on MDM" src="https://user-images.githubusercontent.com/5359586/229950406-98343bf7-9653-4117-a8f5-c03359ba0d86.png">
#### End user workflow
> Available in Fleet Premium or Ultimate
You can use Fleet's end user migration workflow to reduce the gap in MDM coverage during migration.
The end user migration workflow is supported for automatically enrolled (DEP) hosts.
The migration worfklow is supported for automatically enrolled (DEP) hosts.
To watch a GIF that walks through the end user experience during the migration workflow, in the Fleet UI, head to **Settings > Integrations > Mobile device management (MDM)**, and scroll down to the **End user migration workflow** section.
During the end user migration workflow, an end user's device will have their selected system
theme (light or dark) applied. If your logo does not look good on either light or dark backgrounds,
you can optionally set an alternate logo for the themes.
In Fleet, you can configure the end user workflow using the Fleet UI or fleetctl command-line tool.
You can do this in the Fleet UI by going to **Settings** > **Organization settings** >
**Organization info** and adding a url to the desired image in the **Organization avatar URL (for
dark backgrounds)** and **Organization avatar URL (for light backgrounds)** inputs. The appropriate
image will show depending on the selected system theme.
Fleet UI:
1. Select the avatar on the right side of the top navigation and select **Settings > Integrations > Mobile device management (MDM)**.
2. Scroll down to the **End user migration workflow** section and select the toggle to enable the workflow.
3. Under **Mode** choose a mode and enter the webhook URL for you automation tool (ex. Tines) under **Webhook URL** and select **Save**.
4. During the end user migration workflow, an end user's device will have their selected system theme (light or dark) applied. If your logo is not easy to see on both light and dark backgrounds, you can optionally set a logo for each theme:
1. Head to **Settings** > **Organization settings** >
**Organization info** and add URLs to your logos in the **Organization avatar URL(for dark backgrounds)** and **Organization avatar URL (for light backgrounds)** fields.
2. Select **Save**.
fleetctl CLI:
1. Create `fleet-config.yaml` file or add to your existing `config` YAML file:
```yaml
apiVersion: v1
kind: config
spec:
mdm:
macos_migration:
enable: true
mode: "voluntary"
webhook_url: "https://example.com"
...
```
2. Fill in the above keys under the `mdm.macos_migration` key.
To learn about each option, in the Fleet UI, select the avatar on the right side of the top navigation, select **Settings > Integrations > Mobile device management (MDM)**, and scroll down to the **End user migration workflow** section.
3. During the end user migration workflow, the window will show the Fleet logo on top of a dark and light background (appearance configured by end user).
If want to add a your organization's logo, you can optionally set a logo for each background:
```yaml
apiVersion: v1
kind: config
spec:
org_info:
org_logo_url: https://fleetdm.com/images/press-kit/fleet-blue-logo.png
org_logo_url_light_background: https://fleetdm.com/images/press-kit/fleet-white-logo.png
...
```
Add URLs to your logos that are visible on a dark background and light background in the `org_logo_url` and `org_logo_url_light_background` keys respectively. If you only set a logo for one, the Fleet logo will be used for the other.
4. Run the fleetctl `apply -f fleet-config.yml` command to add your configuration.
5. Confirm that your configuration was saved by running `fleetctl get config`.
6. Send [these guided instructions](#how-to-turn-on-mdm-end-user) to your end users to complete the final few steps via Fleet Desktop.
##### How to turn on MDM (end user)
1. Select the Fleet icon in your menu bar and select **Migrate to Fleet**.
2. Select **Start** in the **Migrate to Fleet** popup.
2. On your **My device** page, select the **Turn on MDM** button in the yellow banner and follow the instructions.
* If you don’t see the yellow banner or the **Turn on MDM** button, select the purple **Refetch** button at the top of the page.
* If you still don't see the **Turn on MDM** button or the **My device** page presents you with an error, please contact your IT administrator.
## Check migration progress
To see a report of which hosts have successfully migrated to Fleet, have MDM features off, or are still enrolled to your old MDM solution head to the **Dashboard** page by clicking the icon on the left side of the top navigation bar.
Then, scroll down to the **Mobile device management (MDM)** section.
## FileVault recovery keys
@ -82,44 +210,6 @@ For all other settings:
* If it does not export settings, you will need to re-create the configuration profiles. Learn how to do that [here](./MDM-custom-macOS-settings.md#step-1-create-a-configuration-profile)
2. Create [teams](https://fleetdm.com/docs/using-fleet/teams) according to the needs of your organization
3. Follow the instructions to add configuration profiles to Fleet [here](./MDM-custom-macOS-settings.md#step-2-upload-configuration-profile-to-fleet).
## Instructions for end users
Your organization uses Fleet to check if all devices meet its security policies.
Fleet includes device management features (called “MDM”) that allow your IT team to change settings remotely on your Mac. This lets your organization keep your Mac up to date so you don’t have to.
Want to know what your organization can see? Read about [transparency](https://fleetdm.com/transparency).
### How to turn on MDM:
1. Select the Fleet icon in your menu bar and select **My device**.
![Fleet icon in menu bar](https://raw.githubusercontent.com/fleetdm/fleet/main/website/assets/images/articles/fleet-desktop-says-hello-world-cover-1600x900@2x.jpg)
2. On your **My device** page, select **Turn on MDM** the button in the yellow banner and follow the instructions.
- If you don’t see the yellow banner or the **Turn on MDM** button, select the purple **Refetch** button at the top of the page.
- If you still don't see the **Turn on MDM** button or the **My device** page presents you with an error, please contact your IT administrator.
<img width="1400" alt="My device page - turn on MDM" src="https://user-images.githubusercontent.com/5359586/229950406-98343bf7-9653-4117-a8f5-c03359ba0d86.png">
#### Automatic Enrollment (ADE)
1. If your device is enrolled in Apple Business Manager (ABM) and assigned to the Fleet server, the end user will receive a "Device Enrollment: &lt;organization&gt; can automatically configure your Mac." system notification within the macOS Notifications Center.
2. After the end user clicks on the system notification, macOS will open the "Profiles" System Setting and ask the user to "Allow Device Enrollment: &lt;organization&gt; can automatically configure your Mac based on settings provided by your System Administrator."
3. If the end user does not Allow the setting, the system notification will continue to nag the end user until the setting has been allowed.
4. Once this setting has been approved, the MDM enrollment profile cannot be removed by the end user.
#### Manual Enrollment
1. If your device is not enrolled in Apple Business Manager (ABM), the end user will be given the option to manually download the MDM enrollment profile.
2. Once downloaded, the user will receive a system notification that the Device Enrollment profile has been needs to be installed in the System Settings &gt; Profiles section.
2. After installation, the MDM enrollment profile can be removed by the end user at any time.
### How to turn on disk encryption