fleet icon indicating copy to clipboard operation
fleet copied to clipboard
verified publisher icon fleetdm

Deploy certificates from DigiCert and custom SCEP certificate authority on macOS

Open noahtalerman opened this issue 1 year ago • 7 comments

Goal

User story
As an IT admin,
I want Fleet to install a unique certificate (Common Name has unique host vitals) from my custom certificate authority (CA) or DigiCert on all my macOS hosts
so that I can grant end users access to Wi-Fi.

Key result

Deploy certificates from DigiCert and custom certificate authority (CA)

Original requests

  • #13420

Context

  • Product designer: @marko-lisica

Changes

Product

  • [x] UI changes: Figma link
  • [x] CLI (fleetctl) usage changes: No changes
  • [x] YAML changes: #26484
  • [x] REST API changes: #26484
  • [x] Fleet's agent (fleetd) changes: No changes
  • [x] GitOps mode changes: GitOps mode changes specified in Figma.
  • [x] Activity changes: PR here
  • [x] Permissions changes: PR to permissions guide here.
  • [x] Changes to paid features or tiers: Available to Fleet Premium only. PR to pricing table here.
  • [x] Transparency changes: No changes
  • [x] First draft of test plan added
  • [x] Other reference documentation changes: No changes
  • [ ] Once shipped, requester has been notified
  • [ ] Once shipped, dogfooding issue has been filed

Engineering

  • [x] Test plan is finalized
  • [ ] Feature guide changes:
    • Update existing NDES guide to cover all 3 types of CAs (NDES, custom SCEP and DigiCert)
    • I already made PR to do redirects for UI and redirects from the current NDES guide URL to the new URL (see here).
    • Mention that enrollment method for certificate profile made in DigiCert must be "REST API", otherwise Fleet can't use that profile to get certificate.
    • PR: #27439
  • [ ] Database schema migrations: #26602
  • [x] Load testing: Not needed

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

  • Requires load testing: No, because we don't expect a profiles to be deployed to all hosts. We expect profiles to be deployed gradually as part of enrolling new devices.
  • Risk level: High
  • Risk description: Largely new functionality for Fleet

Test plan

UI

  • [x] On /settings/integrations/mdm page there's no Simple Certificate Enrollment Protocol (SCEP) section.
  • [x] On /settings/integrations page there's new menu item "Certificates" that opens /settings/integrations/certificates page.
  • [x] On /settings/integrations/certificates page user first see empty state and CTA button to Add CA.
  • [x] When user adds certificate authority on /settings/integrations/certificates list of CAs appears and user can add more CAs.
  • [x] User can edit all certificate authorities from the list on /integrations/certificates/ page(edit action on row hover appears in the list)
  • [x] User can delete any CA by hovering over the row and selecting delete action. Confirmation modal should appear.
  • [x] User can add only one NDES CA configuration and in the Add CA modal NDES option gets disabled if one already exist. Make sure that customers that already have NDES configured have this option disabled when they upgrade Fleet version.
  • [x] Add CA button opens modal where user can choose from 3 CA types at the top: DigiCert, Custom SCEP, and NDES.
  • [x] When the user opens Add CA modal on /settings/integrations/certificates page and selects DigiCert, the user can't save the configuration until all fields are populated.
  • [x] In Add CA modal, when DigiCert is selected, the user can use only letters, numbers and underscores (no spaces) in "Name" input field, otherwise show error.
  • [x] In Add CA modal, when DigiCert is selected, if the user uses the name that's already used by another DigiCert CA, show error.
  • [x] Fleet should validate if the API token provided in Add CA modal > DigiCert form is valid and if not throw an error when user select "Add CA" button. Fleet should throw a generic message for any other error (e.g. network issue).
  • [x] When editing DigiCert CA user can't save configuration if all required fields aren't present.
  • [x] When creating DigiCert CA, user can't specify a DigiCert profile ID that has been deleted -- validation error.
  • [x] When the user opens Add CA modal and selects "Microsoft Network Device Enrollment Service (NDES)", the user can't save the configuration until all fields are populated.
  • [x] In Add CA modal > NDES, Fleet should validate if SCEP URL, Admin URL and credentials are valid and show errors specified in Figma.
  • [x] When editing NDES CA user can't save the configuration if all required fields aren't present.
  • [x] When the user opens Add CA modal on /settings/integrations/certificates page and selects "Custom Simple Certificate Enrollment Protocol (SCEP)", the user can't save the configuration until all required fields are populated.
  • [x] In Add CA modal, when "Custom SCEP" is selected, the user can use only letters, numbers and underscores (no spaces) in "Name" input field, otherwise show error.
  • [x] In Add CA modal, when "Custom SCEP" is selected, if the user uses the name that's already used by another custom SCEP CA, show error.
  • [x] In Add CA modal > Custom SCEP, Fleet should validate if the SCEP URL is valid and show errors specified in Figma.
  • [x] When editing custom SCEP CA user can't save the configuration if all required fields aren't present.
  • [x] Fleet should restrict configuration profile upload if there are non-existing variables prefixed with $FLEET_VAR_. E.g. user misspells the name of the variable.
  • [x] Make sure that all variables defined in Figma are working.
  • [x] On hosts/:id page, in OS settings modal error should appear if the host doesn't have an IdP email and the user specified $FLEET_VAR_HOST_END_USER_EMAIL_IDP. in profile. (this is error)
  • [x] Make sure that "Add CA", edit and delete actions are disabled on /settings/integrations/certificates page when GitOps mode is enabled and tooltips appear on hover over.
  • [x] Make sure that activities are generated when the user adds/edits/deletes CA.
  • [x] Make sure that only admin and gitops role can add/edit/delete certificate authorities.
  • [x] On Host details > OS settings modal, make sure that the user can see error message specified in Figma when API token provided in CA configuration isn't valid (this case happens before the profile is delivered because Fleet wasn't able to get certificate from Digicert).
  • [x] On Host details > OS settings modal, make sure that the user can see error message specified in Figma if Profile GUID specified in CA configuration doesn't exist (this case happens before the profile is delivered because Fleet wasn't able to get certificate from Digicert).
  • [x] On Host details > OS settings modal, make sure that the user can see error message specified in Figma with error message directly from from DigiCert if it's not one of the 2 cases above (this case happens before the profile is delivered because Fleet wasn't able to get certificate from Digicert).
  • [x] On Host details > OS settings modal, make sure that the user can still see errors from MDM protocol related to DigiCert certificate profile (e.g. when .mobileconfig XML is malformed)

GitOps

  • [x] User can add/edit/delete certificate authorities under org_settings.integrations.
  • [x] Make sure that we validate "name" for DigiCert and Custom SCEP CAs.
  • [x] Make sure to validate API token for DigiCert CA.
  • [x] Make sure to validate SCEP URL and challenge for custom SCEP CA.
  • [x] Fleet GitOps should restrict configuration profile upload if there are non-existing variables prefixed with $FLEET_VAR_. E.g. user misspells the name of the variable.

API

  • [x] User can view certificate authorities via GET /api/v1/fleet/config
  • [x] User can add/edit/delete certificate authorities via PATCH /api/v1/fleet/config endpoint
  • [x] Make sure that we validate "name" for DigiCert and Custom SCEP CAs.
  • [x] API should restrict configuration profile upload if there are non-existing variables prefixed with $FLEET_VAR_. E.g. user misspells the name of the variable.
  • [x] Make sure that GET /api/v1/fleet/hosts/:id response for host.mdm.os_settings.profile[i].detail looks like specified in Figma when API token provided in CA configuration isn't valid (this case happens before the profile is delivered because Fleet wasn't able to get certificate from Digicert).
  • [x] Make sure that GET /api/v1/fleet/hosts/:id response for host.mdm.os_settings.profile[i].detail looks like specified in Figma when profile_id token provided in CA configuration isn't valid (this case happens before the profile is delivered because Fleet wasn't able to get certificate from Digicert).

Happy path (DigiCert) ✅

  1. Go to Settings > Integrations > Certificates
  2. Select Add CA and select DigiCert
  3. Fill the form with the necessary information from DigiCert One platform and select Add CA. Use DIGICERT_WIFI as a name.
  4. Create configuration profile (PKCS12), using an example from Apple docs here
  5. Replace the password field with $FLEET_VAR_DIGICERT_PASSWORD_DIGICERT_WIFI and replace data field with $FLEET_VAR_DIGICERT_DATA_DIGICERT_WIFI
  6. Upload configuration profile to Fleet
  7. Go to host details and verify that the profile is installed
  8. Use a query to check if certificate is installed on the host
  9. Deploy one profile to 2 or more hosts -- all of them should get certs.

Happy path (custom SCEP) ✅

  1. Go to Settings > Integrations > Certificates
  2. Select Add CA and select Custom Simple Certificate Enrollment Protocol (SCEP)
  3. Fill the form with necessary information and select Add CA. Use SCEP_WIFI as name.
    1. Create a configuration profile (SCEP), using an example from Apple docs here
  5. Replace challenge field with $FLEET_VAR_CUSTOM_SCEP_CHALLENGE_SCEP_WIFI and replace URL field with $$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_SCEP_WIFI.
  6. Upload configuration profile to Fleet
  7. Go to host details and verify that the profile is installed
  8. Use a query to check if a SCEP certificate is installed on the host
  9. Deploy one profile to 2 or more hosts -- all of them should get certs.

DigiCert + custom SCEP ✅

  1. It is possible to put both a DigiCert PKCS12 payload and the custom SCEP payload into one profile. The host will get 2 certificates. Use such a profile as part of the above testing.

Testing notes

Confirmation

  1. [ ] Engineer: Added comment to user story confirming successful completion of test plan.
  2. [ ] QA: Added comment to user story confirming successful completion of test plan.

noahtalerman avatar Jan 28 '25 18:01 noahtalerman

@lukeheath I assigned you because I added P2. More info on why here: https://github.com/fleetdm/fleet/issues/26436#issuecomment-2672622235

cc @georgekarrv

noahtalerman avatar Feb 20 '25 20:02 noahtalerman

@noahtalerman Agreed this is a P2. George is going to dig into it and review with the team, and get us a t-shirt size so we can determine when it makes sense to move on this.

lukeheath avatar Feb 20 '25 22:02 lukeheath

UPDATE: @noahtalerman: For when Fleet adds the ability to deploy certificates to Windows & Linux workstations.

User requested this because they want the private keys for certificates on Windows and Linux workstations to be in the TPM chip so they can't be accessed by the end user or other software.

  • @marko-lisica: Equivalent of Keychain on macOS?
    • @noahtalerman: Sounds like this is level of security higher than Windows equivalent for Keychain (certificate store): https://polansky.co/blog/tpm-backed-certificates-windows/#:~:text=Normally%20when%20you,get%20into%20it.

@noahtalerman One other piece of feedback we got today in the channel from customer-pingali is that in the future it would be nice if Fleet could generate the key material for MDM-issued certs in the TPM of the device.

"A more specific use case is that some migration tools seem to pull the private keys along to the new machine (trying to be helpful). A company can mitigate this directly, but it would be easier if it just wasn't possible to migrate private keys, in the same way there just isn't a way to migrate biometric data."

Patagonia121 avatar Feb 21 '25 00:02 Patagonia121

@georgekarrv just a reminder that this user story is ready to spec. Can you please complete the TODOs in the "Engineering" section so that we can estimate this one this week?

noahtalerman avatar Feb 25 '25 14:02 noahtalerman

Here's a video to show how integration with DigiCert will look (how to make certificate template), and what fields in the DigiCert's API we use.

Note: It's not public, as there are customer/prospect data visible.

Video: https://drive.google.com/file/d/178rE8MsSRn2paRhu9INNx15jXvMCEiw0/view?usp=drive_link

cc @noahtalerman @getvictor

marko-lisica avatar Feb 27 '25 12:02 marko-lisica

I QA'd the backend portion and cleared the checkmarks. @ghernandez345 Please clear your checkmarks after you're done.

@georgekarrv I recommend only moving the issue to the QA column after engineers have gone through the testplan.

getvictor avatar Mar 21 '25 19:03 getvictor

QA Notes:

I completed the test plan and verified all unreleased bugs have been patched.

All flows are working as expected including errors.

Image

PezHub avatar Apr 01 '25 18:04 PezHub

Hey @noahtalerman, It's only left to ping customer success, and I'm assigning it to you

marko-lisica avatar Apr 14 '25 19:04 marko-lisica

In the cloud city, Certificates deployed wide, Mac users connect, glide.

fleet-release avatar Apr 15 '25 19:04 fleet-release