Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-04-21 13:37:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 91

Deploy certificates guide: Cleanup and add note about PayloadCertificateAnchorUUID

Browse source
This commit is contained in:
Noah Talerman 2026-04-17 12:49:50 -05:00 committed by GitHub
parent 712e31d716
commit f025de07ad
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 26 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
articles/connect-end-user-to-wifi-with-certificate.md
View file

@ -2,20 +2,20 @@
_Available in Fleet Premium_
Fleet can help your end users connect to third-party tools like Wi-Fi or VPN by deploying certificates from your certificate authority (CA). Fleet currently supports [Okta](#okta), [DigiCert](#digicert), [Microsoft NDES](#microsoft-ndes), [Smallstep](#smallstep), [Hydrant](#hydrant), and a custom [SCEP](#custom-scep-simple-certificate-enrollment-protocol) or [EST](#custom-est-enrollment-over-secure-transport) server.
Fleet can help your end users connect to third-party tools like Wi-Fi or VPN by deploying certificates from your certificate authority (CA). Currently, these are supported platforms for each CA:
- [Okta](#okta): macOS, iOS, and iPadOS
- [DigiCert](#digicert): macOS, iOS, and iPadOS
- [Microsoft NDES](#microsoft-ndes): macOS, iOS, iPadOS and Windows
- [Smallstep](#smallstep): macOS, iOS, and iPadOS
- [Hydrant](#hydrant): Linux
- [Any SCEP (Simple Certificate Enrollment Protocol) CA](#any-scep-simple-certificate-enrollment-protocol-ca): macOS, Windows, iOS, iPadOS, and Android
- [Any EST (Enrollment over Secure Transport) CA](#any-est-enrollment-over-secure-transport-ca): Linux
Fleet will automatically renew certificates on Apple (macOS, iOS, iPadOS), Windows, and Android hosts before expiration. Learn more in the [Renewal section](#renewal).
To deploy certificates on a self-hosted Fleet instance, you'll need to configure a [server private key](https://fleetdm.com/docs/configuration/fleet-server-configuration#server-private-key).
To automatically connect Apple (macOS, iOS, iPadOS) hosts to Wi-Fi without end user action, in the Wi-Fi payload, set the `PayloadCertificateAnchorUUID` ([Apple docs](https://developer.apple.com/documentation/devicemanagement/wifi/eapclientconfiguration-data.dictionary#:~:text=PayloadCertificateAnchorUUID)) to the certificate payloads UUID.
Currently, these are supported platforms for each certificate authority:
- **Okta**: macOS, iOS, and iPadOS
- **DigiCert**: macOS, iOS, and iPadOS
- **Microsoft NDES**: macOS, iOS, iPadOS and Windows
- **Smallstep**: macOS, iOS, and iPadOS
- **Hydrant**: Linux
- **Custom SCEP server**: macOS, Windows, iOS, iPadOS, and Android
- **Custom EST**: Linux
To deploy certificates on a self-hosted Fleet instance, you'll need to configure a [server private key](https://fleetdm.com/docs/configuration/fleet-server-configuration#server-private-key).
## Okta
@ -143,9 +143,6 @@ When Fleet delivers the profile to your hosts, Fleet will replace the variables.
</plist>
```
## Microsoft NDES
The following steps show how to deploy [Microsoft NDES](https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/network-device-enrollment-service-overview) certificates.
@ -629,13 +626,13 @@ SELECT 1 FROM certificates WHERE path = '/opt/company/certificate.pem' AND not_v
The following steps show how to deploy certificates from any certificate authority that supports the [SCEP protocol](https://en.wikipedia.org/wiki/Simple_Certificate_Enrollment_Protocol) certificate authority (CA).
### Step 1: Connect Fleet to a custom SCEP server
### Step 1: Connect Fleet to a SCEP CA
1. In Fleet, head to **Settings > Integrations > Certificates**.
2. Select the **Add CA** button and select **Custom** in the dropdown.
2. Select the **Add CA** button and select **Custom Simple Certificate Enrollment Protocol (SCEP)** in the dropdown.
3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (for example, "WIFI_AUTHENTICATION"). This name will be used later as a variable name in a configuration profile.
4. Add your **SCEP URL** and **Challenge**.
6. Select **Add CA**. Your custom SCEP certificate authority (CA) should appear in the list in Fleet.
6. Select **Add CA**. Your SCEP certificate authority (CA) should appear in the list in Fleet.
### Step 2: Add SCEP configuration profile to Fleet
@ -667,13 +664,13 @@ How to deploy SCEP certificates to Android hosts:
2. In Fleet, head to **Controls > OS settings > Certificates** and select **Add certificate**.
3. In **Name**, enter a name for the certificate (e.g., "wifi-certificate"). This name is used as the certificate alias to reference in configuration profiles (e.g. [WiFi configuration](https://developers.google.com/android/management/configure-networks#eap_authentication)).
4. In **Certificate authority**, select the custom SCEP CA you created in step 1.
4. In **Certificate authority**, select the SCEP CA you created in step 1.
5. In **Subject name**, enter the certificate's subject name (SN). Separate subject fields by a ",". You can use [Fleet's host variables](https://fleetdm.com/docs/configuration/yaml-files#variables) to make the certificate unique to each host. For example: `CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL`.
6. Select **Save**. Fleet will deploy the certificate to your Android hosts.
If something goes wrong, errors will appear on each host's **Host details > OS settings**.
How does this work? Fleet installs the "Fleet" Android app on each host. Every 15 minutes, the app checks for new certificates, retrieves any from the custom SCEP CA, and installs them in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore).
How does this work? Fleet installs the "Fleet" Android app on each host. Every 15 minutes, the app checks for new certificates, retrieves any from the SCEP CA, and installs them in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore).
#### Example configuration profiles
@ -872,14 +869,14 @@ The flow for EST is similar to Hydrant, and differs from the other certificate a
This step will vary between providers. EST servers require a `username` and `password` for authentication. These may be obtained from your company's certificate authority administrator.
### Step 2: Connect Fleet to the custom EST server
### Step 2: Connect Fleet to the EST server
1. In Fleet, head to **Settings > Integrations > Certificates**.
2. Select **Add CA** and then choose **Custom EST Proxy** in the dropdown.
2. Select **Add CA** and then choose **Custom Enrollment over Secure Transport (EST)** in the dropdown.
3. Add a **Name** for your certificate authority. The best practice is to create a name based on your use case in all caps snake case (ex. "WIFI_AUTHENTICATION").
4. Add your Custom EST Proxy **URL**.
4. Add your EST **URL**.
5. Add the username and password as the **Username** and **Password** in Fleet respectively.
6. Click **Add CA**. Your Custom EST Proxy certificate authority (CA) should appear in the list in Fleet.
6. Click **Add CA**. Your EST certificate authority (CA) should appear in the list in Fleet.
### Step 3: Create a custom script
@ -958,7 +955,7 @@ If an end user is on vacation (offline for more than 30 days), their certificate
Fleet automatically retries failed certificate delivery for macOS, iOS, iPadOS, Windows, and Android hosts. Apple and Android certificates are attempted up to 4 times (1 initial attempt + 3 retries). Currently, Windows are attempted only once (4 times [coming soon](https://github.com/fleetdm/fleet/issues/42981)).
> Currently, for NDES, Smallstep, and custom SCEP CAs, Fleet requires that the ⁠`$FLEET_VAR_SCEP_RENEWAL_ID` variable is in the certificate's OU (Organizational Unit) for automatic renewal to work for Apple and Windows hosts. For some CAs, including [NDES](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/plan/active-directory-domain-services-maximum-limits?utm_source=chatgpt.com#:~:text=OU%20names%20can%20only%20be%2064%20characters%20long.), the OU has a maximum length of 64 characters so any characters beyond this limit get truncated, causing the renewal to fail.
> Currently, for NDES, Smallstep, and SCEP CAs, Fleet requires that the ⁠`$FLEET_VAR_SCEP_RENEWAL_ID` variable is in the certificate's OU (Organizational Unit) for automatic renewal to work for Apple and Windows hosts. For some CAs, including [NDES](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/plan/active-directory-domain-services-maximum-limits?utm_source=chatgpt.com#:~:text=OU%20names%20can%20only%20be%2064%20characters%20long.), the OU has a maximum length of 64 characters so 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.
>
@ -984,7 +981,7 @@ When you edit a certificate configuration profile for Apple hosts, via GitOps, a
### HTTP signatures
If you're deploying certificates from a [custom EST](#custom-est-enrollment-over-secure-transport) certificate authority, you can use HTTP signatures instead of a Fleet API token to authenticate requests to Fleet's ["Request certificate" endpoint](https://fleetdm.com/docs/rest-api/rest-api#request-certificate).
If you're deploying certificates from an [EST](#any-est-enrollment-over-secure-transport-ca) certificate authority, you can use HTTP signatures instead of a Fleet API token to authenticate requests to Fleet's ["Request certificate" endpoint](https://fleetdm.com/docs/rest-api/rest-api#request-certificate).
This is only supported on Linux hosts with TPM (Trusted Platform Module) hardware that enroll to Fleet using a Fleet agent generated (`fleetctl package`) with the `--fleet-managed-host-identity-certificate` flag.
@ -1015,7 +1012,7 @@ fetch_cert -ca <EST-CA-ID> -fleeturl "<Fleet-server-URL>" -csr CustomerUserNetwo
* NDES SCEP proxy is currently supported for macOS and Windows devices. Support for DDM (Declarative Device Management) is coming soon, as is support for iOS, iPadOS, 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 `! @ # $ % ^ & * _`, and Common Names (CN) should NOT include `+` characters.
* The Windows SCEP client adds ⁠/pkiclient.exe to the SCEP server URL. When using Fleet's custom SCEP proxy to deploy certificates, Fleet removes it, allowing you to use non-NDES SCEP servers.
* The Windows SCEP client adds ⁠/pkiclient.exe to the SCEP server URL. When using Fleet's SCEP proxy to deploy certificates, Fleet removes it, allowing you to use non-NDES SCEP servers.
* On **Windows** hosts, Fleet will not verify the SCEP profile via osquery. Fleet will mark it as verified, if a successful request went through, even if the certificate is not present.
* On **Windows** hosts, Fleet will not remove deployed certificates when configuration profiles are removed from Fleet or when host is transfered to another fleet.
@ -1031,7 +1028,7 @@ If NDES returns `pkiStatus=FAILURE, failInfo=badRequest`, the NDES password cach
### 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.
Fleet acts as a middleman between the host and the NDES or SCEP server. When a host requests a certificate from Fleet, Fleet requests a certificate from the NDES or SCEP server, retrieves the certificate, and sends it back to the host.
Certificates will appear in the System Keychain on macOS. During the profile installation, the OS generates several temporary certificates needed for the SCEP protocol. These certificates may be briefly visible in the Keychain Access app on macOS. The CA certificate must also be installed and marked as trusted on the device for the issued certificate to appear as trusted. The IT admin can send the CA certificate in a separate [CertificateRoot profile](https://developer.apple.com/documentation/devicemanagement/certificateroot?language=objc)
@ -1044,13 +1041,13 @@ NDES SCEP proxy:
- Resends the configuration profile to the host if the one-time challenge password has expired.
- If the host has been offline and the one-time challenge password is more than 60 minutes old, Fleet assumes the password has expired and will resend the profile to the host with a new one-time challenge password.
Custom SCEP proxy:
SCEP proxy:
- Generates a one-time passcode that is added to the URL in the SCEP profile.
- When a host makes a certificate request via the URL, the passcode is validated by Fleet prior to retrieving a certificate from the custom SCEP server.
- When a host makes a certificate request via the URL, the passcode is validated by Fleet prior to retrieving a certificate from the SCEP server.
- This Fleet-managed passcode is valid for 60 minutes. Fleet automatically resends the SCEP profile
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.
- The static challenge configured for the SCEP server remains in the SCEP profile.
### How to get the CAThumbprint for Windows SCEP profiles