diff --git a/docs/Contributing/Testing-and-local-development.md b/docs/Contributing/Testing-and-local-development.md index bf293ab91f..0fa2998172 100644 --- a/docs/Contributing/Testing-and-local-development.md +++ b/docs/Contributing/Testing-and-local-development.md @@ -505,95 +505,24 @@ To run your local server with the MDM features enabled, you need to get certific ### ABM setup -To enable the [DEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#dep-device-enrollment-program) enrollment flow, the Fleet server needs three things: - -1. A private key. -1. A certificate. -1. An encrypted token generated by Apple. - -#### Private key, certificate, and encrypted token +To enable the [DEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#dep-device-enrollment-program) enrollment flow, the Fleet server needs an encrypted token generated by Apple. First ask @lukeheath to create an account for you in [ABM](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#abm-apple-business-manager). You'll need an account to generate an encrypted token. -Once you have access to ABM, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm) in the user facing docs to generate the private key, certificate, and encrypted token. +Once you have access to ABM, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm) to get and upload the encrypted token. ### APNs and SCEP setup -The server also needs a private key + certificate to identify with Apple's [APNs](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#apns-apple-push-notification-service) servers, and another for [SCEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#scep-simple-certificate-enrollment-protocol). +The server also needs a certificate to identify with Apple's [APNs](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#apns-apple-push-notification-service) servers. -To generate both, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-push-notification-service-apns). +To get a certificate and upload it, [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-macos-setup#apple-push-notification-service-apns). Note that: -1. Fleet must be running to generate the certificates and keys. +1. Fleet must be running to generate the token and certificate. 2. You must be logged in to Fleet as a global admin. See [Building Fleet](./Building-Fleet.md) for details on getting Fleet setup locally. 3. To login into https://identity.apple.com/pushcert you can use your ABM account generated in the previous step. -4. Save all the certificates and keys in a safe place. - -Internally, the certificates are generated using this flow. Note that the fleet sails API base url can be changed using the `TEST_FLEETDM_API_URL` environment variable. - -```mermaid -sequenceDiagram - participant user as user email - participant fleetctl as fleetctl - participant server as fleet server - participant fleetdm as fleetdm.com sails app - participant apple as identity.apple.com - link apple: PushCert @ https://identity.apple.com/pushcert - - note over fleetctl: fleetctl login - fleetctl->>+server: login - server-->>-fleetctl: token - note over fleetctl: fleetctl generate mdm_apple - fleetctl->>+server: generate certificates - server->>server: generate self-signed SCEP cert & key - server->>server: generate APNs key - server->>server: generate APNs CSR - server-)+fleetdm: request vendor signature on APNs CSR - server-->>-fleetctl: SCEP cert, SCEP key, APNs key - note over fleetdm: calls /ee/tools/mdm/cert - fleetdm--)-user: vendor-signed APNs CSR - user->>+apple: vendor-signed APNs CSR - note right of apple: managed through web ui - apple-->>-user: Apple-signed APNs certificate -``` - -Another option, if for some reason, generating the certificates and keys fails or you don't have a supported email address handy is to use `openssl` to generate your SCEP key pair: - -```sh -$ openssl genrsa -out fleet-mdm-apple-scep.key 4096 - -$ openssl req -x509 -new -nodes -key fleet-mdm-apple-scep.key -sha256 -days 1826 -out fleet-mdm-apple-scep.crt -subj '/CN=Fleet Root CA/C=US/O=Fleet DM.' -``` - -### Running the server - -Try to store all the certificates and tokens you generated in the earlier steps together in a safe place outside of the repo, then start the server with: - -```sh -FLEET_MDM_APPLE_SCEP_CHALLENGE=scepchallenge \ -FLEET_MDM_APPLE_SCEP_CERT=/path/to/fleet-mdm-apple-scep.crt \ -FLEET_MDM_APPLE_SCEP_KEY=/path/to/fleet-mdm-apple-scep.key \ -FLEET_MDM_APPLE_BM_SERVER_TOKEN=/path/to/dep_encrypted_token.p7m \ -FLEET_MDM_APPLE_BM_CERT=/path/to/fleet-apple-mdm-bm-public-key.crt \ -FLEET_MDM_APPLE_BM_KEY=/path/to/fleet-apple-mdm-bm-private.key \ -FLEET_MDM_APPLE_APNS_CERT=/path/to/mdmcert.download.push.pem \ -FLEET_MDM_APPLE_APNS_KEY=/path/to/mdmcert.download.push.key \ - ./build/fleet serve --dev --dev_license --logging_debug -``` - -Note: if you need to enroll VMs using MDM, the server needs to run behind TLS with a valid certificate. In a separate terminal window/tab, create a local tunnel to your server using `ngrok` (`brew install ngrok/ngrok/ngrok` if you don't have it.) - -```sh -ngrok http https://localhost:8080 -``` - -> NOTE: If this is your first time using ngrok this command will fail and you will see a message -> about signing up. Open the sign up link and complete the sign up flow. You can rerun the same command -> and ngrok should work this time. After this open the forwarding link, you will be asked to confirm that you'd like -> to be forwarded to your local server and should accept. - -Don't forget to edit your Fleet server settings (through the UI or `fleetctl`) to use the URL `ngrok` provides to you. You need to do this whenever you restart `ngrok`. +4. Save the token and certificate in a safe place. ### Testing MDM