diff --git a/articles/connect-end-user-to-wifi-with-certificate.md b/articles/connect-end-user-to-wifi-with-certificate.md index 8c2fdf0a53..33a0301f37 100644 --- a/articles/connect-end-user-to-wifi-with-certificate.md +++ b/articles/connect-end-user-to-wifi-with-certificate.md @@ -4,13 +4,7 @@ _Available in Fleet Premium_ Fleet can help your end users connect to Wi-Fi or VPN by deploying certificates from your certificate authority (CA). Fleet currently supports [DigiCert](https://www.digicert.com/digicert-one), [Microsoft NDES](https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/network-device-enrollment-service-overview), custom [SCEP](https://en.wikipedia.org/wiki/Simple_Certificate_Enrollment_Protocol) server, and [Hydrant](https://www.hidglobal.com/solutions/pki-service). -Fleet will automatically renew certificates 30 days before expiration. If an end user is on vacation (offline for more than 30 days), their certificate might expire, and they'll lose access to Wi-Fi or VPN. To reconnect them, ask your end users to temporarily connect to a different network so that Fleet can deliver a new certificate. - -> Currently, for NDES and custom SCEP CAs, Fleet requires that the ⁠`$FLEET_VAR_SCEP_RENEWAL_ID` variable is in the certificate's CN (Common Name) for automatic renewal to work. Since the CN has a maximum length of 64 characters, any characters beyond this limit get truncated, causing the renewal to fail. -> -> The ⁠`$FLEET_VAR_SCEP_RENEWAL_ID` is a 36 character UUID. Please make sure that any additional variables or content combined with it do not exceed the remaining 28 characters. -> -> If automatic renewal fails, you can resend the configuration profile manually on the host's **Host details** page, the end user's **Fleet Desktop > My Device** page, or via [Fleet's API](https://fleetdm.com/docs/rest-api/rest-api#resend-custom-os-setting-configuration-profile). +Fleet will automatically renew certificates before expiration. Learn more in the [Renewal section](#renewal). ## DigiCert @@ -490,7 +484,47 @@ SELECT 1 FROM certificates WHERE path = '/opt/company/certificate.pem' AND not_v 3. On the **Policies** page, select **Manage automations > Scripts**. Select your newly-created policy and then in the dropdown to the right, select your newly created certificate issuance script. 4. Now, any host that doesn't have a certificate in `/opt/company/certificate.pem` or has a certificate that expires in the next 30 days will fail the policy. When the policy fails, Fleet will run the script to deploy a new certificate! -## How the SCEP proxy works +## Renewal + +Fleet will automatically renew certificates 30 days before expiration. If an end user is on vacation (offline for more than 30 days), their certificate might expire, and they'll lose access to Wi-Fi or VPN. To reconnect them, ask your end users to temporarily connect to a different network so that Fleet can deliver a new certificate. + +If certificates are valid for less than 30 days, automatically renewal happens halfway through the validity period. For example, if a certificate is valid for 20 days, Fleet wil renew the certificate 10 days before it expires. + +> Currently, for NDES and custom SCEP CAs, Fleet requires that the ⁠`$FLEET_VAR_SCEP_RENEWAL_ID` variable is in the certificate's CN (Common Name) for automatic renewal to work. Since the CN has a maximum length of 64 characters, any characters beyond this limit get truncated, causing the renewal to fail. +> +> The ⁠`$FLEET_VAR_SCEP_RENEWAL_ID` is a 36 character UUID. Please make sure that any additional variables or content combined with it do not exceed the remaining 28 characters. +> +> If automatic renewal fails, you can resend the configuration profile manually on the host's **Host details** page, the end user's **Fleet Desktop > My Device** page, or via [Fleet's API](https://fleetdm.com/docs/rest-api/rest-api#resend-custom-os-setting-configuration-profile). + +## Advanced + +### User scoped certificates + +You can also upload a certificate to be installed in the login keychain of the managed user on a +macOS host using a user-scoped configuration profile. + +1. **Add your CA as before** + Use the above steps to integrate your CA with Fleet. +1. **Create a certificate payload** + Use your preferred tool (e.g., Apple Configurator or a `.mobileconfig` generator) to create a configuration profile that includes your certificate. +2. **Ensure the payload is scoped to the user** + In the payload, set the `PayloadScope` to `User`. This tells macOS to install the certificate in the user’s login keychain instead of the system keychain. +3. **Upload the configuration profile to Fleet** + Navigate to **Controls > OS settings > Custom settings** in the Fleet UI. Upload the `.mobileconfig` profile you created. +4. **Assign the profile to the correct hosts** + Use Fleet’s targeting filters to assign the profile to the appropriate hosts. The certificate will be installed in the login keychain of the user currently logged in on each device. + +### Editing ceritificate configuration profiles on Apple (macOS, iOS, iPadOS) hosts + +When you edit a certificate configuration profile for Apple hosts, via GitOps, a new certificate will be added to each hosts' Keychain and the old certificate will be removed. It takes a couple minutes for the old certificate to be removed. + +### Assumptions and limitations + +* NDES SCEP proxy is currently supported for macOS devices via Apple config profiles. Support for DDM (Declarative Device Management) is coming soon, as is support for iOS, iPadOS, Windows, and Linux. +* Fleet server assumes a one-time challenge password expiration time of 60 minutes. +* On Windows, SCEP challenge strings should NOT include `base64` encoding or special characters such as `! @ # $ % ^ & * _ ()` + +### How the SCEP proxy works Fleet acts as a middleman between the host and the NDES or custom SCEP server. When a host requests a certificate from Fleet, Fleet requests a certificate from the NDES or custom SCEP server, retrieves the certificate, and sends it back to the host. @@ -513,28 +547,6 @@ Custom SCEP proxy: to the host with a new passcode if the host requests a certificate after the passcode has expired. - The static challenge configured for the custom SCEP server remains in the SCEP profile. -## Assumptions and limitations - -* NDES SCEP proxy is currently supported for macOS devices via Apple config profiles. Support for DDM (Declarative Device Management) is coming soon, as is support for iOS, iPadOS, Windows, and Linux. -* Fleet server assumes a one-time challenge password expiration time of 60 minutes. -* On Windows, SCEP challenge strings should NOT include `base64` encoding or special characters such as `! @ # $ % ^ & * _ ()` - -## How to deploy certificates to a user's login keychain - -You can also upload a certificate to be installed in the login keychain of the managed user on a -macOS host using a user-scoped configuration profile. - -1. **Add your CA as before** - Use the above steps to integrate your CA with Fleet. -1. **Create a certificate payload** - Use your preferred tool (e.g., Apple Configurator or a `.mobileconfig` generator) to create a configuration profile that includes your certificate. -2. **Ensure the payload is scoped to the user** - In the payload, set the `PayloadScope` to `User`. This tells macOS to install the certificate in the user’s login keychain instead of the system keychain. -3. **Upload the configuration profile to Fleet** - Navigate to **Controls > OS settings > Custom settings** in the Fleet UI. Upload the `.mobileconfig` profile you created. -4. **Assign the profile to the correct hosts** - Use Fleet’s targeting filters to assign the profile to the appropriate hosts. The certificate will be installed in the login keychain of the user currently logged in on each device. -