Guida completa alla firma del pacchetto MSIX

Questa guida illustra come firmare un pacchetto MSIX per ogni fase di sviluppo, dal test locale alla distribuzione di produzione. Per un confronto tra opzioni e costi di firma, vedere Sign an MSIX package overview (Firma di un pacchetto MSIX).

Scegliere un approccio di firma

Sviluppo: Firmare per il testing locale

Per lo sviluppo locale, usare un certificato autofirmato. I pacchetti autofirmati possono essere installati solo nei computer in cui il certificato è attendibile in modo esplicito. Questo è intenzionale e appropriato per i test.

Opzione A: Interfaccia della riga di comando di WinApp (consigliata per i nuovi progetti)

L'interfaccia della riga di comando di WinApp gestisce la generazione e l'accesso dei certificati in un singolo passaggio.

Passaggio 1: Installare l'interfaccia della riga di comando di WinApp

winget install -e --id Microsoft.WinAppCLI --source winget

Passaggio 2: Generare un certificato di sviluppo autofirmato

winapp cert generate --manifest .\appxmanifest.xml --output .\devcert.pfx --install

Il --manifest flag legge il nome dell'autore direttamente dall'oggetto appxmanifest.xml. Il --install flag aggiunge il certificato all'archivio trust del computer locale, in modo da poter installare immediatamente il pacchetto.

Passaggio 3: Firmare il pacchetto

winapp sign MyApp.msix --cert .\devcert.pfx

Opzione B: PowerShell + SignTool (Windows 10 e versioni successive)

Usare questo approccio se non si usa la CLI di WinApp.

Passaggio 1: Creare un certificato autofirmato

Eseguire quanto segue in un prompt di PowerShell con privilegi elevati. Il valore Subject deve corrispondere esattamente al Publisher nel appxmanifest.xml:

New-SelfSignedCertificate -Type Custom -KeyUsage DigitalSignature `
  -Subject "CN=MyPublisher" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}") `
  -FriendlyName "MyApp Dev Cert"

Prendere nota dell'impronta nel risultato — sarà necessario nei passaggi successivi.

Passaggio 2: Esportare il certificato in un file PFX

$password = ConvertTo-SecureString -String "YourPassword" -Force -AsPlainText
Export-PfxCertificate -cert "Cert:\CurrentUser\My\<Thumbprint>" `
  -FilePath .\devcert.pfx -Password $password

Passaggio 3: Considerare attendibile il certificato in locale

Import-PfxCertificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" `
  -FilePath .\devcert.pfx -Password $password

Passaggio 4: Firmare il pacchetto

SignTool sign /fd SHA256 /a /f .\devcert.pfx /p "YourPassword" MyApp.msix

Per l'utilizzo completo di SignTool, vedere Firmare un pacchetto dell'app con SignTool.

Test in corso: distribuire ai tester con un certificato autofirmato

Per installare un pacchetto MSIX autofirmato nel computer di un tester, il certificato deve prima essere considerato attendibile nel computer.

Assegnare ai tester il certificato: Condividere il .pfx file o .cer (solo chiave pubblica) insieme al .msix pacchetto.

I tester eseguono quanto segue in un prompt di PowerShell con privilegi elevati:

# If you shared a .pfx file (testers need the password)
Import-PfxCertificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" `
  -FilePath .\devcert.pfx -Password (ConvertTo-SecureString "YourPassword" -Force -AsPlainText)

# If you shared a .cer file (public key only, no password needed)
Import-Certificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" -FilePath .\devcert.cer

Dopo aver accettato il certificato, i tester possono installare il .msix facendo doppio clic su di esso.

Produzione: firma Azure Artifacts (ex Firma Attendibile)

Applica a: Windows 10 versione 1809 e successive, Windows 11 (tutte le versioni), Windows Server 2016 e versioni successive

Firma degli artefatti di Azure è il nuovo nome per quello che in precedenza era chiamato Firma attendibile. Il servizio è identico, ma solo il nome è stato modificato. È comunque possibile visualizzare "Firma attendibile" in alcuni strumenti (ad esempio l'azione azure/trusted-signing-action GitHub e l'ID pacchetto winget) perché tali riferimenti vengono aggiornati nel corso del tempo.

La firma degli artefatti di Azure è l'opzione consigliata per la firma di produzione MSIX. La reputazione è legata all'identità verificata anziché a un certificato specifico, il che significa che l'identità dell'editore crea reputazione SmartScreen nel tempo quando gli utenti installano le app firmate. Consultare Sign an MSIX package overview (Panoramica sulla firma di un pacchetto MSIX) per informazioni sui requisiti di idoneità e sui costi prima di creare un account.

Prerequisiti

• Un account di firma artefatto con convalida dell'identità completata e un profilo certificato creato. Consultare la guida rapida sulla firma degli artefatti.
• Ruolo firmatario del Profilo Certificato di Firma Affidabile assegnato all'identità utilizzata per la firma.

Passaggio 1: Installare gli strumenti client per la firma degli artefatti

Gli strumenti client di firma artefatto includono il plug-in dlib necessario, una versione compatibile di SignTool e il runtime .NET 8. La sintassi standard di SignTool non funziona con la firma degli artefatti senza questo pacchetto.

winget install -e --id Microsoft.Azure.ArtifactSigningClientTools

Se WinGet non è disponibile (ad esempio in un agente di compilazione Windows Server), eseguire l'installazione tramite PowerShell come amministratore:

$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri "https://download.microsoft.com/download/70ad2c3b-761f-4aa9-a9de-e7405aa2b4c1/ArtifactSigningClientTools.msi" -OutFile .\ArtifactSigningClientTools.msi
Start-Process msiexec.exe -Wait -ArgumentList '/I ArtifactSigningClientTools.msi /quiet'
Remove-Item .\ArtifactSigningClientTools.msi

Passaggio 2: Creare un file JSON di metadati

Creare un file denominato metadata.json con i dettagli dell'account di firma dell'artefatto. L'URI dell'endpoint deve corrispondere all'area di Azure in cui è stato creato l'account (trovarlo nel portale di Azure nell'account di firma artefatto come URIAccount):

{
  "Endpoint": "https://<region>.codesigning.azure.net/",
  "CodeSigningAccountName": "<your-account-name>",
  "CertificateProfileName": "<your-certificate-profile-name>"
}

Per l'elenco completo degli URI di endpoint specifici dell'area, vedere Integrazioni di firma.

Passaggio 3: Eseguire l'autenticazione

Impostare le credenziali di Azure come variabili di ambiente (usare le credenziali di registrazione app per CI/CD):

$env:AZURE_CLIENT_ID     = "<your-client-id>"
$env:AZURE_TENANT_ID     = "<your-tenant-id>"
$env:AZURE_CLIENT_SECRET = "<your-client-secret>"

In alternativa, eseguire az login per la firma locale interattiva.

Passaggio 4: Firmare il pacchetto

Usare il SignTool installato con i Client Tools per la firma degli artefatti. Il /dlib flag punta al plug-in dlib installato nel passaggio precedente:

signtool sign /v /fd SHA256 `
  /tr "https://timestamp.acs.microsoft.com" /td SHA256 `
  /dlib "C:\Program Files (x86)\Microsoft\ArtifactSigningClientTools\bin\Azure.CodeSigning.Dlib.dll" `
  /dmdf .\metadata.json `
  MyApp.msix

CI/CD: GitHub Actions

Usare il valore ufficiale azure/trusted-signing-action:

- name: Sign MSIX with Azure Artifact Signing
  uses: azure/trusted-signing-action@v0
  with:
    azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
    azure-client-secret: ${{ secrets.AZURE_CLIENT_SECRET }}
    endpoint: ${{ secrets.AZURE_TRUSTED_SIGNING_ENDPOINT }}
    trusted-signing-account-name: ${{ secrets.AZURE_CODE_SIGNING_NAME }}
    certificate-profile-name: ${{ secrets.AZURE_CERT_PROFILE_NAME }}
    files-folder: ${{ github.workspace }}\output
    files-folder-filter: msix

Per Azure DevOps, vedere Impostare Azure DevOps con firma attendibile.

Produzione: distribuzione Microsoft Store

Applies a: Tutte le versioni Windows supportate

Se stai distribuendo attraverso il Microsoft Store, non devi firmare il pacchetto manualmente, ovvero lo Store lo firma durante il processo di invio. Compilare il pacchetto e inviarlo tramite il Centro per i partner. Lo Store fornisce una firma attendibile a livello globale e gestisce tutta la gestione dei certificati.

Produzione: certificato di firma del codice OV

Applica a: Windows 10 e versioni successive

Se la firma degli artefatti non è disponibile per l'area geografica o la situazione, è possibile acquistare un certificato di firma del codice OV (Convalida organizzazione) da un'autorità di certificazione (CA), ad esempio DigiCert, Sectigo o GlobalSign. I costi in genere vanno da $300 a 500/anno.

Dopo aver ottenuto un file PFX dalla tua CA:

SignTool sign /fd SHA256 /a /f .\cert.pfx /p "YourPassword" `
  /tr http://timestamp.digicert.com /td SHA256 `
  MyApp.msix

Per le opzioni di firma complete, vedere Firmare un pacchetto dell'app con SignTool.

Articoli correlati

• Panoramica della firma di un pacchetto MSIX
• Firmare un pacchetto di un'app con SignTool
• Creare un certificato per la firma del pacchetto
• Assegnare pacchetti con Azure Key Vault
• Guida introduttiva alla firma degli artefatti
• Informazioni di riferimento per l'interfaccia della riga di comando di WinApp
• Guida alla risoluzione dei problemi di MSIX