electron-osx-sign guide

The content in this guide is specific with app bundles built upon Electron and may not comply with other general codesigning tasks (concepts are transferable). An Electron version 1.1.1 or later is assumed; if you are using a legacy version of Electron, please refer to another codesigning guide. This guide is up-to-date with the latest electron-osx-sign.

This guide is tailored to a developmentdistribution build for distribution on the Mac App Storeoutside the Mac App Store. Please package your app bundle with Electron masdarwin build.

Update the fields on the right accordingly if you wish to sign for different purposes; the guide will respond dynamically as you update your settings. As your edits are saved locally, you may come back and pick up from where you left off while setting up your codesigning flow.

Codesigning identitity

You will have to obtain signing identities from Apple after becoming a registered developer. To codesign your app for development build, you should use an identity matching Mac Developer: *.To codesign your app for distribution on the Mac App Store, you should an identity matching 3rd Party Mac Developer Application: *.To codesign your app for distribution outside the Mac App Store, you should an identity matching Developer ID Application: *. Do specify the name of your signing identity if there are multiple in your keychain with similar and ambigious names, or if they are of different naming patterns.

Make sure your signing identity is valid; run security find-identity -p codesigning -v in Terminal to display a list of valid identities installed in the keychain. Install your signing identity in the system default keychain or in another keychain.

Creating codesigning identities is beyond the scope of this guide of the current version; please look for related external sources.

Entitlements file

An entitlements file allow you to enable App Sandbox and other features involving interaction with the system.

As you will distribute your app within the Mac App Store, App Sandbox is required by Apple for security. However, it will remove most capabilities of your app interacting with the system. A default entitlements file with App Sandbox enabled is available on GitHub. If your app does not request specific access to the system, the default entitlements file with App Sandbox should work for you; however, you may modify the file up to your need. After adding the entitlement keys, please save the changed file to your working directory.

It is not required but encouraged to have App Sandbox enabled for distribution outside the Mac App Store; skip to the next section if you are neither enabling App Sandbox nor adding additional entitlement keys to your signing process. An empty entitlements file is available on GitHub; also, a default entitlements file with App Sandbox enabled is available on GitHub.

Provisioning profile

With App Sandbox enabled, Electron 1.1.1 and later requires embedding of provisioning profile for stable performance.

As your app should have App Sandbox enabled, it is required to embed provisionig profile in your app bundle while testing or before shipping. A provisioning profile for development specifies a range of devices on which your app bundle may run.A provisioning profile for distribution on the Mac App Store does not allow local testing. Therefore, if you would like to test your app before shipping, please follow the development guide first.

It is required to embed provisioning profile from having enabled App Sandbox in your entitlements file. A provisioning profile for development build specifies a range of devices on which your app bundle may run.A provisioning profile for distribution outside the Mac App Store allows running on multiple devices.

You may optionally embed provisioning profile. Skip to get your recipe if you would like not to include it. A provisioning profile for development build specifies a range of devices on which your app bundle may run.A provisioning profile for distribution outside the Mac App Store allows running on multiple devices. As App Sandbox is not enabled, your app should function even when no provisioning profile is embedded.

Make sure that your provisioning profile matches your build by inspecting it through running security cms -D -i <path-to-provisioning-profile> in Terminal. A provisioning profile for development build should contain a list of registered devices under ProvisionedDevices.A provisioning profile for distribution on the Mac App Store should not contain ProvisionedDevices nor ProvisionsAllDevices.A provisioning profile for distribution outside the Mac App Store should contain ProvisionsAllDevices.

It is recommended to save your provisioning profiles in your working directory so that electron-osx-sign may automatically pick up the appropriate provisioning profile to embed. The current version does not replace existing provisioning profile in the app bundle; it is therefore encouraged to sign a fresh build every time.

Hardened runtime

The hardened runtime is introduced in macOS 10.14 Mojave and is required for app notarization. More info on notarizating your app is available here. For distribution outside the Mac App Store, it is recommended to enable hardened runtime to later notarize your app.Please note that even with hardened runtime, the app cannot be notarized as it is signed by a development certificate.Please note that even with hardened runtime, the app bundle cannot be notarized as it is signed by a 3rd Party Mac Developer Application: * certificate.

Recipes

Generated below are recipes for codesigning your app based on your choices made above. It may be easier to test codesigning with electron-osx-sign before integrating in a more streamlined workflow.

electron-osx-sign

CLI

electron-osx-sign <path-to-app> --platform= --type= --identity= --keychain= --entitlements= --provisioning-profile= --hardened-runtime

API opts

{ app: <path-to-app>
, platform:
, type:
, identity:
, keychain:
, entitlements:
, "provisioning-profile":
, "hardened-runtime": true }

electron-packager

Setting up app packaging with electron-packager is beyond the scope of this guide; please refer to its manual or external sources. Also note that only the bare minimum is produced below.

CLI

electron-packager <path-to-source> --platform= --osx-sign.type= --osx-sign.identity= --osx-sign.keychain= --osx-sign.entitlements= --osx-sign.provisioning-profile= --osx-sign.hardened-runtime

API opts

{ dir: <path-to-source>
, platform: , "osx-sign":
{ type:
, identity:
, keychain:
, entitlements:
, "provisioning-profile":
, "hardened-runtime": true } }

electron-builder

// TODO