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

[Patagonia121]

UPDATE: Closed this story and filed a testing ticket instead (TODO @noahtalerman). 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: #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: #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]

@noahtalerman @marko-lisica maybe this should be changed to: implement an IdP / LDAP integration, i.e., you could federate or pull in data from AD / LDAP / Okta / whatever based on the name of the user in the Directory Service which make available any user attribute in that system (email, manager, role, department, building, etc.) to populate configuration profiles.

[marko-lisica]

Hey @nonpunctual, thanks for the feedback. With this story we want to add way to use existing information (from device_mapping) as a variable in the configuration profile. I suggest filing a feature request for additional ways to add user info from IdP, LDAP, etc. to a host.

[nonpunctual]

Right. The Jamf LDAP integration allows the data in LDAP to become data in the Jamf db (effectively associating the user's LDAP data to the device record.) You can set LDAP data in Jamf to update every time a device submits inventory. This makes the user data available to be populated in config profile variables.

[noahtalerman]

Hey @dherder, @nonpunctual, and @willmayhone88 when you get the chance, can you please drop add comments w/ example workflows that require variables in configuration profiles? Thanks!

Please check out the user story in the issue description for context (it's changed).

[nonpunctual]

@noahtalerman It makes sense to have this feature be available in a Certificate payload in a Config Profile, but, ideally any attribute of a device record (or a limited subset of attributes) would be available to populate any field in a Configuration Profile.

1. add some user or system identifying string to an 802.1x certificate for secure auto-join to Wi-Fi https://support.apple.com/guide/deployment/connect-to-8021x-networks-depabc994b84/web
2. populate email address / UPN in cert for IdP / SSO authentication to SAML / OIDC app
3. Deploying a user identifying string in a custom certificate placed in Keychain for auth / signing to VPN or proxy or ???
4. automatically configure corporate email with email address / UPN via profile
5. automatically configure admin user account access to corporate tenant (Saas app, eg)
6. Displaying some given attribute of a device on screen as part of a Config Profile, eg, displaying the Asset Tag on the macOS login window (ie, asset tag is an arbitrary string that the org has defined. They may want to use that in a Config Profile for various reasons.)
7. Assigning custom room / building numbers in a Zoom room config profile

This is the list of variables available in Jamf for Config Profiles:

variable	description
$MANAGEMENTID	Device management ID assigned by Jamf Pro
$DEVICENAME	Mobile Device Name
$ASSET_TAG	Asset Tag
$SITENAME	Site Name
$SITEID	Site ID
$SERIALNUMBER	Serial Number
$UDID	UDID
$USERNAME	Username
$FULLNAME or $REALNAME	Full Name
$EMAIL	Email Address
$PHONE	Phone Number
$ROOM	Room
$POSITION	Position
$DEPARTMENTNAME	Department Name
$DEPARTMENTID	Department ID
$BUILDINGNAME	Building Name
$BUILDINGID	Building ID
$MACADDRESS	MAC Address
$JSSID	Jamf Pro API index
$PROFILEJSSID	Jamf Pro ID of the Configuration Profile
$EXTENSIONATTRIBUTE_#	Extension Attribute ID NumberNote: The ID number is found in the extension attribute URL. In the example URL below, "id=2" indicates the extension attribute ID number:https://JAMF_PRO_URL.jamfcloud.com/mobileDeviceExtensionAttributes.html?id=2&o=r

[noahtalerman]

Hey @zayhanlon heads up, this didn't get through drafting in the current design sprint (ends today).

Leaving it on the drafting board for next design sprint because we want to prioritize features that contribute to Jamf parity. Adding it to feature fest so other folks are aware of what we're prioritizing.

[nonpunctual]

@dherder what is your understanding of the need for this? I thought this was critical for customer-rosner but maybe that status has changed? Thanks.

[dherder]

@nonpunctual its critical for customer-starchik

[nonpunctual]

@noahtalerman @marko-lisica I agree this probably can't go later than the next design sprint as customer-starchik MDM migration is imminent & I am sure this is something they will probably need to test almost immediately as I believe it's tied to cert auth in their environment. cc @zayhanlon @dherder

[noahtalerman]

customer-starchik MDM migration is imminent & I am sure this is something they will probably need to test almost immediately as I believe it's tied to cert auth in their environment

@nonpunctual thanks! Do you know when they want to start testing?

[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:

• 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]

Closed this story and filed a testing ticket instead (TODO @noahtalerman). 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.