Contributor docs: APNs and ABM in the UI (#19549)
- Remove outdated sections
This commit is contained in:
Noah Talerman
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user