Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-04-21 13:37:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 91

Improve Windows Autopilot dev setup docs with custom domain (#42831)

Browse source 
- Added custom domain + ngrok setup instructions for local Autopilot
testing (Entra requires a verified domain, not raw ngrok URLs).
- Clarified that `FLEET_DEV_DOWNLOAD_FLEETDM_URL` is a server runtime
env var requiring `--dev` mode.
This commit is contained in:
Nico 2026-04-13 11:42:23 -03:00 committed by GitHub
parent 36819b468c
commit 852ec6f807
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 50 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/Contributing/getting-started/testing-and-local-development.md
View file

@ -1003,7 +1003,7 @@ described below.
For Autopilot, Azure requires the Fleet server instance to have a proper domain name with some TXT/MX records added (see `/settings/integrations/automatic-enrollment/windows` on your Fleet instance).
For that reason, currently the only way to test this flow is to use Dogfood or the QA fleet server,
which already have this configured, or to configure an alternate server for this workflow.
which already have this configured, or to [configure an alternate server for this workflow](../../product-groups/mdm/windows-autopilot.md#setting-up-a-custom-domain-with-ngrok).
#### Pre-requisites
@ -1071,11 +1071,11 @@ mkdir -p ./tmp/fleetd-base-dir/stable
4. Start up an HTTP file server from the Fleet repo root directory using the [`tools/file-server`](../../tools/file-server/README.md) tool: `go run ./tools/file-server 8085 ./tmp/fleetd-base-dir`
5. Start your "installers" ngrok tunnel and forward to http://localhost:8085.
- Example: `ngrok http --domain=installers.fleetdm-example.ngrok.app http://localhost:8085`
6. Perform a Fleet deployment(to Dogfood, QA or your own instance) with
`FLEET_DEV_DOWNLOAD_FLEETDM_URL` set to the "installers" ngrok URL (if using Terraform, the environment variable is set on
`infrastructure/dogfood/terraform/aws-tf-module/main.tf`).
- Example: `FLEET_DEV_DOWNLOAD_FLEETDM_URL="https://installers.fleetdm-example.ngrok.app"`
7. Enroll your Windows device with Autopilot. Tip: You can watch ngrok traffic via the inspect web interface url to ensure the two hosted packages are in the correct place and successfully reached by the host.
6. Start your Fleet server with `FLEET_DEV_DOWNLOAD_FLEETDM_URL` set to the "installers" ngrok URL. For a local dev server:
- Example: `FLEET_DEV_DOWNLOAD_FLEETDM_URL="https://installers.fleetdm-example.ngrok.app" ./build/fleet serve --dev`
- For Dogfood/QA deployments using Terraform, set the environment variable on `infrastructure/dogfood/terraform/aws-tf-module/main.tf`.
- Note: This variable is only read when dev mode is enabled (`--dev` flag).
7. Enroll your Windows device with Autopilot. See the [Windows Autopilot guide](../../product-groups/mdm/windows-autopilot.md#enrolling-the-device) for detailed enrollment steps, including prerequisites like custom domain setup and required licenses. Tip: You can watch ngrok traffic via the inspect web interface url to ensure the two hosted packages are in the correct place and successfully reached by the host.
## MDM setup and testing

46
docs/Contributing/product-groups/mdm/windows-autopilot.md
View file

@ -4,7 +4,7 @@
- [Windows MDM Setup](https://fleetdm.com/guides/windows-mdm-setup#windows-autopilot)
- [Autopilot add devices](https://learn.microsoft.com/en-us/autopilot/add-devices)
- [Assigning Intune licenses](https://learn.microsoft.com/en-gb/intune/intune-service/fundamentals/licenses-assign)
- [Serve locally built Fleetd during Autopilot](https://github.com/fleetdm/fleet/blob/docs-windows-autopilot-dev/docs/Contributing/getting-started/testing-and-local-development.md#building-and-serving-your-own-fleetd-basemsi-installer-for-windows)
- [Serve locally built Fleetd during Autopilot](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/getting-started/testing-and-local-development.md#building-and-serving-your-own-fleetd-basemsi-installer-for-windows)
## Assigning an Intune license to your user
To use Autopilot, your user needs to have an Intune license assigned. If you don't already have one assigned, follow these steps:
@ -15,6 +15,7 @@ To use Autopilot, your user needs to have an Intune license assigned. If you don
4. Select your user and click "Assign"
1. If it says no license is available, you are good to buy a license, which will be charged on Noah Talerman's (As of 24th February 2026) brex card.
## Configuring Windows Autopilot for development
To set up Windows Autopilot for development, follow these steps:
1. Create a [new Intune security group](https://intune.microsoft.com/#view/Microsoft_AAD_IAM/AddGroupBlade)
@ -34,9 +35,50 @@ To add your Windows device (VM's work as well) to Autopilot, you need to get som
Follow the steps [in the autopilot add devices guide](https://learn.microsoft.com/en-us/autopilot/add-devices#directly-upload-the-hardware-hash-to-an-mdm-service), to either get the information into a .csv or upload it directly.
> **Important:** When uploading the hardware hash CSV, include the **group tag** that matches your dynamic security group query (e.g., `NameDev`). If you forget, you can edit the device in the [Autopilot devices list](https://intune.microsoft.com/#view/Microsoft_Intune_Enrollment/AutopilotDevices.ReactView/filterOnManualRemediationRequired~/false) and add it later.
#### If using a VM
If using a VM, make sure the VM is assigned a serial number. This is different on how to do for each VM provider, but for example on UTM, you can edit an instance, go to "Arguments" and add the following: `-smbios type=1,serial=<SERIAL_NUMBER>`, where <SERIAL_NUMBER> is a custom unique identifier.
Once added, you should see the device with it's serial show up in [the Autopilot devices list](https://intune.microsoft.com/#view/Microsoft_Intune_Enrollment/AutopilotDevices.ReactView/filterOnManualRemediationRequired~/false), it is ready to be enrolled, once the "Profile status" is "Assigned" (which may take some minutes).
Once added, you should see the device with it's serial show up in [the Autopilot devices list](https://intune.microsoft.com/#view/Microsoft_Intune_Enrollment/AutopilotDevices.ReactView/filterOnManualRemediationRequired~/false), it is ready to be enrolled, once the "Profile status" is "Assigned".
## Setting up a custom domain with ngrok
Microsoft Entra requires a **verified custom domain** for the MDM application URIs. You cannot use a raw `*.ngrok.io` URL — Entra will reject it during domain verification.
1. **Register a domain** (e.g., a cheap `.xyz` domain from Namecheap). You don't need to purchase SSL — ngrok handles TLS termination.
2. **Add a subdomain in ngrok's dashboard** (Domains section) — e.g., `mdm.yourdomain.xyz`. ngrok will provide a CNAME target (e.g., `xxx.ngrok-dns.com`).
3. **Configure DNS in your domain registrar:**
- Add a **CNAME record** for the subdomain (e.g., `mdm`) pointing to the ngrok CNAME target.
- Add the **TXT record** that Microsoft Entra provides on the **root domain** (e.g., `yourdomain.xyz`) for domain verification.
- Note: DNS standards don't allow CNAME records to coexist with other record types at the same name. Using a subdomain for the CNAME avoids this conflict — the root domain stays free for the Entra TXT verification record.
4. **Verify the root domain in Entra:** go to [Entra > Domain names](https://entra.microsoft.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Domains) > Add custom domain, enter your root domain (e.g., `yourdomain.xyz`), and verify it using the TXT record.
5. **Configure the MDM application in Entra** following the [Windows MDM Setup guide](https://fleetdm.com/guides/windows-mdm-setup#step-2-connect-fleet-to-microsoft-entra-id). Use your **subdomain** (e.g., `mdm.yourdomain.xyz`) for all MDM URLs (Application ID URI, discovery URL, terms of use URL).
Example ngrok config with a custom domain for the Fleet server:
```yaml
version: "3"
agent:
authtoken: <your_ngrok_authtoken>
tunnels:
fleet:
proto: http
schemes: [https]
hostname: mdm.yourdomain.xyz # subdomain CNAME'd to ngrok
addr: https://localhost:8080
inspect: true
installers:
proto: http
schemes: [https]
hostname: installers.your-ngrok-subdomain.ngrok.io
addr: http://localhost:8085
inspect: true
tuf:
proto: http
schemes: [http]
hostname: tuf.your-ngrok-subdomain.ngrok.io
addr: http://localhost:8081
inspect: true
```
Only the Fleet server tunnel needs the custom domain. The installer and TUF tunnels can use regular ngrok subdomains.