You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> 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.
19
+
> A notarized app is a macOS app that was uploaded to Apple for processing before it was distributed.
20
+
> When you export a notarized app from Xcode, it code signs the app with a Developer ID certificate
21
+
> and staples a ticket from Apple to the app. The ticket confirms that you previously uploaded the app to Apple.
24
22
25
-
> 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.
23
+
> On macOS 10.14 and later, the user can launch notarized apps when Gatekeeper is enabled.
24
+
> When the user first launches a notarized app, Gatekeeper looks for the app’s ticket online.
25
+
> If the user is offline, Gatekeeper looks for the ticket that was stapled to the app.
26
26
27
-
Apple has made this a hard requirement as of 10.15 (Catalina).
27
+
As macOS 10.15 (Catalina), Apple has made notarization a hard requirement for all applications
28
+
distributed outside of the Mac App Store. App Store applications do not need to be notarized.
28
29
29
30
## Prerequisites
30
31
31
32
For notarization, you need the following things:
32
33
33
34
1. Xcode 13 or later installed on your Mac.
34
-
2. An [Apple Developer](https://developer.apple.com/) account.
35
-
3.[An app-specific password for your ADC account’s Apple ID](https://support.apple.com/HT204397).
36
-
4. Your app may need to be signed with `hardened-runtime`, including the following entitlement:
37
-
1.`com.apple.security.cs.allow-jit`
35
+
1. An [Apple Developer](https://developer.apple.com/) account.
36
+
1.[An app-specific password for your ADC account’s Apple ID](https://support.apple.com/HT204397).
37
+
1. Your app may need to be signed with `hardenedRuntime: true` option, with the `com.apple.security.cs.allow-jit` entitlement.
38
38
39
-
If you are using Electron 11 or below, you must add the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement too.
40
-
When using version 12+, this entitlement should not be applied as it increases your app's attack surface.
39
+
> [!NOTE]
40
+
> If you are using Electron 11 or below, you must add the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement too.
41
+
> When using version 12+, this entitlement should not be applied as it increases your app's attack surface.
41
42
42
43
## API
43
44
44
-
### Method: `notarize(opts): Promise<void>`
45
-
46
-
*`options` Object
47
-
*`tool` String - The notarization tool to use, default is `notarytool`. Previously, the value `legacy` used `altool`, which [**stopped working** on November 1st 2023](https://developer.apple.com/news/?id=y5mjxqmn).
48
-
*`appPath` String - The absolute path to your `.app` file
49
-
* There are three authentication methods available:
50
-
* user name with password:
51
-
*`appleId` String - The username of your Apple Developer account
52
-
*`appleIdPassword` String - The [app-specific password](https://support.apple.com/HT204397) (not your Apple ID password).
53
-
*`teamId` String - The [team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/) you want to notarize under.
54
-
* ... or apiKey with apiIssuer:
55
-
*`appleApiKey` String - Absolute path to the `.p8` file containing the key. Required for JWT authentication. See Note on JWT authentication below.
56
-
*`appleApiKeyId` String - App Store Connect API key ID, for example, `T9GPZ92M7K`. Required for JWT authentication. See Note on JWT authentication below.
57
-
*`appleApiIssuer` String - Your App Store Connect API key issuer, for example, `c055ca8c-e5a8-4836-b61d-aa5794eeb3f4`. Required if `appleApiKey` is specified.
58
-
* ... or keychain with keychainProfile:
59
-
*`keychain` String (optional) - The name of the keychain or path to the keychain you stored notarization credentials in. If omitted, iCloud keychain is used by default.
60
-
*`keychainProfile` String - The name of the profile you provided when storing notarization credentials.
61
-
62
-
## Safety when using `appleIdPassword`
63
-
64
-
1. Never hard code your password into your packaging scripts, use an environment
65
-
variable at a minimum.
66
-
2. It is possible to provide a keychain reference instead of your actual password (assuming that you have already logged into
67
-
the Application Loader from Xcode). For example:
45
+
`@electron/notarize` exposes a single `notarize` function that accepts the following parameters:
46
+
*`appPath` — the absolute path to your codesigned and packaged Electron application.
47
+
* additional options required for authenticating your Apple ID (see below)
48
+
49
+
The method returns a void Promise once app notarization is complete. Please note that notarization may take
50
+
many minutes.
51
+
52
+
If the notarization process is unusually log for your application, see Apple Developer's docs to
53
+
[Avoid long notarization response times and size limits](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow#3561440).
54
+
55
+
### Usage with app-specific password
56
+
57
+
You can generate an [app-specific password](https://support.apple.com/en-us/102654) for your Apple ID
58
+
to notarize your Electron applications.
59
+
60
+
This method also requires you to specify the [Team ID](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id/)
61
+
of the Developer Team you want to notarize under. An Apple ID may be part of multiple Teams.
appleId, // Login name of your Apple Developer account
69
+
appleIdPassword, // App-specific password
70
+
teamId, // Team ID for your developer team
71
+
});
71
72
```
72
73
73
-
Another option is that you can add a new keychain item using either the Keychain Access app or from the command line using the `security` utility:
74
+
> [!IMPORTANT]
75
+
> **Never hard code your app-specific password into your packaging scripts.** Use an environment
76
+
> variable at a minimum.
74
77
75
-
```bash
76
-
security add-generic-password -a "AC_USERNAME" -w <app_specific_password> -s "AC_PASSWORD"
77
-
```
78
-
where `AC_USERNAME` should be replaced with your Apple ID, and then in your code you can use:
78
+
### Usage with App Store Connect API key
79
+
80
+
Alternatively, you can also authenticate via JSON Web Token (JWT) with App Store Connect.
81
+
82
+
You can obtain an API key from [App Store Connect](https://appstoreconnect.apple.com/access/integrations/api).
83
+
Create a **Team Key** (not an _Individual Key_) with **App Manager** access.
84
+
85
+
Note down the Issuer ID (UUID format) and Key ID (10-character alphanumeric string),
86
+
and download the `.p8` API key file (`AuthKey_<appleApiKeyId>.p8`).
87
+
For security purposes, the private key can only be downloaded once.
88
+
89
+
Provide the absolute path to your API key as the `appleApiKey` argument.
79
90
80
91
```javascript
81
-
constpassword=`@keychain:AC_PASSWORD`;
92
+
import { notarize } from'@electron/notarize';
93
+
94
+
awaitnotarize({
95
+
appPath,
96
+
appleApiKey, // Absolute path to API key (e.g. `/path/to/AuthKey_X0X0X0X0X0.p8`)
97
+
appleApiIssuer, // Issuer ID (e.g. `d5631714-a680-4b4b-8156-b4ed624c0845`)
98
+
});
82
99
```
83
100
84
-
##Notes on JWT authentication
101
+
### Usage with Keychain credentials
85
102
86
-
You can obtain an API key from [App Store Connect](https://appstoreconnect.apple.com/access/api). Create a _Team Key_ (not an _Individual Key_) with _App Manager_ access. Note down the Issuer ID and download the `.p8` file. This file is your API key and comes with the name of `AuthKey_<appleApiKeyId>.p8`. Provide the path to this file as the `appleApiKey` argument.
103
+
As an alternative to passing authentication options, you can also store your authentication
104
+
credentials (for both API key and app-specific password strategies) in the macOS Keychain
105
+
via the `xcrun notarytool` command-line utility.
87
106
88
-
## Notes on your teamId
107
+
This method has the advantage of validating your notarization credentials before submitting
108
+
your application for notarization.
89
109
90
-
To get your `teamId` value, go to your [Apple Developer Account](https://developer.apple.com/account), then click on "Membership details", and there you will find your Team ID.
[`debug`](https://www.npmjs.com/package/debug) is used to display logs and messages. You can use `export DEBUG=electron-notarize*` to log additional debug information from this module.
Successful storage of your credentials will look like this:
129
+
130
+
```
131
+
This process stores your credentials securely in the Keychain. You reference these credentials later using a profile name.
132
+
133
+
Validating your credentials...
134
+
Success. Credentials validated.
135
+
Credentials saved to Keychain.
136
+
To use them, specify `--keychain-profile "my-api-key-profile"`
137
+
```
138
+
139
+
After successfully storing your credentials, pass the keychain profile name into
140
+
the `keychainProfile` parameter.
97
141
98
142
```javascript
99
143
import { notarize } from'@electron/notarize';
100
144
101
-
asyncfunctionpackageTask () {
102
-
// Package your app here, and code sign with hardened runtime
103
-
awaitnotarize({
104
-
appPath,
105
-
appleId,
106
-
appleIdPassword,
107
-
teamId,
108
-
});
109
-
}
145
+
awaitnotarize({
146
+
appPath,
147
+
keychainProfile,
148
+
});
149
+
```
150
+
## Troubleshooting
151
+
152
+
### Debug logging
153
+
154
+
[`debug`](https://www.npmjs.com/package/debug) is used to display logs and messages.
155
+
Run your notarization scripts with the `DEBUG=electron-notarize*` environment variable to log additional
156
+
debug information from this module.
157
+
158
+
### Validating credentials
159
+
160
+
When notarizing your application, you may run into issues with validating your notarization
161
+
credentials.
162
+
163
+
```
164
+
Error: HTTP status code: 401. Invalid credentials. Username or password is incorrect.
165
+
Use the app-specific password generated at appleid.apple.com. Ensure that all authentication arguments are correct.
110
166
```
167
+
168
+
[Storing your credentials in Keychain](#usage-with-keychain-credentials) will validate your credentials before
169
+
even GitHub.
170
+
171
+
### Validating app notarization
172
+
173
+
To validate that notarization worked, you can use the `stapler` command-line utility:
174
+
175
+
```sh
176
+
stapler validate path/to/notarized.app
177
+
```
178
+
179
+
### Apple documentation
180
+
181
+
Apple also provides additional debugging documentation on
182
+
[Resolving common notarization issues](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/resolving_common_notarization_issues).
0 commit comments