https://github.com/electron/electron-notarize
Notarize your macOS Electron Apps
https://github.com/electron/electron-notarize
Last synced: 6 months ago
JSON representation
Notarize your macOS Electron Apps
- Host: GitHub
- URL: https://github.com/electron/electron-notarize
- Owner: electron
- License: mit
- Created: 2018-10-22T16:42:16.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-10-26T14:03:15.000Z (7 months ago)
- Last Synced: 2024-10-29T15:26:28.487Z (7 months ago)
- Language: TypeScript
- Size: 397 KB
- Stars: 135
- Watchers: 5
- Forks: 32
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
Electron Notarize
-----------
> Notarize your Electron apps seamlessly for macOS
[](https://github.com/electron/notarize/actions/workflows/test.yml)
[](https://npm.im/@electron/notarize)
## Installation
```bash
npm install @electron/notarize --save-dev
```
## What is app "notarization"?
From Apple's docs in XCode:
> A notarized app is a macOS app that was uploaded to Apple for processing before it was distributed.
> When you export a notarized app from Xcode, it code signs the app with a Developer ID certificate
> and staples a ticket from Apple to the app. The ticket confirms that you previously uploaded the app to Apple.
> On macOS 10.14 and later, the user can launch notarized apps when Gatekeeper is enabled.
> When the user first launches a notarized app, Gatekeeper looks for the app’s ticket online.
> If the user is offline, Gatekeeper looks for the ticket that was stapled to the app.
As macOS 10.15 (Catalina), Apple has made notarization a hard requirement for all applications
distributed outside of the Mac App Store. App Store applications do not need to be notarized.
## Prerequisites
For notarization, you need the following things:
1. Xcode 13 or later installed on your Mac.
1. An [Apple Developer](https://developer.apple.com/) account.
1. [An app-specific password for your ADC account’s Apple ID](https://support.apple.com/HT204397).
1. Your app may need to be signed with `hardenedRuntime: true` option, with the `com.apple.security.cs.allow-jit` entitlement.
> [!NOTE]
> If you are using Electron 11 or below, you must add the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement too.
> When using version 12+, this entitlement should not be applied as it increases your app's attack surface.
## API
`@electron/notarize` exposes a single `notarize` function that accepts the following parameters:
* `appPath` — the absolute path to your codesigned and packaged Electron application.
* `notarytoolPath` - String (optional) - Path to a custom notarytool binary ([more details](#custom-notarytool))
* additional options required for authenticating your Apple ID (see below)
The method returns a void Promise once app notarization is complete. Please note that notarization may take
many minutes.
If the notarization process is unusually log for your application, see Apple Developer's docs to
[Avoid long notarization response times and size limits](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow#3561440).
### Usage with app-specific password
You can generate an [app-specific password](https://support.apple.com/en-us/102654) for your Apple ID
to notarize your Electron applications.
This method also requires you to specify the [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/)
of the Developer Team you want to notarize under. An Apple ID may be part of multiple Teams.
```javascript
import { notarize } from '@electron/notarize';
await notarize({
appPath,
appleId, // Login name of your Apple Developer account
appleIdPassword, // App-specific password
teamId, // Team ID for your developer team
});
```
> [!IMPORTANT]
> **Never hard code your app-specific password into your packaging scripts.** Use an environment
> variable at a minimum.
### Usage with App Store Connect API key
Alternatively, you can also authenticate via JSON Web Token (JWT) with App Store Connect.
You can obtain an API key from [App Store Connect](https://appstoreconnect.apple.com/access/integrations/api).
Create a **Team Key** (not an _Individual Key_) with **App Manager** access.
Note down the Issuer ID (UUID format) and Key ID (10-character alphanumeric string),
and download the `.p8` API key file (`AuthKey_.p8`).
For security purposes, the private key can only be downloaded once.
Provide the absolute path to your API key as the `appleApiKey` argument.
```javascript
import { notarize } from '@electron/notarize';
await notarize({
appPath,
appleApiKey, // Absolute path to API key (e.g. `/path/to/AuthKey_X0X0X0X0X0.p8`)
appleApiIssuer, // Issuer ID (e.g. `d5631714-a680-4b4b-8156-b4ed624c0845`)
});
```
### Usage with Keychain credentials
As an alternative to passing authentication options, you can also store your authentication
credentials (for both API key and app-specific password strategies) in the macOS Keychain
via the `xcrun notarytool` command-line utility.
This method has the advantage of validating your notarization credentials before submitting
your application for notarization.
For example:
```sh
# App-specific password strategy
xcrun notarytool store-credentials "my-app-password-profile"
--apple-id ""
--team-id
--password
```
```sh
# App Store Connect API key strategy
xcrun notarytool store-credentials "my-api-key-profile"
--key ""
--key-id
--issuer
```
Successful storage of your credentials will look like this:
```
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 "my-api-key-profile"`
```
After successfully storing your credentials, pass the keychain profile name into
the `keychainProfile` parameter.
```javascript
import { notarize } from '@electron/notarize';
await notarize({
appPath,
keychainProfile,
});
```
### Custom notarytool
You can provide a path to a custom `notarytool`. This module allows this option to enable unique edge cases - but this use case is _explicitly unsupported_.
## Troubleshooting
### Debug logging
[`debug`](https://www.npmjs.com/package/debug) is used to display logs and messages.
Run your notarization scripts with the `DEBUG=electron-notarize*` environment variable to log additional
debug information from this module.
### Validating credentials
When notarizing your application, you may run into issues with validating your notarization
credentials.
```
Error: HTTP status code: 401. Invalid credentials. Username or password is incorrect.
Use the app-specific password generated at appleid.apple.com. Ensure that all authentication arguments are correct.
```
[Storing your credentials in Keychain](#usage-with-keychain-credentials) will validate your credentials before
even GitHub.
### Validating app notarization
To validate that notarization worked, you can use the `stapler` command-line utility:
```sh
stapler validate path/to/notarized.app
```
### Apple documentation
Apple also provides additional debugging documentation on
[Resolving common notarization issues](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/resolving_common_notarization_issues).