MDM docs: Update contributor docs and add feature flags (#10373)
- Update configuration docs to include config options required for beta users: feature flags and SCEP challenge - Update contributor docs to point to user facing docs for generating APNs and ABM cert and keys.
This commit is contained in:
Noah Talerman
@@ -473,71 +473,26 @@ To enable the [DEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/g
|
||||
1. A certificate.
|
||||
1. An encrypted token generated by Apple.
|
||||
|
||||
#### Private key + certificate
|
||||
#### Private key, certificate, and encrypted token
|
||||
|
||||
You can generate the private key and the certificate using `fleetctl`:
|
||||
First ask @zwass 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.
|
||||
|
||||
```
|
||||
fleetctl generate mdm-apple-bm
|
||||
```
|
||||
|
||||
This will output two files `fleet-apple-mdm-bm-public-key.crt` and `fleet-apple-mdm-bm-private.key`, save them in a safe place.
|
||||
|
||||
#### Encrypted token
|
||||
|
||||
Ask @zwass 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)
|
||||
|
||||
Once you have access:
|
||||
|
||||
1. Go to https://business.apple.com/#/main/preferences/myprofile
|
||||
1. Click on "+ Add" to create a new MDM server.
|
||||
1. Use a name that allows you to identify the server.
|
||||
1. Under "Upload Public Key," upload the `fleet-apple-mdm-bm-public-key.crt` you generated before.
|
||||
1. Click "Save."
|
||||
1. Click on the "Download Token" button at the top and confirm the download in the modal.
|
||||
1. Save the token in a safe place.
|
||||
Once you have access to ABM, follow [these guided instructions](../Using-Fleet/Mobile-device-management.md#apple-business-manager-abm) in the user facing docs to generate the private key, certificate, and 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).
|
||||
|
||||
Both can be generated using the command below. The email must be a company email address. It cannot be an email address from commercial email providers like gmail.com.
|
||||
|
||||
```
|
||||
$ fleetctl generate mdm-apple --email <email> --org <organization>
|
||||
```
|
||||
|
||||
Using the above syntax, a command would look like this:
|
||||
```
|
||||
$ fleetctl generate mdm-apple --email it@example.com --org "Acme Co."
|
||||
```
|
||||
|
||||
Successful output would look like this:
|
||||
```
|
||||
Sending certificate signing request (CSR) for Apple Push Notification service (APNs) to <email>...
|
||||
Generating APNs key, Simple Certificate Enrollment Protocol (SCEP) certificate, and SCEP key...
|
||||
|
||||
Success!
|
||||
|
||||
Generated your APNs key at fleet-mdm-apple-apns.key
|
||||
|
||||
Generated your SCEP certificate at fleet-mdm-apple-scep.crt
|
||||
|
||||
Generated your SCEP key at fleet-mdm-apple-scep.key
|
||||
|
||||
Go to your email to download a CSR from Fleet. Then, visit https://identity.apple.com/pushcert to upload the CSR. You should receive an APNs certificate in return from Apple.
|
||||
|
||||
Next, use the generated certificates to deploy Fleet with `mdm` configuration: https://fleetdm.com/docs/deploying/configuration#mobile-device-management-mdm
|
||||
```
|
||||
To generate both, follow [these guided instructions](../Using-Fleet/Mobile-device-management.md#apple-push-notification-service-apns).
|
||||
|
||||
Note that:
|
||||
|
||||
1. Fleet must be running for the command to succeed.
|
||||
2. You must be logged in to `fleetctl` using a global admin account. See [Building Fleet](./Building-Fleet.md) for details on getting Fleet setup locally.
|
||||
1. Fleet must be running to generate the certificates and keys.
|
||||
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.
|
||||
|
||||
Another option, if for some reason the `fleetctl generate` command fails or you don't have a supported email address handy is to use `openssl` to generate your SCEP key pair:
|
||||
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:
|
||||
|
||||
```
|
||||
$ openssl genrsa -out fleet-mdm-apple-scep.key 4096
|
||||
|
||||
@@ -2580,7 +2580,31 @@ packaging:
|
||||
|
||||
#### Mobile device management (MDM)
|
||||
|
||||
> MDM features are not ready for production and are currently in development. These features are disabled by default.
|
||||
> MDM features are not ready for production and are currently in beta. These features are disabled by default. To enable these features set `FLEET_DEV_MDM_ENABLED=1` as an environment variable.
|
||||
|
||||
#### dev_mdm_enabled
|
||||
|
||||
This is the first of two feature flags required to turn on MDM features. This feature flag should be set to `1` before you follow the [setup MDM instructions](../Using-Fleet/Mobile-device-management.md#set-up).
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_DEV_MDM_ENABLE`
|
||||
- Config file format:
|
||||
```
|
||||
dev:
|
||||
mdm_enable: 1
|
||||
```
|
||||
|
||||
##### apple_mdm_enable
|
||||
|
||||
This is the second feature flag required to turn on MDM features. This feature flag must be set to `1` at the same time as when you set the certificate and keys for Apple Push Certificate server (APNs) and Apple Business Manager (ABM). Otherwise, the Fleet server won't start.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_ENABLE`
|
||||
- Config file format:
|
||||
```
|
||||
mdm:
|
||||
apple_enable: 1
|
||||
```
|
||||
|
||||
##### apple_apns_cert
|
||||
|
||||
@@ -2690,6 +2714,18 @@ The content of the PEM-encoded private key for the Simple Certificate Enrollment
|
||||
-----END RSA PRIVATE KEY-----
|
||||
```
|
||||
|
||||
##### apple_scep_challenge
|
||||
|
||||
An alphanumeric secret for the Simple Certificate Enrollment Protocol (SCEP). Should be 32 characters in length and only include alphanumeric characters.
|
||||
|
||||
- Default value: ""
|
||||
- Environment variable: `FLEET_MDM_APPLE_SCEP_CHALLENGE`
|
||||
- Config file format:
|
||||
```
|
||||
mdm:
|
||||
apple_scep_challenge: scepchallenge
|
||||
```
|
||||
|
||||
##### apple_bm_server_token
|
||||
|
||||
This is the path to the Apple Business Manager encrypted server token (a `.p7m` file) downloaded from Apple Business Manager. Only one of `apple_bm_server_token` and `apple_bm_server_token_bytes` can be set.
|
||||
|
||||
Reference in New Issue
Block a user