Notarize with the notarytool

Notarization is a security feature for macOS apps outside the Mac App Store, command line tools, kexts, and so on. The developer registers the developed programs to the Apple Notary Service. When you launch the program, macOS checks it was registered to the Apple Notary Service. If the program is not registered, macOS blocks its launch.

For the details about the notarization, see the following article.

There are two methods to notarize: Xcode and notarytool. You can notarize with GUI by using Xcode. It is easy to understand, but you must operate by hand, and it is hard to operate from the script and CI/CD.

notarytool is a command-line utility. You can execute it from the Terminal, CI/CD, and scripts. Therefore, it is useful for automation.

altool is also a command-line program. However, it had been deprecated. You must use notarytool, Xcode 14, or later since November 11, 2023.

This article explains how to notarize with the notarytool.

Outline

You need the following preliminaries to notarize with the notarytool.

1. Look up your team ID.
2. Set up the two-factor authentication of your Apple ID.
3. Store your credentials in your keychain.

You need to store your credentials on the machine where the notarytool runs. Follow the steps below to notarize.

1. Activate the Hardened Runtime or the sandbox.
2. Sign your program with the Developer ID Application Certificate.
3. Upload with the notarytool.
4. Staple with the notarytool.

Look up your team ID

The notarytool creates the profile per the credential and stores it into the keychain. Create the profile for each developer team. If you work for outsourcing, your developer account might belong to one or more developer teams. Then, the developer profile should be the same count.

You need to specify the team ID on creating the profile, so look up your team ID. You can find your team ID on the account page on the Apple Developer Site.

1. Sign in to the account page on the Apple Developer Site.
2. Select the developer team from the links at the top right of the page.
3. Click the “Membership details” link.
4. You can find your team ID in the “Team ID” row.

Generate the app password for the two-factor authentication

You need to enable the two-factor authentication of the Apple ID for the developer account. The notarytool needs the app password to authorize the two-factor authentication-enabled account. For the details about how to generate the app password of the Apple ID, see the following article.

Add the profile to the keychain

Add the profile that stores the credentials for notarytool. Execute the following command in the Terminal.

xcrun notarytool store-credentials "AC_PASSWORD" --apple-id "[email protected]" --team-id TEAMID --password examplepassword

The AC_PASSWORD is a profile name. You can enter the name you like. You specify the profile which notarytool uses, so you should set a name that is easy to understand.

The [email protected] is an Apple ID of the developer account, the TEAMID is a developer team ID, and the examplepassword is an app-specific password.

If the notarytool stores the credential successfully, the following message will appear.

This process stores your credentials securely in the keychain. You reference these credentials later using a profile name.

Validating your credentials...
Success. Credentials validated.
Credentials saved to keychain.
To use them, specify `--keychain-profile "AC_PASSWORD"`

Confirm in the Keychain Access

The profile is named com.apple.gke.notary.tool in Keychain Access. The profile account is named com.apple.gke.notary.tool.saved-creds.AC_PASSWORD. The suffix is a profile name so that you can distinguish them from each other.

The Build Settings of the Notarized Apps

You must sandbox or activate the Hardened Runtime to notarize the apps. The system assigns the app’s home directory to each sandboxed app, and the app can’t access the other app’s home directory and the system’s essential directories.

If you can implement all of the app’s functions in the sandboxed environment, you should sandbox the app. However, suppose you need to implement a function that can’t be run in the sandboxed environment. In that case, you can activate the Hardened Runtime.

The Hardened Runtime protects the runtime integrity of your software by preventing exploits. It blocks the unauthorized alternation of the running program. The Hardened Runtime doesn’t affect almost all functions, but JIT (Just In Time Compiler). You can activate the blocked functions, such as JIT, by the entitlement. However, you should activate them when you don’t have other methods, and the function is required.

For the details about the build settings, see the following article.

Create the Disk Image file

The disk image file (in UDIF format) is the best format for uploading. You can create it with the Disk Utility.

The installer package (pkg) should be a flat package format. You can’t use the mpkg format.

For the details about how to create the installer, see the following article.

Upload

Execute the following command to upload to the Apple Notary Service.

xcrun notarytool submit MyApp.dmg --keychain-profile "AC_PASSWORD" --wait

With the --wait option, the notarytool waits until receiving the result. It takes a long time, 20 minutes or more. It depends on the program size.

If the notarization is successful, the notarytool displays Accepted.

Staple

The notarytool embeds the notarized ticket into the deployed file. This function is called the “Staple”. Run the following command to staple.

xcrun stapler staple "MyApp.dmg"

Summary

As this article demonstrates, notarization with notarytool is straightforward. Only run the command.

The notarytool has the --wait option, which is useful when you call it from the automated script.

I recommend you to migrate to the notarytool as soon as possible.