mirror of
https://github.com/fleetdm/fleet
synced 2026-04-21 21:47:20 +00:00
d0ab789e4f
Updated to shorten and remove techincal details that are available inside the script (as comments). Related to: #38985 --------- Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com>
237 lines
15 KiB
Markdown
237 lines
15 KiB
Markdown
# Windows MDM setup
|
||
|
||
|
||
|
||
To control OS settings, updates, and more on Windows hosts, follow the manual enrollment instructions.
|
||
|
||
To use automatic enrollment (aka zero-touch) features on Windows, follow the instructions to connect Fleet to Microsoft Entra ID. You can further customize zero-touch with Windows Autopilot.
|
||
|
||
To migrate Windows hosts from your current MDM solution to Fleet, follow the [Automatic Windows MDM migration](#automatic-windows-mdm-migration) instructions.
|
||
|
||
## Turn on Windows MDM
|
||
|
||
### Step 1: Generate your certificate and key
|
||
|
||
Fleet uses a certificate and key pair to authenticate and manage interactions between the Fleet server and a Windows host.
|
||
|
||
How to generate a certificate and key:
|
||
|
||
1. With [OpenSSL](https://www.openssl.org/) installed, open your Terminal (macOS) or PowerShell (Windows) and run the following command to create a key: `openssl genrsa --traditional -out fleet-mdm-win-wstep.key 4096`.
|
||
|
||
2. Create a certificate: `openssl req -x509 -new -nodes -key fleet-mdm-win-wstep.key -sha256 -days 3652 -out fleet-mdm-win-wstep.crt -subj '/CN=Fleet Root CA/C=US/O=Fleet.'`.
|
||
|
||
> Note: The default `openssl` binary installed on macOS is actually `LibreSSL`, which doesn't support the `--traditional` flag. To successfully generate these files, make sure you're using `OpenSSL` and not `LibreSSL`. You can check what your `openssl` command points to by running `openssl version`.
|
||
|
||
### Step 2: Configure Fleet with your certificate and key
|
||
|
||
In your Fleet server configuration, set the contents of the certificate and key in the following environment variables:
|
||
|
||
> Note: Any environment variable that ends in `_BYTES` expects the file's actual content to be passed in, not a path to the file. If you want to pass in a file path, remove the `_BYTES` suffix from the environment variable.
|
||
|
||
- [FLEET_MDM_WINDOWS_WSTEP_IDENTITY_CERT_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-windows-wstep-identity-cert-bytes)
|
||
- [FLEET_MDM_WINDOWS_WSTEP_IDENTITY_KEY_BYTES](https://fleetdm.com/docs/deploying/configuration#mdm-windows-wstep-identity-key-bytes)
|
||
|
||
Restart the Fleet server.
|
||
|
||
### Step 3: Turn on Windows MDM
|
||
|
||
1. Head to the **Settings > Integrations > Mobile device management (MDM)** page.
|
||
|
||
2. Next to **Turn on Windows MDM** select **Turn on** to navigate to the **Manage Windows MDM** page.
|
||
|
||
3. Toggle Windows MDM on. The best practice is to leave the end user experience set to **Automatic**. If you want end users to have to take action to turn MDM on, choose **Manual**.
|
||
|
||
## Manual enrollment
|
||
|
||
With Windows MDM turned on, enroll a Windows host to Fleet by installing [Fleet's agent (fleetd)](https://fleetdm.com/docs/using-fleet/enroll-hosts).
|
||
|
||
> Windows [tamper protection](https://learn.microsoft.com/en-us/defender-endpoint/prevent-changes-to-security-settings-with-tamper-protection) is disabled on a host when MDM is turned on.
|
||
|
||
### Migrating from another MDM solution
|
||
|
||
When migrating Windows hosts from another MDM, devices may fail to report MDM as "On." You might see enrollment errors (e.g., 400 or 0x8018000a) in [fleetd logs](https://fleetdm.com/guides/enroll-hosts#debugging). Local accounts can also become locked.
|
||
|
||
These issues are usually caused by leftover enrollment data or third-party management agents from the previous MDM.
|
||
|
||
To fix this:
|
||
|
||
1. Run the [fix-windows-mdm-migration.ps1](https://github.com/fleetdm/fleet/blob/main/docs/solutions/windows/scripts/fix-windows-mdm-migration.ps1) script on affected hosts.
|
||
2. Reboot the device.
|
||
3. In Fleet, open the host and select **Refetch** on the **Host details** page.
|
||
|
||
Learn how to [run scripts in Fleet](https://fleetdm.com/guides/scripts#manually-run-scripts).
|
||
|
||
|
||
**Conflicting RMM or management agents:** Third-party RMM agents (such as N-able/SolarWinds, ConnectWise, or Kaseya) installed alongside the previous MDM solution can interfere with Fleet's MDM enrollment and may cause Windows Update to stop functioning. Check for and remove any RMM agents that are no longer needed before or after migrating to Fleet.
|
||
|
||
## Automatic enrollment
|
||
|
||
_Available in Fleet Premium_
|
||
|
||
To automatically enroll Windows workstations when they’re first unboxed and set up by your end users, we will connect Fleet to Microsoft Entra ID.
|
||
|
||
Connecting Fleet to Entra also enables end users to manually turn on MDM via the [Settings > Access work or school workflow](https://support.microsoft.com/en-us/account-billing/join-your-work-device-to-your-work-or-school-network-ef4d6adb-5095-4e51-829e-5457430f3973#:~:text=If%20you%27ve%20had%20your%20device%20for%20a%20while%20and%20it%27s%20already%20been%20set%20up%2C%20you%20can%20follow%20these%20steps%20to%20join%20your%20device%20to%20the%20network.). Fleet will collect the email and store it as the IdP [username](https://fleetdm.com/guides/foreign-vitals-map-idp-users-to-hosts). If a different email is used during the [setup experience](https://fleetdm.com/guides/setup-experience#end-user-authentication), it won't override the one used in **Settings > Access work or school**.
|
||
|
||
During enrollment, end users are prompted to set up Windows Hello and add a PIN. To see the end user experience, watch [this video](https://www.youtube.com/watch?v=vJ9ciRLfVY8).
|
||
|
||
After you connect Fleet to Entra, you can customize the Windows setup experience with [Windows Autopilot](https://learn.microsoft.com/en-us/autopilot/windows-autopilot).
|
||
|
||
In order to connect Fleet to Entra, the IT admin (you) needs a Microsoft Enterprise Mobility + Security E3 license. Each end user who automatically enrolls or manually turns on MDM needs at least a [Microsoft Entra P1 license](https://www.microsoft.com/en-us/security/business/microsoft-entra-pricing). If they already have an [E3 or E5 license](https://www.microsoft.com/en-us/microsoft-365/enterprise/microsoft365-plans-and-pricing) then you're good to go.
|
||
|
||
### Step 1: Buy Microsoft licenses
|
||
|
||
1. Sign in to [Microsoft 365 admin center](https://admin.microsoft.com/).
|
||
|
||
2. In the left-side bar, select **Marketplace**.
|
||
|
||
3. On the **Marketplace** page, select **All products** and in the search bar below **All products** enter "Enterprise Mobility + Security E3".
|
||
|
||
4. Find **Enterprise Mobility + Security E3** and select **Details**
|
||
|
||
5. On the **Enterprise Mobility + Security E3** page, select **Buy** and follow instructions to purchase the license.
|
||
|
||
6. Find and buy a license.
|
||
|
||
7. Sign in to [Microsoft Entra ID portal](https://portal.azure.com).
|
||
|
||
8. At the top of the page, search "Users" and select **Users**.
|
||
|
||
9. Select or create a test user and select **Licenses**.
|
||
|
||
10. Select **+ Assignments** and assign yourself the **Enterprise Mobility + Security E3**. Assign the test user the Intune license.
|
||
|
||
### Step 2: Connect Fleet to Microsoft Entra ID
|
||
|
||
The end user will see Microsoft's default initial setup. You can further simplify the initial device setup with Autopilot, which is similar to Apple's Automated Device Enrollment (DEP).
|
||
|
||
Some Intune/Entra deployments enable automatic enrollment into Intune. Check to ensure **Automatic Enrollment** is not enabled, or your devices will not appear in Fleet.
|
||
|
||
In your Intune settings, select **Devices**, and under **Device onboarding**, open the **Enrollment** submenu. Select **Automatic Enrollment** and ensure both **MDM user scope** and **Windows Information Protection (WIP) user scope** are set to **None**.
|
||
|
||
1. [Sign in to Microsoft Entra](https://fleetdm.com/sign-in-to/microsoft-automatic-enrollment-tool).
|
||
2. On the home page, find and copy the **Tenant ID**.
|
||
3. In Fleet, navigate to **Settings** > **Integrations** > **MDM**. Under **Windows Enrollment**, select **Connect**.
|
||
4. Under **Entra tenants**, select **Add**, paste tenant ID, and select **Add**. If you don't add the Entra Tenant ID, end users will see the "Device management could not be enabled" error, and won't be able to enroll their host.
|
||
5. Head to Entra, and on the top of the page, search "Domain names" and select **Domain names**. Select **+ Add custom domain**, type your Fleet URL (e.g. fleet.acme.com), and select **Add domain**.
|
||
6. Use the information presented in Azure AD to create a new TXT/MX record with your domain registrar, then select **Verify**. If you're a managed-cloud customer, please reach out to Fleet to create a TXT/MX record for you.
|
||
7. At the top of the page, search for "Mobility" and select **Mobility (MDM and WIP)**.
|
||
8. Select **+ Add application**, then select **+ Create your own application**.
|
||
9. Enter "Fleet" as the name of your application and select **Create**.
|
||
10. Set MDM user scope to **All**, then in Fleet head to **Settings** > **Integrations** > **MDM** > **Windows Enrollment > Edit** and copy the **MDM URLs**. Paste them in Entra, and select **Save**.
|
||
11. While on this same page, select the **Custom MDM application settings** link.
|
||
12. Click on the **Application ID URI**, which will bring you to the **Expose an API** submenu with an edit button next to the text box.
|
||
13. Replace with your Fleet URL (e.g., fleet.acme.com) and select **Save**.
|
||
14. Select **API permissions** from the sidebar, then select **+ Add a permission**.
|
||
15. Select **Microsoft Graph**, then select **Delegated permissions**, and select **Group > Group.Read.All** and **Group > Group.ReadWrite.All** and **Add permissions**.
|
||
16. Again select **+ Add a permission** and then **Microsoft Graph** and **Application permissions**, select the following:
|
||
+ Device > Device.Read.All
|
||
+ Device > Device.ReadWrite.All
|
||
+ Directory > Directory.Read.All
|
||
+ Group > Group.Read.All
|
||
+ User > User.Read.All
|
||
17. Select **Add permissions**.
|
||
18. Select **Grant admin consent for [your tenant name]**, and confirm.
|
||
|
||
Now you're ready to automatically enroll Windows hosts to Fleet.
|
||
|
||
### Step 3: Test automatic enrollment
|
||
|
||
Testing automatic enrollment requires creating a test user in Microsoft Entra ID and a freshly wiped or new Windows workstation.
|
||
|
||
1. Sign in to [Microsoft Entra ID portal](https://portal.azure.com).
|
||
|
||
2. At the top of the page, search "Users" and select **Users**.
|
||
|
||
3. Select **+ New user > Create new user**, fill out the details for your test user, and select **Review + Create > Create**.
|
||
|
||
4. Go back to **Users** and refresh the page to confirm that your test user was created.
|
||
|
||
5. Open your Windows workstation and follow the setup steps. When you reach the **How would you like to set up?** screen, select **Set up for an organization**. If your workstations have Windows 11, select **Set up for work or school**.
|
||
|
||
6. Sign in with your test user's credentials and finish the setup steps.
|
||
|
||
7. When you reach the desktop on your Windows workstation, confirm that your workstation was automatically enrolled to Fleet by selecting the carrot (^) in your taskbar and then selecting the Fleet icon. This will navigate you to this workstation's **My device** page.
|
||
|
||
8. On the **My device** page, below **My device** confirm that your workstation has a **Status** of "Online."
|
||
|
||
## Windows Autopilot
|
||
|
||
### Step 1: Create an Autopilot profile
|
||
|
||
1. Sign in to [Microsoft Intune](https://endpoint.microsoft.com/) using the Intune admin user from step 1.
|
||
|
||
2. In the left-side bar, select **Devices > Enrollment** under **Device onboarding**. Under **Windows Autopilot** select **Deployment Profiles** to navigate to the **Windows Autopilot deployment profiles** page.
|
||
|
||
3. Select **+ Create profile > Windows PC** and follow steps to create an Autopilot profile. On the **Assignments** step, select **+ Add all devices**.
|
||
|
||
### Step 2: Register a test workstation
|
||
|
||
1. Open your test workstation and follow these [Microsoft instructions](https://learn.microsoft.com/en-us/autopilot/add-devices#desktop-hash-export) to export your workstation's device hash as a CSV. The CSV should look something like `DeviceHash_DESKTOP-2V08FUI.csv`
|
||
|
||
2. In Intune, in the left-side bar, select **Devices > Enroll devices**. Under **Windows Autopilot Deployment Program** select **Devices** to navigate to the **Windows Autopilot devices** page.
|
||
|
||
3. Select **Import** and import your CSV.
|
||
|
||
4. After Intune finishes the import, refresh the **Windows Autopilot devices** page several times to confirm that your workstation is registered with Autopilot.
|
||
|
||
### Step 3: Upload your organization's logo
|
||
|
||
1. Navigate to [Microsoft Entra ID portal](https://portal.azure.com).
|
||
|
||
2. At the top of the page, search for "Microsoft Entra ID", select **Microsoft Entra ID**, and then select **Company branding**.
|
||
|
||
3. On the **Company Branding** page, select **Configure** or **Edit** under **Default sign-in experience**.
|
||
|
||
4. Select the **Sign-in form** tab and upload your logo to the **Square logo (light theme)** and **Square logo (dark theme)** fields.
|
||
|
||
5. In the bottom bar, select **Review + Save** and then **Save**.
|
||
|
||
### Step 4: Test Autopilot
|
||
|
||
1. Wipe your test workstation.
|
||
|
||
2. After it's been wiped, open your workstation and follow the setup steps. On the screen in which you're asked to sign in, you should see the title "Welcome to [your organization]!" next to the logo you uploaded in step 4.
|
||
|
||
|
||
## Automatic Windows MDM migration
|
||
|
||
Fleet can automatically migrate your Windows hosts from another MDM solution to Fleet without end user interaction.
|
||
|
||
### Step 1: Set up Windows MDM in Fleet
|
||
|
||
Follow the [steps above](#manual-enrollment) to turn on Windows MDM in Fleet.
|
||
|
||
### Step 2: Install Fleet's agent on the hosts
|
||
|
||
1. [Enroll](https://fleetdm.com/docs/using-fleet/enroll-hosts) the Windows hosts you want to migrate to Fleet.
|
||
|
||
2. Navigate to the **Hosts** tab in the main navigation bar and wait until your hosts are visible in the hosts list.
|
||
|
||
### Step 3: Enable automatic migration
|
||
|
||
1. Head back to the **Settings > Integrations > Mobile device management (MDM)** page.
|
||
|
||
2. Next to **Windows MDM turned on (servers excluded)** select **Edit** to navigate to the **Manage Windows MDM** page.
|
||
|
||
3. On the **Manage Windows MDM** page, select **Automatically migrate hosts connected to another MDM solution**. Click **Save** to save the change.
|
||
|
||
### Step 4: Monitor your hosts as they migrate to Fleet MDM
|
||
|
||
Once the automatic migration is enabled, Fleet sends a notification to each host to tell it to migrate. This process usually takes a few minutes at most.
|
||
|
||
You can [track migration progress in Fleet](https://fleetdm.com/guides/mdm-migration#check-migration-progress).
|
||
|
||
## Turn off Windows MDM
|
||
|
||
1. Turn off MDM for each host by running [this script](https://github.com/fleetdm/fleet/blob/main/it-and-security/lib/windows/scripts/turn-off-mdm.ps1) from Fleet on all your Windows hosts.
|
||
2. Head to **Settings > Integrations > MDM**.
|
||
3. In the **Mobile device management (MDM)** section, select **Edit** next to "Windows MDM turned on."
|
||
4. Switch **Windows MDM on** to **Windows MDM off** and select **Save**.
|
||
|
||
<meta name="articleTitle" value="Windows MDM setup">
|
||
<meta name="authorFullName" value="Noah Talerman">
|
||
<meta name="authorGitHubUsername" value="noahtalerman">
|
||
<meta name="category" value="guides">
|
||
<meta name="publishedOn" value="2023-10-23">
|
||
<meta name="articleImageUrl" value="../website/assets/images/articles/windows-mdm-fleet-1600x900@2x.png">
|
||
<meta name="description" value="Configuring Windows MDM in Fleet.">
|