Windows Code Signing

Complete guide to signing Windows applications with electron-builder using standard certificates, EV certificates, or Azure Trusted Signing

Windows code signing is fully supported in electron-builder. If configuration values are provided correctly, signing is executed automatically during the build process.

Windows applications are dual code-signed using both SHA1 and SHA256 hashing algorithms for maximum compatibility.

Certificate Types

There are two types of Windows code signing certificates:

Standard Code Signing Certificate

• Works with auto-update functionality
• More affordable option
• Shows a warning during installation until trust is established
• The warning disappears once enough users have installed your application
• Can be exported for use on CI servers
• Best for: Most applications, CI/CD workflows

EV (Extended Validation) Code Signing Certificate

• Works with auto-update functionality
• Higher trust level - works immediately without warnings
• More expensive than standard certificates
• Bound to a physical USB dongle (hardware token)
• Cannot be exported for CI builds
• Requires win.certificateSubjectName configuration
• Best for: Enterprise applications, when immediate trust is critical

Prerequisites

If you are using Windows 7, ensure that PowerShell is updated to version 3.0.

Standard Certificate Signing

For standard code signing certificates that can be exported:

1. Obtain your certificate

   Purchase a code signing certificate from a trusted Certificate Authority:

   • DigiCert
   • Sectigo (formerly Comodo)
   • SSL.com
   • GlobalSign

   Export your certificate as a .pfx or .p12 file with a strong password.

2. Set environment variables

   Configure the following environment variables:

   # Certificate file path or base64-encoded content
   CSC_LINK=/path/to/certificate.pfx
   
   # Certificate password
   CSC_KEY_PASSWORD=your-certificate-password
   

   For CI/CD, encode your certificate to base64:

   # Windows (PowerShell)
   [Convert]::ToBase64String([IO.File]::ReadAllBytes("certificate.pfx")) | Out-File -Encoding ASCII encoded.txt
   
   # macOS/Linux
   base64 -i certificate.pfx -o encoded.txt
   

   Then set CSC_LINK to the base64 string.

3. Build your application

   Run your build command as usual:

   npm run build
   # or
   electron-builder --win
   

   electron-builder will automatically sign your application during the build process.

If building Windows apps on macOS/Linux and using different credentials, set WIN_CSC_LINK and WIN_CSC_KEY_PASSWORD instead of the standard CSC_* variables.

EV Certificate Signing

For Extended Validation certificates with hardware tokens:

1. Connect the hardware token

   Ensure your EV certificate’s USB hardware token is connected to the build machine.

2. Configure certificateSubjectName

   In your electron-builder configuration, specify the certificate subject name:

   {
     "win": {
       "certificateSubjectName": "Your Company Name, Inc."
     }
   }
   

   The subject name must match exactly what’s in your certificate. To find it:

   1. Open Certificate Manager (certmgr.msc)
   2. Navigate to Personal → Certificates
   3. Double-click your certificate
   4. Use the “Issued to” name exactly as shown
3. Build on the token machine

   Run your build on the machine with the hardware token connected:

   electron-builder --win
   

EV certificates cannot be used on CI servers (AppVeyor, GitHub Actions, etc.) because they require the physical hardware token. Consider using standard certificates for CI builds.

Azure Trusted Signing (Beta)

Microsoft offers a cloud-based code signing service called Azure Trusted Signing, which is an excellent option for CI/CD workflows.

Setup Overview

1. Create Azure Trusted Signing Account

   Follow Microsoft’s quickstart guide to set up a Trusted Signing Account.

2. Create App Registration

   Set up an App registration in Azure:

   1. Create the App registration
   2. Create a “Secret” for it (save the secret value)
   3. Assign the role “Trusted Signing Certificate Profile Signer” to the App registration

   The App registration is considered a “service principal” - you’ll need to search for its name to find it in the role assignment panel.

3. Configure electron-builder

   Add Azure Trusted Signing configuration to your electron-builder config:

   {
     "win": {
       "azureSignOptions": {
         "publisherName": "CN=Your Company Name",
         "endpoint": "https://your-endpoint.codesigning.azure.net",
         "certificateProfileName": "your-profile-name",
         "codeSigningAccountName": "your-signing-account-name"
       }
     }
   }
   

   Configuration properties:

   Property	Description
   publisherName	Must match exactly the CommonName (CN) property of your certificate
   endpoint	The endpoint you selected when creating your certificate
   certificateProfileName	The name of the certificate profile in your Trusted Signing Account
   codeSigningAccountName	The name of the Trusted Signing Account (NOT the app registration name)

4. Set environment variables

   Configure authentication environment variables (for service principal with secret):

   # Azure AD Tenant ID (from Entra ID portal)
   AZURE_TENANT_ID=your-tenant-id
   
   # Application (Client) ID from your App registration
   AZURE_CLIENT_ID=your-client-id
   
   # Secret value from your App registration (not the secret ID)
   AZURE_CLIENT_SECRET=your-client-secret
   

   These environment variables are read directly by the Invoke-TrustedSigning PowerShell module.

   For other authentication methods, see Azure.Identity EnvironmentCredential documentation.

5. Build your application

   Run your build as usual:

   electron-builder --win
   

   electron-builder will use Azure Trusted Signing automatically.

If both azureSignOptions and signtoolOptions are configured, azureSignOptions takes precedence and signtoolOptions will be ignored.

Code Signing on Unix Systems

You can sign Windows applications from macOS or Linux:

1. Use standard certificate

   EV certificates (hardware tokens) cannot be used on Unix systems. Use a standard exportable certificate instead.

2. Set Windows-specific variables

   WIN_CSC_LINK=/path/to/windows-certificate.pfx
   WIN_CSC_KEY_PASSWORD=your-password
   
3. Build for Windows

   electron-builder --win
   

For detailed instructions on signing Windows apps from Unix, see the Code Signing Windows Apps on Unix tutorial.

Troubleshooting

Certificate Not Found

If electron-builder cannot find your certificate:

1. Verify the certificate is in the correct keystore
2. Check that CSC_LINK points to the correct file
3. Ensure CSC_KEY_PASSWORD is correct
4. For EV certificates, verify certificateSubjectName matches exactly

Environment Variable Length Limit

Windows cannot handle environment variable values longer than 8192 characters.

If your base64-encoded certificate exceeds this limit:

1. Re-export your certificate
2. Uncheck “Include all certificates in the certification path if possible”
3. The extra certificates in the chain are not necessary

Build Fails with “Couldn’t resolve host name”

This is a transient network error. electron-builder automatically retries signing operations up to 3 times with exponential backoff.

File Being Used by Another Process

This can occur on Windows when:

• Antivirus software is scanning the file
• Multiple build processes are running simultaneously

electron-builder automatically retries the signing operation.

Example Configuration

{
  "win": {
    "target": ["nsis", "portable"],
    "certificateSubjectName": "Your Company, Inc.",
    "signingHashAlgorithms": ["sha1", "sha256"],
    "verifyUpdateCodeSignature": true
  }
}

Next Steps

macOS Code Signing

Learn about macOS code signing and notarization

Auto Update

Set up auto-update with signed applications