From a7967a398ccfb564bec5b01c614703d2a2b14fb9 Mon Sep 17 00:00:00 2001 From: Jordan Montgomery Date: Mon, 28 Apr 2025 11:30:56 -0400 Subject: [PATCH] Update DigiCert integration contributor doc for renewal (#28517) Updates contributor doc based on recently merged DigiCert renewal changes I'm not sure if leaving the "admin" on that last mermaid doc was the right thing to do but I wanted to make it clear this all happens automatically without admin intervention once setup --- docs/Contributing/MDM-DigiCert-Integration.md | 50 ++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/Contributing/MDM-DigiCert-Integration.md b/docs/Contributing/MDM-DigiCert-Integration.md index e408f98caf..c023e0ecd5 100644 --- a/docs/Contributing/MDM-DigiCert-Integration.md +++ b/docs/Contributing/MDM-DigiCert-Integration.md @@ -14,6 +14,10 @@ _Notes:_ - CA name should be treated as a unique identifier and never changed once set. The profiles (and potential renewals) are tied to the CA name. To cleanly change the CA name, remove any profiles using the old CA name (which will remove the associated certificates from devices), change the CA name, upload new profiles using the new CA name. - Although you can have multiple PKCS12 payloads in a profile, each CA can only be used once per profile. +- Certificates created prior to the renewal feature being added will not be automatically renewed. To make them eligible for automatic renewal, manually resend the DigiCert profile to the host +- Sometimes macOS keychain takes a bit to drop the prior certificate especially if you leave + Keychain Access open. If the prior certificate is being returned by OSQuery or you see it in + Keychain Access, most likely quitting Keychain Access and reopening it will fix this ## Architecture diagrams @@ -55,7 +59,7 @@ sequenceDiagram fleet->>fleet: Inject Fleet variables fleet->>+digicert: Get certificate digicert-->>-fleet: Certificate - fleet->>fleet: Save NotValidAfter date + fleet->>fleet: Save NotValidBefore, NotValidAfter dates, Serial number fleet->>+apple: Push notification (APNS) apple-->>-fleet: OK deactivate fleet @@ -76,6 +80,50 @@ sequenceDiagram fleet-->>-host: OK ``` +```mermaid +--- +title: Automatically renew existing DigiCert certificate before it expires +--- +sequenceDiagram + autonumber + actor admin as Admin + participant host as Host + participant fleet as Fleet server + participant digicert as DigiCert + participant apple as Apple + fleet->>fleet: Process cleanups then aggregations cron every hour + fleet->>fleet: Query Host MDM Managed Certificates table for DigiCert certificates
expiring soon(validity window > 30 days and not_valid_after < 30 days or
validity window < 30 days and not_valid_after < half validity window from
now) + fleet->>fleet: Mark host-profile association rows for expiring certificates for resend + + + fleet--)+fleet: Process profiles every 30 seconds + fleet->>fleet: Validate profile + fleet->>fleet: Decrypt API token + fleet->>fleet: Inject Fleet variables + fleet->>+digicert: Get certificate + digicert-->>-fleet: Certificate + fleet->>fleet: Save NotValidBefore, NotValidAfter dates, Serial number + fleet->>+apple: Push notification (APNS) + apple-->>-fleet: OK + deactivate fleet + + host--)+fleet: Idle message + fleet-->>-host: PKCS12 profile (DigiCert certificate) + activate host + host->>host: Add certificate to keychain + host->>host: Remove prior certificate from keychain
(once no longer in use - usually seconds to minutes) + host-->>-fleet: Acknowledged message + activate fleet + fleet-->>-host: Empty + + host->>+fleet: Read + fleet-->>-host: Get profiles command (once an hour) + + host->>+fleet: Write (profiles) + fleet->>fleet: PKCS12 profile Verified + fleet-->>-host: OK +``` + ## Sample PKCS12 profile ```xml