trilemma-dev/authorized

Defining Custom Rights

macOS's authorization system is built around the concept of rights. The Policy Database contains definitions for all of the rights on the system and your application can add its own.

If an application defines its own rights it can then use these to self-restrict functionality. For details on why you might want to do see, consider reading Apple's Technical Note TN2095: Authorization for Everyone although keep in mind the code samples shown are not applicable if you are using this Swift implementation.

To define a custom right:

let myCustomRight = AuthorizationRight(name: "com.example.MyApp.special-action")
let description = "MyApp would like to perform a special action."
let rules: Set<AuthorizationRightRule> = [CannedAuthorizationRightRules.authenticateAsAdmin]
try myCustomRight.createOrUpdateDefinition(rules: rules, descriptionKey: description)

The above example creates a right called "com.example.MyApp.special-action" which requires that the user authenticate as an admin. How exactly the user does so is up to macOS; your application does not concern itself with this. (At the time of this documentation being written this means the user needing to type in a password, but in the future Apple could for example update their implementation of the authenticateAsAdmin rule to use Touch ID.) When the user is asked to authenticate they will see the message "MyApp would like to perform a special action."

There are several optional parameters not used in this example, see documentation for details.

If you need to create a rule which is not solely composed of already existing rules, you must create an authorization plug-in, which is not covered by this framework. See Using Authorization Plug-ins for more information.

Authorization

In some more advanced circumstances you may to want directly interact with macOS's Security Server via the Authorization class.

If you only need to check if a user can perform an operation, use Authorization.checkRights(_:environment:options:) which does not involve creating an Authorization instance.

Otherwise you'll typically want to initialize an instance via Authorization.init() and then subsequently request rights with Authorization.requestRights(_:environment:options:).

Authorization conforms to Codable and so can be serialized and deserialized for convenient transference between processes.

Ultimately Authorization is a wrapper around AuthorizationRef and so if needed this underlying reference can be accessed via Authorization.authorizationRef. However, please note the lifetime of this reference is bound to its containing Authorization instance.

Sandboxing

Most of this framework is not available to sandboxed processes because of privilege escalation. The exception to this is reading or existence checking a right definition in the Policy Database.

Package Metadata

Repository: trilemma-dev/authorized

Default branch: main

README: README.md