Uw MSIX-pakket ondertekenen: uitgebreide handleiding

Deze handleiding begeleidt u bij het ondertekenen van een MSIX-pakket voor elke ontwikkelingsfase, van lokaal testen tot productiedistributie. Zie een overzicht van een MSIX-pakket ondertekenen voor een vergelijking van ondertekeningsopties en -kosten.

Een ondertekeningsbenadering kiezen

Ontwikkeling: Aanmelden voor lokale tests

Gebruik een zelfondertekend certificaat voor lokale ontwikkeling. Zelfondertekende pakketten kunnen alleen worden geïnstalleerd op computers waarop het certificaat expliciet wordt vertrouwd. Dit is opzettelijk en geschikt voor testen.

Optie A: WinApp CLI (aanbevolen voor nieuwe projecten)

De WinApp CLI verwerkt het genereren van certificaten en het aanmelden in één stap.

Stap 1: De WinApp CLI installeren

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

Stap 2: Een zelfondertekend ontwikkelingscertificaat genereren

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

De --manifest vlag leest de naam van de uitgever rechtstreeks vanuit uw appxmanifest.xml. Met de --install vlag wordt het certificaat toegevoegd aan het vertrouwensarchief van de lokale machine, zodat u het pakket onmiddellijk kunt installeren.

Stap 3: Het pakket ondertekenen

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

Optie B: PowerShell + SignTool (Windows 10 en hoger)

Gebruik deze methode als u de WinApp CLI niet gebruikt.

Stap 1: Een zelfondertekend certificaat maken

Voer het volgende uit in een PowerShell-prompt met verhoogde bevoegdheid. De Subject-waarde moet exact overeenkomen met de Publisher in uw 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"

Noteer de vingerafdruk in de uitvoer. U hebt deze nodig in de volgende stappen.

Stap 2: het certificaat exporteren naar een PFX-bestand

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

Stap 3: Het certificaat lokaal vertrouwen

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

Stap 4: Het pakket ondertekenen

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

Zie Een app-pakket ondertekenen met SignTool voor het volledige gebruik van SignTool.

Testen: Distribueren naar testers met een zelfondertekend certificaat

Als u een zelfondertekend MSIX-pakket wilt installeren op de computer van een tester, moet het certificaat eerst op die computer worden vertrouwd.

Testers het certificaat geven: Deel het .pfx bestand of .cer (alleen openbare sleutel) naast het .msix pakket.

Testers voeren het volgende uit in een PowerShell-prompt met verhoogde bevoegdheid:

# 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

Nadat het certificaat is vertrouwd, kunnen testers het .msix installeren door erop te dubbelklikken.

Productie: Azure Artifact Signing (voorheen Trusted Signing)

Van toepassing op: Windows 10 versie 1809 en hoger, Windows 11 (alle versies), Windows Server 2016 en hoger

Azure Artefactondertekening is de nieuwe naam voor wat eerder Vertrouwde Ondertekening werd genoemd. De service is identiek: alleen de naam is gewijzigd. Mogelijk ziet u 'Vertrouwde ondertekening' in bepaalde hulpprogramma's (zoals de azure/trusted-signing-action GitHub-actie en de winget pakket-id) omdat deze verwijzingen na verloop van tijd worden bijgewerkt.

Azure Artifact Signing is de aanbevolen optie voor het ondertekenen van productie-MSIX. Reputatie is gekoppeld aan uw geverifieerde identiteit in plaats van een specifiek certificaat, wat betekent dat uw uitgeversidentiteit in de loop van de tijd SmartScreen-reputatie bouwt wanneer gebruikers uw ondertekende apps installeren. Zie Een MSIX-pakketoverzicht ondertekenen voor geschiktheidsvereisten en kosteninformatie voordat u een account instelt.

Vereiste voorwaarden

• Een artefactondertekeningsaccount met identiteitsvalidatie voltooid en een certificaatprofiel gemaakt. Zie de Quickstart Artefactondertekening.
• De rol Profielondertekening voor vertrouwd handtekeningcertificaat die is toegewezen aan de identiteit die wordt gebruikt voor ondertekening.

Stap 1: Artefactondertekeningshulpprogramma's installeren

De clienthulpprogramma's voor artefactondertekening bevatten de vereiste dlib-invoegtoepassing, een compatibele versie van SignTool en de .NET 8 runtime. De syntaxis van Standard SignTool werkt niet met Artifact Signing zonder dit pakket.

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

Als WinGet niet beschikbaar is (bijvoorbeeld op een Windows Server buildagent), installeert u deze als beheerder via PowerShell:

$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

Stap 2: Een JSON-bestand met metagegevens maken

Maak een bestand met de naam metadata.json met de details van uw artefactondertekeningsaccount. De eindpunt-URI moet overeenkomen met de Azure regio waar u uw account hebt gemaakt (zoek deze in de Azure-portal onder uw artefactondertekeningsaccount als Account-URI):

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

Zie Ondertekeningsintegraties voor de volledige lijst met regiospecifieke eindpunt-URI's.

Stap 3: Verifiëren

Stel uw Azure-referenties in als omgevingsvariabelen (gebruik app-registratiereferenties voor CI/CD):

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

U kunt ook uitvoeren az login voor interactieve lokale ondertekening.

Stap 4: Het pakket ondertekenen

Gebruik de SignTool die is geïnstalleerd met de clienttools voor artefactondertekening. De /dlib vlag verwijst naar de dlib-invoegtoepassing die in de vorige stap is geïnstalleerd:

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

Gebruik de officiële 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

Zie Set up Azure DevOps with Trusted Signing voor Azure DevOps.

Productie: Distributie via de Microsoft Store

Van toepassing op: Alle ondersteunde Windows-versies

Als u distribueert via de Microsoft Store, hoeft u het pakket niet zelf te ondertekenen. De Store ondertekent het tijdens het indieningsproces. Bouw uw pakket en verzend het via partnercentrum. De Store biedt een wereldwijd vertrouwde handtekening en verwerkt alle certificaatbeheer.

Productie: OV-codeondertekeningscertificaat

Van toepassing op: Windows 10 en hoger

Als ondertekening van artefacten niet beschikbaar is voor uw regio of situatie, kunt u een OV-certificaat (Organisatievalidatie) voor ondertekening van code kopen bij een certificeringsinstantie (CA), zoals DigiCert, Sectigo of GlobalSign. Kosten variëren doorgaans van $ 300-500 per jaar.

Zodra u een PFX-bestand van uw CA hebt:

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

Zie Een app-pakket ondertekenen met SignTool voor volledige ondertekeningsopties.

Verwante artikelen

• Een MSIX-pakketoverzicht ondertekenen
• Een app-pakket ondertekenen met SignTool
• Een certificaat maken voor pakketondertekening
• Pakketten toewijzen met Azure Key Vault
• Snelstartgids voor ondertekening van artefacten
• WinApp CLI-referentie
• Handleiding voor het oplossen van problemen met MSIX