Introduction

I didn’t find Apple’s documentation to be completely clear on how to grant an Mac OS X application authorization to run system-level commands. The best solution and only solution I could find was to use the function AuthorizationExecuteWithPrivileges. I wrote two simple Xcode projects, OSXSimpleAuth and OSXSlightlyBetterAuth, for OS X Leopard (10.5) to demonstrate its use, and I hope it will help others get something working quickly and gain a basic understanding, so they can concentrate on adding more robust functionality.

Simple Example

A simple example of how to use AuthorizationExecuteWithPrivileges is as follows:

1. Create a Authorization Reference (AuthorizationCreate)
2. Run your tool with the authorization reference (AuthorizationExecuteWithPrivileges)

For this example, OSXSimpleAuth, I created a Foundation Tool and added the Security framework to it.

// Create authorization reference
AuthorizationRef authorizationRef;
OSStatus status;
status = AuthorizationCreate(NULL, kAuthorizationEmptyEnvironment,
                             kAuthorizationFlagDefaults, &authorizationRef);

// Run the tool using the authorization reference
char *tool = "/sbin/dmesg";
char *args[] = {NULL};
FILE *pipe = NULL;
status = AuthorizationExecuteWithPrivileges(authorizationRef, tool,
                                            kAuthorizationFlagDefaults, args, &pipe);

Slightly Better Example

A slightly better example that uses more options to run AuthorizationExecuteWithPrivileges and has links to some explanations from Apple’s documentation can be found in OSXSlightlyBetterAuth.

// Create authorization reference
OSStatus status;
AuthorizationRef authorizationRef;

// AuthorizationCreate and pass NULL as the initial
// AuthorizationRights set so that the AuthorizationRef gets created
// successfully, and then later call AuthorizationCopyRights to
// determine or extend the allowable rights.
// http://developer.apple.com/qa/qa2001/qa1172.html
status = AuthorizationCreate(NULL, kAuthorizationEmptyEnvironment,
                             kAuthorizationFlagDefaults, &authorizationRef);
if (status != errAuthorizationSuccess)
    NSLog(@"Error Creating Initial Authorization: %d", status);

// kAuthorizationRightExecute == "system.privilege.admin"
AuthorizationItem right = {kAuthorizationRightExecute, 0, NULL, 0};
AuthorizationRights rights = {1, &right};
AuthorizationFlags flags = kAuthorizationFlagDefaults |
                           kAuthorizationFlagInteractionAllowed |
                           kAuthorizationFlagPreAuthorize |
                           kAuthorizationFlagExtendRights;

// Call AuthorizationCopyRights to determine or extend the allowable rights.
status = AuthorizationCopyRights(authorizationRef, &rights, NULL, flags, NULL);
if (status != errAuthorizationSuccess)
    NSLog(@"Copy Rights Unsuccessful: %d", status);

NSLog(@"\n\n** %@ **\n\n", @"This command should work.");
char *tool = "/sbin/dmesg";
char *args[] = {NULL};
FILE *pipe = NULL;

status = AuthorizationExecuteWithPrivileges(authorizationRef, tool,
                                            kAuthorizationFlagDefaults, args, &pipe);
if (status != errAuthorizationSuccess)
    NSLog(@"Error: %d", status);

// The only way to guarantee that a credential acquired when you
// request a right is not shared with other authorization instances is
// to destroy the credential.  To do so, call the AuthorizationFree
// function with the flag kAuthorizationFlagDestroyRights.
// http://developer.apple.com/documentation/Security/Conceptual/authorization_concepts/02authconcepts/chapter_2_section_7.html
status = AuthorizationFree(authorizationRef, kAuthorizationFlagDestroyRights);

Notice the “Right” label in the authorization dialog box screenshot. The AuthorizationItem was set with “system.privilege.admin” via the kAuthorizationRightExecute constant.

Conclusion

Apple recommends only using AuthorizationExecuteWithPrivileges in two cases. One is to create an installer. The other is to repair your helper tool by setting the setuid bit. The helper tool is supposed to encapsulate the root privileged portion of the code. Be aware that I didn’t do this in the examples. Go to the OSXSimpleAuth project page and the OSXSlightlyBetterAuth project page to download the example Xcode projects.