Integrering av eSigner med CI/CD-pipeliner (en komplett oppsetts- og konfigurasjonsveiledning)

Omfangsmerknad: Denne veiledningen konsoliderer SSL.coms eksisterende integrasjonsdokumentasjon for eSigner CKA (Cloud Key Adapter) og eSigner CodeSignTool. 

1. eSigner CKA vs. CodeSignTool: Hvilken trenger du? 

SSL.coms eSigner-plattform har to forskjellige klientverktøy for CI/CD-signering, og å velge det rette på forhånd unngår mye bortkastet oppsetttid. 

CI/CD-plattformer med eSigner CKA-veiledninger: GitHub Actions, Azure Pipelines, GitLab CI, Travis CI (alle fire for .vsix-signering), og CircleCI, GitHub Actions, GitLab CI, Travis CI (for .NET DLL-signering via signtool.exe). 

CI/CD-plattformer med eSigner CodeSignTool-guider: CircleCI, GitHub Actions, GitLab CI, Travis CI, Jenkins, Azure DevOps og Bitbucket. 

Hvis pipelinen din kjører på Linux- eller macOS-kjørere, eller du ønsker én konfigurasjonsstil som fungerer på samme måte på tvers av alle CI/CD-verktøy, bruk CodeSignTool. Hvis du allerede er godt kjent med en Windows-basert signtool.exe-arbeidsflyt, vil CKA føles mer naturlig. 

2. Sjekkliste før integrering (gjør dette før du berører CI/CD-konfigurasjon) 

Nesten alle støtteforespørsler om at «signering mislyktes» kan spores tilbake til at et av disse trinnene blir hoppet over eller utført i feil rekkefølge. Gå gjennom denne listen fra topp til bunn. 

2.1 SSL.com-konto og -sertifikat 

• Ha en aktiv SSL.com-konto. Du autentiserer deg hos eSigner med brukernavnet og passordet til denne kontoen fra din egen pipeline, så bruk en dedikert tjeneste-/automatiseringskonto i stedet for en personlig konto der det er praktisk. 
• Kjøp et kodesigneringssertifikat som støtter eSigner: Begge EV-kode signeringssertifikat og OV-kodesigneringssertifikat kan brukes til signering.
• Fullfør organisasjons-/identitetsvalidering. Automatisk signering vil mislykkes (eller aldri registreres) hvis valideringen er ufullstendig.
• Registrer sertifikatet i eSigner. Et sertifikat som ikke er registrert kan ikke brukes til skysignering i det hele tatt – dette er den vanligste blokkeringen for førstegangsintegrasjoner. Følg Registrer eSigner Ekstern dokument-/EV-kodesignering for å koble sertifikatet til eSigner-skytjenesten. 

2.2 Oppsett av e-signeringslegitimasjon og engangskode 

• Konfigurer eSigner Authenticator / TOTP-hemmeligheten. eSigner krever et engangspassord (TOTP) sammen med brukernavnet og passordet ditt for hver signeringssamtale. Følg Automatiser eSigner EV-kodesignering for å hente TOTP_SECRET-en din. Dette er et engangsoppsett. 
• Finn legitimasjons-ID-en din (kun CodeSignTool). Hvis kontoen din har mer enn ett eSigner-kodesigneringssertifikat, blir CREDENTIAL_ID en obligatorisk parameter – CodeSignTool har ingen måte å gjette hvilket sertifikat du mener. Du kan hente listen over legitimasjons-ID-er knyttet til kontoen din ved å bruke kommandoen get_credential_ids CodeSignTool før du kobler opp pipelinen din, slik at du ikke feilsøker en manglende parameter senere. 
• Bestem TEST vs. PROD. eSigner har et sandkassemiljø («TEST»/«sandkasse») og et produksjonsmiljø («PROD»/«produkt»). Pek på TEST mens du validerer pipelinen din, og bytt bare ENVIRONMENT_NAME/MODE til PROD når en fullstendig signeringsrunde fungerer ende til ende. Signering i TEST-modus produserer ikke en sertifikatkjede som er klarert av sluttbrukere. 

2.3 Forutsetninger for CI/CD-plattformen 

• Lagre legitimasjon som krypterte hemmeligheter, aldri som klartekstvariabler i pipeline. Hver plattform nedenfor har en mekanisme for hemmeligheter/beskyttede variabler (GitHub Actions-hemmeligheter, GitLab CI/CD-variabler merket med «Masked», CircleCI-prosjektmiljøvariabler, Jenkins-legitimasjon, Azure DevOps-variabelgrupper/nøkkelhvelv, Bitbucket-repositorivariabler). Bruk den for BRUKERNAVN, PASSWORD, CREDENTIAL_ID og TOTP_SECRET. 
• Bekreft at løperen din har riktig operativsystem/verktøy:
  • eSigner CKA: krever en Windows-runner/agent (Windows-nyeste, Windows-2019, osv.) fordi den installerer en Windows CNG KSP. Den vil ikke kjøre på Linux- eller macOS-avbildninger. 
  • eSigner CodeSignTool (Docker-rute) krever at Docker er tilgjengelig på løperen (docker-tjenesten er aktivert, Docker-in-Docker for GitLab, setup_remote_docker for CircleCI, osv.) og utgående nettverkstilgang til ghcr.io (GitHub Container Registry) og SSL.coms signeringsendepunkter. 
• Sørg for at filen du signerer finnes på byggestadiet før signeringsstadiet kjører. Hver arbeidsflyt nedenfor er delt inn i et byggestadium (produserer artefaktet) og et signeringsstadium (forbruker det) – uoverensstemmelser mellom artefaktbaner mellom to stadier er den vanligste konfigurasjonsfeilen. 

2.4 Valgfritt: Windows-spesifikk forberedelse (kun eSigner CKA) 

• Bekreft at Windows SDK / signtool.exe finnes på runner-avbildningen. Standard Windows-nyeste GitHub/Azure/CircleCI-avbildninger leverer Windows 10 SDK, men den nøyaktige signtool.exe-banen (x86 vs. x64, og SDK-byggnummermappen) varierer etter avbildningsversjon – eksempelarbeidsflytene nedenfor hardkoder en bane, og du bør bekrefte den mot det faktiske avbildningen du bruker. Hvis x64-binærfilen gir en feil, kan du gå tilbake til x86-byggfilen på en bane som C:\Program Files (x86)\Windows Kits\10\bin\ \x86\signtool.exe. 
• Vit hvor eSigner CKA installeres og logger. Installasjonsprogrammet skriver til en -DIR=-sti du velger, og skriver KSP-logger under %APPDATA%\eSignerCKA\KSP — last opp den mappen som en byggeartefakt, slik at mislykkede signeringsforsøk kan diagnostiseres fra CI-logger i stedet for at de krever RDP-tilgang til løperen. 

Når alt ovenfor er gjort, velg verktøyet og plattformkombinasjonen som samsvarer med oppsettet ditt nedenfor. 

 

3. eSigner CKA: CI/CD-integrasjon 

3.1 Vanlige oppsetttrinn (alle plattformer) 

Hver eSigner CKA-arbeidsflyt, uavhengig av plattform, utfører de samme fem handlingene: 

• Last ned og installer eSignerCKA i stille modus. 
• Kjør eSignerCKATool.exe-konfigurasjonen med kontoinformasjonen din, TOTP-hemmeligheten og modusen for å generere en lokal master.key. 
• Kjør eSignerCKATool.exe, og utlast deretter for å registrere sertifikatet i Windows-sertifikatlageret. 
• Les sertifikatets tommelavtrykk ut av Sertifikat:\Gjeldende bruker\Min og send den til signtool.exe (eller OpenVsixSignTool for .vsix-pakker). 
• Last opp eSignerCKA-loggmappen som en byggeartefakt, slik at feil kan feilsøkes. 

4. eSigner CodeSignTool: CI/CD-integrasjon 

4.1 Vanlige oppsetttrinn (alle plattformer) 

CodeSignTool-arbeidsflyter følger de samme to-trinnsmønstrene overalt: en byggefase produserer artefakten, og en signeringsfase henter SSL.coms Docker-bilde fra codesigneren og signerer det. Docker-tilnærmingen betyr at den samme kjernekommandoen fungerer nesten uendret på tvers av CircleCI, GitHub Actions, GitLab CI, Travis CI, Jenkins, Azure DevOps og BitBucket – bare den omkringliggende pipeline-syntaksen er forskjellig. 

Nødvendige miljøvariabler/hemmeligheter: 

Nødvendige inndata: 

5. Eksempel på arbeidsflyter 

Eksempel på arbeidsflyter finnes i følgende SSL.com-guider: 

eSigner CKA: 

• Slik integrerer du eSigner CKA med CI/CD-verktøy: Det finnes veiledninger for GitHub Actions, Azure Pipeline, GitLab CI, CircleCI og Travis CI. 

eSigner CodeSignTool, per plattform: 

• CircleCI 

• GitHub-handlinger 

• GitLab CI 

• Travis C.I. 

• Jenkins CI 

• Azure DevOps 

• BitBucket 

6. Feilsøking av vanlige feil 

Hvis ingen av de ovennevnte løser et problem, kan SSL.com-støtten hjelpe med tilpassede eller store signeringsoppsett.