Supported non-admin service identity for a macOS LaunchDaemon

I'm developing a private macOS application on an Apple-silicon Mac mini running macOS Golden Gate 27.2.

I'm evaluating a system LaunchDaemon running under a dedicated, non-administrator identity that cannot log in interactively. A separate desktop application would communicate with the daemon through authenticated local IPC.

Before implementing this architecture, I would like to establish the officially supported approach.

My main question:

What is the Apple-supported method for creating and maintaining a dedicated, non-administrator, non-interactive service identity for a system LaunchDaemon on macOS 27.2?

In particular:

  1. Is there a documented procedure for creating, restricting, disabling, recovering and eventually removing this identity?
  2. Are dscl, sysadminctl or another account-management mechanism supported for this purpose?
  3. Can a LaunchDaemon run under this identity without an interactive user login, including when registered through SMAppService?
  4. Are there any secure-token, FileVault, volume-ownership or keychain restrictions that would affect this design?

If a dedicated non-login service identity is not a supported architecture, what alternative does Apple recommend?

I'd particularly appreciate links to official Apple documentation or guidance from Apple engineers.

Thank you.

Answered by DTS Engineer in 915636022

macOS’s support for role accounts is not particularly strong. There are (at least :-) four parts to this:

  1. Creating the role account.
  2. Using the role account in your launchd daemon.
  3. Handling the role account execution context.
  4. Keeping this running in the long term.

I’ll deal with each in turn.

1. Create the Role Account

The only way to specifically create a role account is by passing the -roleAccount flag to sysadminctl. This isn’t really an API — I mean, it doesn’t even have a man page )-: — but it’s the best we’ve got.

Another option is Identity Services, both the CBIdentity class within the Collaboration framework and the CSIdentity type within the OSServices framework. These let you create hidden users, and the doc comments for the underlying flag, kCSIdentityFlagHidden, make it pretty clear that hidden users are intended to be used for system services. Specifically, in <OSServices/CSIdentity.h> you’ll find this:

  /*
   * This flag causes the identity to be "hidden," that is, excluded
   * from most user-visible identity lists. Hidden identities include
   * administrative users and groups such as root, www, and mysql.
   * System service access control groups should be created with the
   * hidden flag.
   */
  kCSIdentityFlagHidden         = 1

However, the whole Identity Services concept is pretty much deprecated, either formally or informally.

2. Use the Account

Configuring a launchd daemon to use a role account is trivial: Set the UserName property in the launchd property list, as documented in the launchd.plist man page.

There are a couple of thinsg to watch out for here. First, we generally recommend that you install your launchd daemon using SMAppService, and that requires you to pass it the name of a launchd property list within your app’s bundle. That’s a read-only location, so you must know UserName in advance. And that means that, in the previous step, you have to pick a user name that’s not going to collide with any other product that does this. Usually that means embedding your product or company name into the user name.

Second, role accounts have a tendency to disappear. This might happen, for example, if the user re-installs the OS, or uses Migration Assistant to move from one Mac to the other. A product that uses one has to handle this. Typically that means detecting the problem and offering a way to repair it.

3. Beware the Execution Context

A launchd daemon always runs in the global context, as explained in TN2083 Daemons and Agents. If you customise the UserName property, the daemon ends up running in a mixed context. The user ID no longer matches the user ID associated with the context as a whole, which for the global context is, of course, root.

Running in a mixed execution context is tricky. You’ll find things that work and things that fail, and that list can change over time. For example, I recently learnt that enabling the App Sandbox in such a daemon doesn’t work.

4. The Long Term™

All of this means that role accounts tend to be brittle. You end up relying on a bunch of implementation details. As those can change over time, you have to update your product accordingly. So, it’s debatable whether role accounts are worth the effort on macOS. It might make more sense to run your daemon as root but limit its scope by enabling App Sandbox.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

macOS’s support for role accounts is not particularly strong. There are (at least :-) four parts to this:

  1. Creating the role account.
  2. Using the role account in your launchd daemon.
  3. Handling the role account execution context.
  4. Keeping this running in the long term.

I’ll deal with each in turn.

1. Create the Role Account

The only way to specifically create a role account is by passing the -roleAccount flag to sysadminctl. This isn’t really an API — I mean, it doesn’t even have a man page )-: — but it’s the best we’ve got.

Another option is Identity Services, both the CBIdentity class within the Collaboration framework and the CSIdentity type within the OSServices framework. These let you create hidden users, and the doc comments for the underlying flag, kCSIdentityFlagHidden, make it pretty clear that hidden users are intended to be used for system services. Specifically, in <OSServices/CSIdentity.h> you’ll find this:

  /*
   * This flag causes the identity to be "hidden," that is, excluded
   * from most user-visible identity lists. Hidden identities include
   * administrative users and groups such as root, www, and mysql.
   * System service access control groups should be created with the
   * hidden flag.
   */
  kCSIdentityFlagHidden         = 1

However, the whole Identity Services concept is pretty much deprecated, either formally or informally.

2. Use the Account

Configuring a launchd daemon to use a role account is trivial: Set the UserName property in the launchd property list, as documented in the launchd.plist man page.

There are a couple of thinsg to watch out for here. First, we generally recommend that you install your launchd daemon using SMAppService, and that requires you to pass it the name of a launchd property list within your app’s bundle. That’s a read-only location, so you must know UserName in advance. And that means that, in the previous step, you have to pick a user name that’s not going to collide with any other product that does this. Usually that means embedding your product or company name into the user name.

Second, role accounts have a tendency to disappear. This might happen, for example, if the user re-installs the OS, or uses Migration Assistant to move from one Mac to the other. A product that uses one has to handle this. Typically that means detecting the problem and offering a way to repair it.

3. Beware the Execution Context

A launchd daemon always runs in the global context, as explained in TN2083 Daemons and Agents. If you customise the UserName property, the daemon ends up running in a mixed context. The user ID no longer matches the user ID associated with the context as a whole, which for the global context is, of course, root.

Running in a mixed execution context is tricky. You’ll find things that work and things that fail, and that list can change over time. For example, I recently learnt that enabling the App Sandbox in such a daemon doesn’t work.

4. The Long Term™

All of this means that role accounts tend to be brittle. You end up relying on a bunch of implementation details. As those can change over time, you have to update your product accordingly. So, it’s debatable whether role accounts are worth the effort on macOS. It might make more sense to run your daemon as root but limit its scope by enabling App Sandbox.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Hi Quinn,

Thank you for the detailed response. I’m evaluating the root-plus-App-Sandbox alternative you mentioned for separately running LaunchDaemon components on macOS Golden Gate 27.2.

I noticed that Apple’s “Signing a daemon with a restricted entitlement” documentation says App Sandbox is not appropriate for daemons, while your related discussion describes a sandboxed-daemon use case. Could you clarify:

  1. Supported configuration: For which daemon types, signing configurations and entitlements is App Sandbox supported or inappropriate? What supported signing, entitlement and launch configuration applies to the root-plus-App-Sandbox approach?
  2. Security isolation: Can separately running components be meaningfully isolated from one another with this approach, or is confinement primarily between each component and the wider system? What guarantees apply to credential custody, filesystem access, interprocess communication (IPC), and protection of a separate controller and authoritative data store?
  3. Startup behavior: What behavior is supported before FileVault unlock, after unlock but before user login, and after login?

For these points, which properties are documented guarantees, and which would need qualification on the target macOS version and hardware?

For context, I’m referring to your response here:
https://developer.apple.com/forums/thread/856568?answerId=915636022

The related discussion:
https://developer.apple.com/forums/thread/848726

And Apple’s daemon-signing documentation:
https://developer.apple.com/documentation/xcode/signing-a-daemon-with-a-restricted-entitlement

Thank you for your help.

I noticed that Apple’s Signing a daemon with a restricted entitlement documentation says App Sandbox is not appropriate for daemons

Things have changed a little since I wrote that [1]:

  • At the time, system extension were brand new and I didn’t understand the implications of packaging a Network Extension provider in a system extension, namely, that you end up with a system extension, which is essentially a daemon, that’s sandboxed.
  • That in turn revealed a number of problems, which we’ve fixed over the years. For example, the System keychain issue discussed on this thread.
  • Starting in macOS 14.2 we require that any daemon installed using SMAppService by a sandboxed app must also be sandboxed.

Given all of the above, I’m more tolerant of sandboxed daemons than I was previously. In contrast, my experience is that mixed execution contexts have become less reliable over the years. And hence the suggestion above.

If you file a bug against Signing a daemon with a restricted entitlement documentation and reply here with the bug number, I’ll get that updated.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] If you’re curious, that text originated in Packaging a Daemon with a Provisioning Profile, back in Feb 2020.

Hi Quinn, I tested a minimal sandboxed macOS app registering an independently sandboxed LaunchAgent through SMAppService on macOS 27.2. Both binaries are signed with an Apple Development identity, and the agent plist is inside the containing app’s Contents/Library/LaunchAgents directory. The agent is wrapped in an app bundle and BundleProgram points to its executable. Neither component uses an App Group or other entitlement beyond App Sandbox.

Before registration, status returned NotFound. The registration call returned SMAppServiceErrorDomain code 22, and the sandbox log for the registering process reported deny(1) job-creation, with smd as the checker. A subsequent unregister returned an error, and no matching launchd job or worker process was observed. The controller’s executable was invoked from Terminal.

Is there a documented signing, packaging, entitlement or launch requirement we may be missing for a sandboxed app to register a sandboxed agent? Does this denial suggest a particular condition we should investigate? I can provide a minimal reproducer and appropriately redacted logs if useful. Thank you.

A while back I created a test project for this. I just built and ran it on macOS 27.2 and it continues to work as expected. However, it was using an agent that was sandboxed but not bundled, which isn’t what I recommend these days [1]. So, I spent some time updating it to use a bundled agent. And this version also works as expected, both on macOS 26.7.2 and macOS 27.2.

I’ve included some details at the end of this post. Hopefully this’ll give you some ideas as to where to start.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] I like having the agent bundled because I want to use an iOS-style app group ID for my XPC, and that means having a provisioning profile. See App Groups: macOS vs iOS: Working Towards Harmony for more on that last bit.


% codesign -d --ent - /Applications/SandboxedAgentApp.app 
…
[Dict]
	[Key] com.apple.application-identifier
	[Value]
		[String] SKMME9E2Y8.com.example.apple-samplecode.SandboxedAgent
	[Key] com.apple.developer.team-identifier
	[Value]
		[String] SKMME9E2Y8
	[Key] com.apple.security.app-sandbox
	[Value]
		[Bool] true
	[Key] com.apple.security.application-groups
	[Value]
		[Array]
			[String] group.eskimo1.SandboxedAgent
% codesign -d --ent - /Applications/SandboxedAgentApp.app/Contents/MacOS/SandboxedAgent.app 
…
[Dict]
	[Key] com.apple.application-identifier
	[Value]
		[String] SKMME9E2Y8.com.example.apple-samplecode.SandboxedAgent.agent
	[Key] com.apple.developer.team-identifier
	[Value]
		[String] SKMME9E2Y8
	[Key] com.apple.security.app-sandbox
	[Value]
		[Bool] true
	[Key] com.apple.security.application-groups
	[Value]
		[Array]
			[String] group.eskimo1.SandboxedAgent
% plutil -p /Applications/SandboxedAgentApp.app/Contents/Library/LaunchAgents/com.example.apple-samplecode.SandboxedAgent.agent.plist
{
  "BundleProgram" => "Contents/MacOS/SandboxedAgent.app/Contents/MacOS/SandboxedAgent"
  "Label" => "com.example.apple-samplecode.SandboxedAgent.agent"
  "MachServices" => {
    "group.eskimo1.SandboxedAgent.agent" => true
  }
}

Hi Quinn,

Thank you for testing this and sharing the working configuration.

I made a fresh status-only build with new identifiers and launched the containing app normally once, rather than invoking its executable from Terminal. Its UI reported NotFound. This build contains no registration or unregistration calls, so this was not another registration attempt.

Both components are signed and sandboxed, with no provisioning profiles or App Group entitlements. The bundled helper is under Contents/Library/Helpers; the LaunchAgent plist uses BundleProgram, RunAtLoad and stdout/stderr paths. Your example instead places the helper under Contents/MacOS and includes App Group entitlements and MachServices.

Before attempting registration again, could you clarify:

  1. Does NotFound before registration distinguish a packaging/signing problem from an otherwise valid, unregistered service?
  2. What is the minimal supported configuration for registering a sandboxed bundled agent without XPC or an App Group? Which differences above would you check first?

The status-only observation exceeded my 15-second test budget, and I could not read its saved evidence file, so I cannot draw a reliable timing conclusion.

Thank you,
Carl

I’m not sure what you mean by NotFound. Are you referring to the System Extension .extensionNotFound error code? If your UI isn’t registering or unregistering anything, how does it get that error? From a properties request (propertiesRequest(forExtensionWithIdentifier:queue:))?

with no provisioning profiles or App Group entitlements.

That is not in and of itself a problem:

  • In my setup the app group entitlement is only needed because I’m using XPC to communicate between my sandboxed app and my sandboxed agent.
  • A profile is only necessary if the program uses restricted entitlements. If you don’t use the app group entitlement, then it’s unlikely that you’re using any other [1] restricted entitlements and thus you don’t need a profile.

the bundled helper is under Contents/Library/Helpers;

That shouldn’t be problem as long as you update the BundleProgram property in the agent’s Info.plist to match.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] Technically app groups isn’t a restricted entitlement, but it’s better if you treat it like one.

Hi Quinn,

Thanks for clarifying. By NotFound I meant SMAppServiceStatusNotFound, read from [SMAppService agentServiceWithPlistName:PLIST_NAME].status. The containing app was opened normally and only read that property. It didn’t call register or unregister, and it didn’t use the System Extensions framework. I couldn’t read the saved evidence file or verify the process exit, so the UI status is the only result I can report for that run.

For a correctly packaged but never-registered bundled LaunchAgent, would you expect NotRegistered rather than NotFound? Also, just to make sure I’m checking the right file: did you mean the BundleProgram key in the launchd plist under Contents/Library/LaunchAgents, or is there a separate requirement in the helper’s Info.plist?

Thank you,
Carl

For a correctly packaged but never-registered bundled LaunchAgent, would you expect NotRegistered rather than NotFound?

You would expect that, but you'd be wrong. It will return "NotFound" until you succeed at running it for the first time. I spend a lot of time on this particular point of confusion the first time I tried it.

This is one of those cases where you need VMs - at least 2 VMs. Keep one as a base, then duplicate it to test something and delete. Any of these kinds of system integrations will fundamentally change the operating system. There's no way on your developer box to get back to that original state where your integration hasn't happened yet. Technically that's true for any app. It's just that certain artifacts are more delicate than others. This architecture is particularly delicate.

it didn’t use the System Extensions framework

Indeed. Sorry about that. I’m mixing up my frameworks )-:

Regarding Service Management, consider this code:

log.log("will check status on agent")
let service = SMAppService.agent(plistName: "com.example.apple-samplecode.SandboxedAgent.agent.plist")
self.log.log("did check status, \(service.status.rawValue)")

If you run this on a Mac that’s never seen your app before and the status comes back with the .notFound value (aka 3), then I don’t think there’s any deep significance to that. The .notFound value basically means that the system has never seen your SMAppService job before.

did you mean the BundleProgram key in the launchd plist under Contents/Library/LaunchAgents

Yes. In my example that’s Contents/Library/LaunchAgents/com.example.apple-samplecode.SandboxedAgent.agent.plist, and the shell transcript in my earlier post show how I’ve set up up BundleProgram.

The one thing I want to call out here is that the plistName parameter in the code above matches the full name of the file in Contents/Library/LaunchAgents. I regularly see folks omit the .plist extension, and then get very confused.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"