Mastering macOS Notarization: Secure Your Apps for Gatekeeper

What is macOS Notarization and Why is it Essential?

macOS Notarization is an automated Apple service that scans your macOS software for malicious content, identifies code-signing issues, and then issues a 'ticket' to indicate that the software is safe. When users attempt to open your notarized application, macOS Gatekeeper can verify this ticket, assuring users that your software doesn't contain known malware and hasn't been tampered with.

Since macOS Catalina (10.15) and later, notarization is a mandatory requirement for all Mac software distributed outside the Mac App Store. If you distribute an unnotarized application, users will encounter a warning preventing them from launching your app without manually overriding security settings, which is a poor user experience and significantly impacts trust. Understanding and integrating notarization into your development workflow is therefore crucial for successful macOS app distribution.

Prerequisites for Notarization

Before you can notarize your macOS application, ensure you have the following prerequisites in place:

1. Apple Developer Program Membership: Notarization requires an Apple Developer Program membership. This gives you access to the code-signing certificates necessary for the process.
2. Xcode: You'll need Xcode (version 10.1 or later, but using the latest stable version is highly recommended) installed on your development machine. Xcode includes the command-line tools for signing and notarizing.
3. App-Specific Password: While you can use your Apple ID password for notarization, Apple strongly recommends using an app-specific password for enhanced security. You can generate one from your Apple ID account page on appleid.apple.com.
4. Code Signing Identity: Your application must be correctly code-signed with a Developer ID Application certificate. This is different from the Mac App Store Distribution certificate. Ensure your project's build settings in Xcode are configured to use the correct Developer ID identity.
5. Hardened Runtime: Your executable must be built with the Hardened Runtime capability enabled. This is a security measure that protects your app against certain classes of attacks. You enable this in Xcode's Signing & Capabilities tab.

Configuring Your Xcode Project for Notarization

Proper Xcode project configuration is the first step towards successful notarization. Here's what you need to check and enable:

1. Code Signing Identity

Ensure your target's 'Signing & Capabilities' tab uses your 'Developer ID Application' certificate for distribution builds. Xcode usually handles this automatically if you've added your Developer ID account.

2. Hardened Runtime

You must enable Hardened Runtime for your primary executable and any helper executables or bundles. In Xcode, go to your target's 'Signing & Capabilities' tab, click the '+' button, and search for 'Hardened Runtime'. Add it, and ensure it's checked.

3. Entitlements

Sometimes, you might need specific entitlements that Hardened Runtime restricts by default. If your app requires access to cameras, microphones, or certain file system locations, you'll need to explicitly add those entitlements. For example, to allow JIT compilation (if your app uses JavaScriptCore or other JIT engines), you would add com.apple.security.cs.allow-jit.

Here's how you might add an entitlement in your .entitlements file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>
</dict>
</plist>

Note: Use entitlements sparingly and only when absolutely necessary, as they can reduce the security posture of your application. Always refer to Apple's documentation for the most current entitlement keys and their implications.

4. Remove Unnecessary Bundles

Ensure your application bundle doesn't contain debug symbols (.dSYM files) or other development-only content that shouldn't be shipped to users. These can bloat your app and sometimes cause notarization failures.

Step-by-Step Notarization Process (Xcode Archive)

The easiest way to notarize your application is often directly through Xcode's Organizer.

1. Archive Your Application: In Xcode, select Product > Archive. This will build your application for distribution and open the Organizer window.

2. Distribute App: In the Organizer window, select your archived app and click 'Distribute App'.

3. Choose Distribution Method: Select 'Developer ID' as the distribution method, then click 'Next'.

4. Choose Destination: Select 'Notarize' as the destination, then click 'Next'. Ensure 'Upload your app's archive to the Apple notarization service' is selected.

5. Review and Upload: Xcode will prompt you to authenticate with your Apple ID and an app-specific password. Review the summary, then click 'Notarize'. Xcode will then upload your archive to Apple's notarization service.

   It's crucial to use an app-specific password here, not your primary Apple ID password.

6. Monitor Notarization Status: After uploading, you'll see a message indicating that the upload was successful and that Apple is processing your request. You can monitor the status in Xcode's Organizer or using the notarytool command-line utility (see next section).

7. Staple the Ticket: Once notarization is complete (you'll receive an email from Apple), you need to 'staple' the notarization ticket to your application. This embedding allows Gatekeeper to confirm notarization even when offline. Xcode often handles this automatically when you export your notarized app. To export, go back to the Organizer, select the notarized archive, click 'Distribute App' -> 'Developer ID' -> 'Export'. Xcode will then export a notarized and stapled .app or .pkg.

Notarization via Command Line (notarytool)

For automation scripts or when you need more control, notarytool (available with Xcode 13 and later) is the preferred command-line tool. It replaces the older altool.

1. Build Your Application

First, build your application and package it into a .dmg, .pkg, or .zip file. For a simple app, you might zip the .app bundle:

# Ensure your app is built and signed with Developer ID
xcodebuild -project YourApp.xcodeproj -scheme YourAppScheme -configuration Release archive -archivePath "build/YourApp.xcarchive"
xcodebuild -exportArchive -archivePath "build/YourApp.xcarchive" -exportPath "build/export" -exportOptionsPlist "exportOptions.plist"

# Create a .zip of your .app bundle for notarization
# Replace YourApp.app with your actual app name
zip -r "YourApp.zip" "build/export/YourApp.app"

Your exportOptions.plist would look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>developer-id</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
    <key>signingStyle</key>
    <string>automatic</string>
    <key>destination</key>
    <string>notarize</string>
    <key>notarize</key>
    <true/>
    <key>hardenedRuntime</key>
    <true/>
</dict>
</plist>

2. Upload for Notarization

Use notarytool to upload your zipped app for notarization. Replace YOUR_APPLE_ID and YOUR_APP_SPECIFIC_PASSWORD with your credentials:

xrun notarytool submit "YourApp.zip" --apple-id "YOUR_APPLE_ID" --password "YOUR_APP_SPECIFIC_PASSWORD" --team-id "YOUR_TEAM_ID" --wait

• --apple-id: Your Apple ID email.
• --password: Your app-specific password.
• --team-id: Your 10-character Developer Team ID (found in your Apple Developer account).
• --wait: This flag makes the command wait until the notarization process is complete, which is very useful for scripting. Without it, you'd have to poll the status.

3. Staple the Notarization Ticket

Once notarytool reports success, you need to staple the notarization ticket to your original application bundle. This is crucial for offline Gatekeeper verification.

xrun stapler staple "build/export/YourApp.app"

• Replace "build/export/YourApp.app" with the actual path to your .app bundle.

4. Verify Stapling

You can verify that your app is properly stapled and notarized using the spctl command:

spctl -a -v "build/export/YourApp.app"

A successful output will include accepted and source=Notarized Developer ID.

Now your YourApp.app (or .dmg/.pkg if you notarized those) is ready for distribution!

# Example of zipping an app for notarization (replace YourApp.app)
zip -r "YourApp.zip" "YourApp.app"

# Example notarization command (replace placeholders)
xrun notarytool submit "YourApp.zip" --apple-id "developer@example.com" --password "abcd-efgh-ijkl-mnop" --team-id "A1B2C3D4E5" --wait

# Example of stapling the notarization ticket
xrun stapler staple "YourApp.app"

# Example of verifying notarization
spctl -a -v "YourApp.app"

Troubleshooting Common Notarization Issues

Notarization can sometimes be finicky. Here are common issues and their solutions:

• Invalid Signature Issues: This is usually due to incorrect code signing. Ensure all embedded executables, frameworks, and bundles are signed with your Developer ID certificate and that the Hardened Runtime is enabled globally for all executables. Use codesign --verify -vvv YourApp.app and spctl -a -vvv YourApp.app.
• Missing Hardened Runtime: Your notarization submission will fail if Hardened Runtime isn't enabled for all executables. Double-check your Xcode build settings and .entitlements.
• Network Issues: Notarization requires an active internet connection to communicate with Apple's servers. Proxy settings or firewalls can sometimes interfere.
• App-Specific Password Problems: Ensure you're using a correct app-specific password, not your primary Apple ID password. Revoke and generate a new one if unsure.
• Conflicting Entitlements: If you've added entitlements, ensure they are correctly formatted and genuinely required. Misconfigured entitlements can cause validation failures.
• Older macOS/Xcode Versions: Always use the latest stable Xcode version for notarization. Apple may introduce new requirements or update their services that older versions don't support.
• Monitoring Submission Logs: If notarization fails, Apple sends an email with a log file URL. Download and analyze this log carefully; it often contains specific reasons for rejection.