Add computer name, serial number, and UUID as variables in macOS configuration profiles

[Patagonia121]

UPDATE: Closed this story and filed a testing ticket instead (#21294). We discovered that the MDM protocol allows users to set computer name, serial number, and UUID in the SCEP payload. Learn more here.

(noahtalerman 2024-07-12)

---

Goal

User story
As a Client Platform Engineer,
I want to add computer name, serial number, and UUID as a variable to a configuration profile
so that Fleet, for each host, populates this variable with host specific information. This way, I can install a unique SCEP certificate to enable Okta Verify on my macOS hosts.

Context

• Product designer: @marko-lisica

We should think about what it will take to implement the same feature for scripts and what approach should we take in order to make this work for both profiles and scripts (i.e. considering scripts while developing for profiles so we can reuse this when we start working on scripts).

Changes

Product

• UI changes: Figma link
• CLI changes: Figma link
• Outdated documentation changes: Docs changes: Variables in macOS configuration profile #20231
• Changes to paid features or tiers: Available in Fleet Premium only
• Other changes:
  • Supported variables are: $FLEET.HOST.COMPUTER_NAME, $FLEET.HOST.HARDWARE_SERIAL, and $FLEET.HOST.UUID
  • Fleet server should parse profiles on upload and reject variables that are not supported. Fleet should reject only variables that start with $FLEET. but not supported.
    • If user specify for ex. $SERIAL_NUMBER Fleet will let this through as is, since it's not supported variable and doesn't have FLEET prefix
  • Before installing the profile to a host, Fleet should replace the variable with the respective value from the host.
  • GitOps should not replace variables that start with $FLEET.. It's still possible to use $ENV_VAR without FLEET prefix.
• Redirect link for docs: Redirect: Variables in macOS configuration profile #20233

Engineering

• Database schema migrations: TODO
• Load testing: TODO

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

QA

Risk assessment

• Risk level: Low

Manual testing steps

1. Create config profiles with variables (whatever is supported as part of this MVP)
2. Deploy config profiles to hosts
3. Validate the data is ingested in Fleet and available

Testing notes

Confirmation

1. Engineer (@____): Added comment to user story confirming successful completion of QA.
2. QA (@____): Added comment to user story confirming successful completion of QA.

[dherder]

@noahtalerman we will need this to support the "managed" status in SCEP workflows involving Okta Verify. Please refer to https://help.okta.com/oie/en-us/content/topics/identity-engine/devices/okta-ca-static-scep-macos-jamf.htm#Create for backgound

[noahtalerman]

Hey @Patagonia121 heads up, this story was prioritized during feature fest.

Aiming to ship an improvement in the next 6 weeks.

[noahtalerman]

Moved the original issue description here:

Variable substitution in macOS profiles allows for dynamically creating profiles based on various attributes, for instance if you would want to create a certificate payload for each machine you wouldn't want to make 10,000 profiles you would want to make one that would send the profile with variable $USER prefilled

1. this becomes incredibly powerful if you could pass the results of a query into the payload

[noahtalerman]

Hey @Patagonia121 heads up, we didn't get to this in the last design sprint.

Bringing it back to feature fest.

[noahtalerman]

Turing this into an air guitar so that we can better understand the problem.

[nonpunctual]

@dherder @noahtalerman @zwass Dave or Zach may have more up-to-date timelines than me. I can also make sure they are asked at the next CS call we have with them.

[dherder]

@noahtalerman seethis blogpost regarding dynamic scep profiles with computername and UDID as variables in a Platform SSO use case

[noahtalerman]

seethis blogpost regarding dynamic scep profiles with computername and UDID as variables in a Platform SSO use case

Important part here:

Once Fleet supports setting these variables in the SCEP config profile, Okta users can keep local macOS credentials sycned w/ Fleet + Okta.

cc @marko-lisica @dherder

[noahtalerman]

Hey @nonpunctual I pulled the ~feature fest off because this story is in the current design sprint :)

[noahtalerman]

From customer-reedtimmer's user stories:

Added as a blocker due to Smallstep certification deployment requiring including host’s serial in generated SCEP payload.

FYI @marko-lisica it sounds like we might want to support serial as a variable in this first pass for deploying SCEP certificates for Smallstep. Needs confirmation.

[noahtalerman]

Hey @marko-lisica, I just watched the Gong recording (internal) from the design review. We do already support GitHub environment variables and they use the $ENV_VAR syntax. The story is here:

• GitOps: Support environment variables in configuration profiles #17309

We dogfood this feature today in the Google Chrome config profile here.

So, I think we have a couple options:

1. Use the same $VAR syntax for Fleet's reserved host vital variables (ex. $HARDWARE_SERIAL. To @georgekarrv's point, this means we don't want to validate variables because a user can specify any variable as an environment variable. In the odd scenario the user specifies a reserved host vital variable an an env variable, we'd likely override the env variable (and document this behavior).
2. Use a different syntax for Fleet's reserved host vitals variables. We can add validation in this case.

If we're focused on users coming from Jamf (we are), option (1) makes sense. That said, I'm not sure it's the best UX. We can't throw error messages which makes it hard to debug.

@getvictor and @lucasmrod any thoughts? Missing other options?

[georgekarrv]

We mighty have a conflict now then. How do you differentiate between at upload time vs runtime. Let's discuss in design tomorrow

[getvictor]

I recommend option 2 -- use a different syntax.

Option 3. Change the syntax of gitops env vars and have runtime use the normal $ENV_VAR syntax.

[noahtalerman]

Hey @marko-lisica heads up, I forgot that we already have one reserved variable for software install scripts: $INSTALLER_PATH

More context in Slack here: https://fleetdm.slack.com/archives/C03C41L5YEL/p1714577714118779

Does our latest plan work with this variable? Do we need to make any changes?

[nonpunctual]

https://support.apple.com/guide/deployment/variables-settings-for-mdm-payloads-dep04666af94/1/web/1.0

[roperzh]

@nonpunctual we were talking about that doc the other day, it's truly awesome. For full context for Marko and Noah, AFAIK it only works for certain payloads (SCEP and VPN)

[marko-lisica]

@noahtalerman $INSTALLER_PATH variable doesn't conflict with configuration profile variables nor GitOps environment variables. See discussion below:

[noahtalerman]

UPDATE: Let's write a guide for this instead of just testing it (noahtalerman). Guide issue is here: #21294

Closed this story and filed a testing ticket instead (#21294). We discovered that the MDM protocol allows users to set computer name, serial number, and UUID in the SCEP payload:

Goal

User story
As a Client Platform Engineer,
I want to know how to deploying a profile (SCEP payload) in Fleet w/ computer name, serial number, and UUID as variables
so that Fleet, for each host, populates this variable with host specific information. This way, I can install a unique SCEP certificate to enable Okta Verify on my macOS hosts.

[fleet-release]

Unique certificates,
Like leaves in a cloud city,
Secure, yet distinct.

[noahtalerman]

Arg! I forgot to file the testing ticket.

Filed a guide ticket instead here: #21294