From 23ae7c763cbdf52f03b56e2dde67f64dd46b89a8 Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Mon, 3 Jun 2024 15:45:41 -0400 Subject: [PATCH] Server configuration docs: APNs and ABM in the UI (#19461) - Add redirect for error message on Fleet server startup if private key is missing: #19455 - Move the APNs and ABM environment variables to contributor docs. They will no longer be used --- .../fleet-server-configuration.md | 138 +----------------- .../Configuration-for-contributors.md | 130 +++++++++++++++++ website/config/routes.js | 2 +- 3 files changed, 136 insertions(+), 134 deletions(-) diff --git a/docs/Configuration/fleet-server-configuration.md b/docs/Configuration/fleet-server-configuration.md index 921aeed7a0..90f87b5736 100644 --- a/docs/Configuration/fleet-server-configuration.md +++ b/docs/Configuration/fleet-server-configuration.md @@ -680,12 +680,9 @@ Setting to true will disable the origin check. ##### server_private_key -The private key used to encrypt sensitive data in Fleet, for example, MDM certificates and keys. -The key must be at least 32 bytes long. If the key is longer than 32 bytes, only the first 32 bytes -will be used (the data is encrypted using AES-256, which requires a 32 byte key). This key is -required for enabling MDM features in Fleet. If you are using the `FLEET_APPLE_APNS_*` and -`FLEET_APPLE_SCEP_*` variables, Fleet will automatically encrypt the values of those variables using -`FLEET_SERVER_PRIVATE_KEY` and save them in the database when you restart after updating. +This key is required for enabling macOS MDM features in Fleet. If you are using the `FLEET_APPLE_APNS_*` and `FLEET_APPLE_SCEP_*` variables, Fleet will automatically encrypt the values of those variables using `FLEET_SERVER_PRIVATE_KEY` and save them in the database when you restart after updating. + +The key must be at least 32 bytes long. Run `openssl rand -base64 32` in the Terminal app to generate one on macOS. - Default value: "" - Environment variable: FLEET_SERVER_PRIVATE_KEY @@ -2808,89 +2805,9 @@ packaging: ## Mobile device management (MDM) -> MDM features require some endpoints to be publicly accessible. For more details, see the guide, [Which API endpoints to expose to the public internet?](https://fleetdm.com/guides/what-api-endpoints-to-expose-to-the-public-internet) +> The [`server_private_key` configuration option](#server_private_key) is required for macOS MDM features. -This section is a reference for the configuration required to turn on MDM features in production. - -If you're a Fleet contributor and you'd like to turn on MDM features in a local environment, see the guided instructions [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#mdm-setup-and-testing). - -##### mdm.apple_apns_cert_bytes - -The content of the Apple Push Notification service (APNs) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_APNS_CERT_BYTES` -- Config file format: - ```yaml - mdm: - apple_apns_cert_bytes: | - -----BEGIN CERTIFICATE----- - ... PEM-encoded content ... - -----END CERTIFICATE----- - ``` - -##### mdm.apple_apns_key_bytes - -The content of the PEM-encoded private key for the Apple Push Notification service (APNs). Typically generated via `fleetctl generate mdm-apple`. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_APNS_KEY_BYTES` -- Config file format: - ```yaml - mdm: - apple_apns_key_bytes: | - -----BEGIN RSA PRIVATE KEY----- - ... PEM-encoded content ... - -----END RSA PRIVATE KEY----- - ``` - -##### mdm.apple_scep_cert_bytes - -The content of the Simple Certificate Enrollment Protocol (SCEP) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_SCEP_CERT_BYTES` -- Config file format: - ```yaml - mdm: - apple_scep_cert_bytes: | - -----BEGIN CERTIFICATE----- - ... PEM-encoded content ... - -----END CERTIFICATE----- - ``` - -The SCEP certificate/key pair [generated by Fleet](https://fleetdm.com/docs/using-fleet/MDM-setup#step-1-generate-the-required-files) expires every 10 years. It's recommended to never change these unless they were compromised. - -If your certificate/key pair was compromised and you change the pair, the disk encryption keys will no longer be viewable on all macOS hosts' **Host details** page until you turn disk encryption off and back on and the keys are [reset by the end user](https://fleetdm.com/docs/using-fleet/MDM-migration-guide#how-to-turn-on-disk-encryption). - -##### mdm.apple_scep_key_bytes - -The content of the PEM-encoded private key for the Simple Certificate Enrollment Protocol (SCEP). Typically generated via `fleetctl generate mdm-apple`. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_SCEP_KEY_BYTES` -- Config file format: - ```yaml - mdm: - apple_scep_key_bytes: | - -----BEGIN RSA PRIVATE KEY----- - ... PEM-encoded content ... - -----END RSA PRIVATE KEY----- - ``` - -##### mdm.apple_scep_challenge - -An alphanumeric secret for the Simple Certificate Enrollment Protocol (SCEP). Define a unique, static secret 32 characters in length and only include alphanumeric characters. - -> SCEP is commonly applied to a number of certificate use cases. Notably, Mobile Device Management (MDM) systems like Microsoft Intune and Apple MDM use SCEP for PKI certificate enrollment. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_SCEP_CHALLENGE` -- Config file format: - ```yaml - mdm: - apple_scep_challenge: scepchallenge - ``` +> The Apple Push Notification service (APNs), SCEP, and Apple Business Manager (ABM) [configuration](https://github.com/fleetdm/fleet/fleet-v4.51.0/main/docs/Contributing/Configuration-for-contributors.md#mobile-device-management-mdm) are deprecated as of Fleet 4.51. They are maintained for backwards compatibility. Please upload your APNs certificate and ABM token in **Settings > Integrations MDM** and **Settings > Integrations > Automatic enrollment** respectively. ##### mdm.apple_scep_signer_validity_days @@ -2916,51 +2833,6 @@ The number of days allowed to renew SCEP certificates. apple_scep_signer_allow_renewal_days: 30 ``` -##### mdm.apple_bm_server_token_bytes - -This is the content of the Apple Business Manager encrypted server token downloaded from Apple Business Manager. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES` -- Config file format: - ```yaml - mdm: - apple_bm_server_token_bytes: | - Content-Type: application/pkcs7-mime; name="smime.p7m"; smime-type=enveloped-data - Content-Transfer-Encoding: base64 - ... rest of content ... - ``` - -##### mdm.apple_bm_cert_bytes - -This is the content of the Apple Business Manager certificate. The certificate is a PEM-encoded X.509 certificate that's typically generated via `fleetctl generate mdm-apple-bm`. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_BM_CERT_BYTES` -- Config file format: - ```yaml - mdm: - apple_bm_cert_bytes: | - -----BEGIN CERTIFICATE----- - ... PEM-encoded content ... - -----END CERTIFICATE----- - ``` - -##### mdm.apple_bm_key_bytes - -This is the content of the PEM-encoded private key for the Apple Business Manager. It's typically generated via `fleetctl generate mdm-apple-bm`. - -- Default value: "" -- Environment variable: `FLEET_MDM_APPLE_BM_KEY_BYTES` -- Config file format: - ```yaml - mdm: - apple_bm_key_bytes: | - -----BEGIN RSA PRIVATE KEY----- - ... PEM-encoded content ... - -----END RSA PRIVATE KEY----- - ``` - ##### mdm.apple_dep_sync_periodicity The duration between DEP device syncing (fetching and setting of DEP profiles). Only relevant if Apple Business Manager (ABM) is configured. diff --git a/docs/Contributing/Configuration-for-contributors.md b/docs/Contributing/Configuration-for-contributors.md index c6a9c51f31..08c2534366 100644 --- a/docs/Contributing/Configuration-for-contributors.md +++ b/docs/Contributing/Configuration-for-contributors.md @@ -2,6 +2,7 @@ - [Integrations](#integrations) - [SMTP-settings](#smtp-settings) +- [Mobile device management (MDM)](#mobile-device-management-mdm) - [Environment variables](#environment-variables) This document includes configuration files and settings that are helpful when developing or contributing to Fleet. @@ -362,6 +363,135 @@ Whether the SMTP server's SSL certificates should be verified. This can be turne verify_ssl_certs: false ``` +## Mobile device management (MDM) + +This section is a reference for the configuration required to turn on MDM features in production. + +If you're a Fleet contributor and you'd like to turn on MDM features in a local environment, see the guided instructions [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#mdm-setup-and-testing). + +##### mdm.apple_apns_cert_bytes + +The content of the Apple Push Notification service (APNs) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_APNS_CERT_BYTES` +- Config file format: + ```yaml + mdm: + apple_apns_cert_bytes: | + -----BEGIN CERTIFICATE----- + ... PEM-encoded content ... + -----END CERTIFICATE----- + ``` + +##### mdm.apple_apns_key_bytes + +The content of the PEM-encoded private key for the Apple Push Notification service (APNs). Typically generated via `fleetctl generate mdm-apple`. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_APNS_KEY_BYTES` +- Config file format: + ```yaml + mdm: + apple_apns_key_bytes: | + -----BEGIN RSA PRIVATE KEY----- + ... PEM-encoded content ... + -----END RSA PRIVATE KEY----- + ``` + +##### mdm.apple_scep_cert_bytes + +The content of the Simple Certificate Enrollment Protocol (SCEP) certificate. An X.509 certificate, PEM-encoded. Typically generated via `fleetctl generate mdm-apple`. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_SCEP_CERT_BYTES` +- Config file format: + ```yaml + mdm: + apple_scep_cert_bytes: | + -----BEGIN CERTIFICATE----- + ... PEM-encoded content ... + -----END CERTIFICATE----- + ``` + +The SCEP certificate/key pair [generated by Fleet](https://fleetdm.com/docs/using-fleet/MDM-setup#step-1-generate-the-required-files) expires every 10 years. It's recommended to never change these unless they were compromised. + +If your certificate/key pair was compromised and you change the pair, the disk encryption keys will no longer be viewable on all macOS hosts' **Host details** page until you turn disk encryption off and back on and the keys are [reset by the end user](https://fleetdm.com/docs/using-fleet/MDM-migration-guide#how-to-turn-on-disk-encryption). + +##### mdm.apple_scep_key_bytes + +The content of the PEM-encoded private key for the Simple Certificate Enrollment Protocol (SCEP). Typically generated via `fleetctl generate mdm-apple`. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_SCEP_KEY_BYTES` +- Config file format: + ```yaml + mdm: + apple_scep_key_bytes: | + -----BEGIN RSA PRIVATE KEY----- + ... PEM-encoded content ... + -----END RSA PRIVATE KEY----- + ``` + +##### mdm.apple_scep_challenge + +An alphanumeric secret for the Simple Certificate Enrollment Protocol (SCEP). Define a unique, static secret 32 characters in length and only include alphanumeric characters. + +> SCEP is commonly applied to a number of certificate use cases. Notably, Mobile Device Management (MDM) systems like Microsoft Intune and Apple MDM use SCEP for PKI certificate enrollment. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_SCEP_CHALLENGE` +- Config file format: + ```yaml + mdm: + apple_scep_challenge: scepchallenge + ``` + +##### mdm.apple_bm_server_token_bytes + +This is the content of the Apple Business Manager encrypted server token downloaded from Apple Business Manager. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_BM_SERVER_TOKEN_BYTES` +- Config file format: + ```yaml + mdm: + apple_bm_server_token_bytes: | + Content-Type: application/pkcs7-mime; name="smime.p7m"; smime-type=enveloped-data + Content-Transfer-Encoding: base64 + ... rest of content ... + ``` + +##### mdm.apple_bm_cert_bytes + +This is the content of the Apple Business Manager certificate. The certificate is a PEM-encoded X.509 certificate that's typically generated via `fleetctl generate mdm-apple-bm`. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_BM_CERT_BYTES` +- Config file format: + ```yaml + mdm: + apple_bm_cert_bytes: | + -----BEGIN CERTIFICATE----- + ... PEM-encoded content ... + -----END CERTIFICATE----- + ``` + +##### mdm.apple_bm_key_bytes + +This is the content of the PEM-encoded private key for the Apple Business Manager. It's typically generated via `fleetctl generate mdm-apple-bm`. + +- Default value: "" +- Environment variable: `FLEET_MDM_APPLE_BM_KEY_BYTES` +- Config file format: + ```yaml + mdm: + apple_bm_key_bytes: | + -----BEGIN RSA PRIVATE KEY----- + ... PEM-encoded content ... + -----END RSA PRIVATE KEY----- + ``` + ## Environment variables ### FLEET_ENABLE_POST_CLIENT_DEBUG_ERRORS diff --git a/website/config/routes.js b/website/config/routes.js index 3c62575c3f..8055fec263 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -522,7 +522,7 @@ module.exports.routes = { 'GET /learn-more-about/setup-abm': '/docs/using-fleet/mdm-setup#apple-business-manager-abm', 'GET /learn-more-about/renew-apns': '/docs/using-fleet/mdm-setup#renewing-apns', 'GET /learn-more-about/renew-abm': '/docs/using-fleet/mdm-macos-setup#renewing-abm', - + 'GET /learn-more-about/fleet-server-private-key': '/docs/using-fleet/fleet-server-configuration#server-private-key', // Sitemap // =============================================================================================================