Интегриране на eSigner с CI/CD Pipelines (Пълно ръководство за настройка и конфигуриране)

Забележка за обхвата: Това ръководство консолидира съществуващата документация на SSL.com за интеграция на eSigner CKA (Cloud Key Adapter) и eSigner CodeSignTool. 

1. eSigner CKA срещу CodeSignTool: Кой ви е необходим? 

Платформата eSigner на SSL.com има два различни клиентски инструмента за CI/CD подписване, а изборът на правилния предварително ви позволява да избегнете много загуба на време за настройка. 

CI/CD платформи с ръководства за eSigner CKA: GitHub Actions, Azure Pipelines, GitLab CI, Travis CI (и четирите за .vsix подписване) и CircleCI, GitHub Actions, GitLab CI, Travis CI (за .NET DLL подписване чрез signtool.exe). 

CI/CD платформи с ръководства за eSigner CodeSignTool: CircleCI, GitHub Actions, GitLab CI, Travis CI, Jenkins, Azure DevOps и Bitbucket. 

Ако вашият конвейер работи на Linux или macOS сървъри или искате един стил на конфигурация, който работи по един и същи начин във всеки CI/CD инструмент, използвайте CodeSignTool. Ако вече сте дълбоко запознати с работен процес на signtool.exe, базиран на Windows, CKA ще ви се стори по-естествен. 

2. Контролен списък преди интеграция (направете това, преди да докоснете CI/CD Config) 

Почти всеки билет за поддръжка с „неуспешно подписване“ води до това, че една от тези стъпки е пропусната или изпълнена нередно. Прегледайте този списък от горе до долу. 

2.1 SSL.com акаунт и сертификат 

• Имайте активен SSL.com акаунт. Ще се удостоверявате в eSigner с потребителското име и паролата на този акаунт от вашия процес на разработка, така че използвайте специален акаунт за услуги/автоматизация, а не личен, където е практично. 
• Закупуване на сертификат за подписване на код, който поддържа eSigner: И двете Сертификат за подписване на EV код намлява Сертификат за подписване на OV код може да се използва за подписване.
• Пълна проверка на организацията/самоличността. Автоматичното подписване ще се провали (или дори никога няма да се регистрира), ако проверката е непълна.
• Регистрирайте сертификата в eSigner. Сертификат, който не е регистриран, изобщо не може да се използва за подписване в облака — това е най-често срещаната пречка за първоначални интеграции. Следвайте Регистриране на eSigner за дистанционно подписване на документи/EV код за да свържете сертификата с облачната услуга eSigner. 

2.2 Настройка на eSigner идентификационни данни и OTP 

• Настройте eSigner Authenticator / TOTP тайната. eSigner изисква еднократна парола (TOTP) заедно с потребителското ви име и парола за всяко повикване за подписване. Следвайте Автоматизирайте подписването на eSigner EV Code за да извлечете вашата TOTP_SECRET. Това е еднократна настройка. 
• Намерете вашия Credential ID (само за CodeSignTool). Ако вашият акаунт има повече от един сертификат за подписване на код eSigner, CREDENTIAL_ID става задължителен параметър — CodeSignTool няма начин да познае кой сертификат имате предвид. Можете да извлечете списъка с идентификатори на идентификатори, свързани с вашия акаунт, като използвате командата get_credential_ids CodeSignTool, преди да свържете вашия канал, за да не отстранявате грешки по-късно. 
• Изберете TEST срещу PROD. eSigner има пясъчна среда („TEST“/„sandbox“) и производствена среда („PROD“/„product“). Насочете към TEST, докато валидирате вашия процес на подписване, и превключвайте ENVIRONMENT_NAME/MODE на PROD само след като пълното преминаване към подписване работи от край до край. Подписването в режим TEST не създава верига от сертификати, на която крайните потребители се доверяват. 

2.3 Предварителни изисквания за CI/CD платформата 

• Съхранявайте идентификационните данни като криптирани тайни, никога като променливи в конвейер с открит текст. Всяка платформа по-долу има механизъм за тайни/защитени променливи (тайни на GitHub Actions, променливи на GitLab CI/CD, маркирани с „Masked“, променливи на средата на проекта CircleCI, идентификационни данни на Jenkins, групи променливи/Key Vault на Azure DevOps, променливи на хранилището на Bitbucket). Използвайте го за USERNAME, PASSWORD, CREDENTIAL_ID и TOTP_SECRET. 
• Уверете се, че вашият бегач има правилната операционна система/инструменти:
  • eSigner CKA: изисква Windows runner/agent (Windows-latest, Windows-2019 и др.), защото инсталира Windows CNG KSP. Не работи на Linux или macOS образи. 
  • eSigner CodeSignTool (Docker маршрут) изисква Docker, наличен на runner-а (активирана услуга за Docker, Docker-in-Docker за GitLab, setup_remote_docker за CircleCI и др.) и изходящ мрежов достъп до ghcr.io (GitHub Container Registry) и крайните точки за подписване на SSL.com. 
• Уверете се, че файлът, който подписвате, съществува на етапа на изграждане, преди да се изпълни етапът на подписване. Всеки работен процес по-долу е разделен на етап на изграждане (създава артефакта) и етап на подписване (го използва) — несъответстващите пътища на артефактите между два етапа са най-често срещаната грешка, свързана само с конфигурацията. 

2.4 По избор: Подготовка, специфична за Windows (само за eSigner CKA) 

• Уверете се, че Windows SDK / signtool.exe е наличен в образа на runner. Стандартните Windows-latest GitHub/Azure/CircleCI образи доставят Windows 10 SDK, но точният път до signtool.exe (x86 срещу x64 и папката с номера на компилация на SDK) варира в зависимост от версията на образа — примерните работни потоци по-долу твърдо кодират път и трябва да го проверите спрямо действителния образ, който използвате. Ако x64 двоичният файл даде грешка, върнете се към x86 компилацията по път като C:\Program Files (x86)\Windows Kits\10\bin\ \x86\signtool.exe. 
• Знайте къде се инсталира и регистрира eSigner CKA. Инсталаторът записва в избран от вас път -DIR= и записва KSP регистрационни файлове под %APPDATA%\eSignerCKA\KSP — качете тази папка като артефакт за изграждане, така че неуспешните опити за подписване да могат да бъдат диагностицирани от CI лог файлове, вместо да се изисква RDP достъп до runner-а. 

След като всичко по-горе е направено, изберете комбинацията от инструмент и платформа, която отговаря на вашата настройка по-долу. 

 

3. eSigner CKA: CI/CD интеграция 

3.1 Общи стъпки за настройка (всички платформи) 

Всеки работен процес на eSigner CKA, независимо от платформата, изпълнява едни и същи пет действия: 

• Изтеглете и инсталирайте eSignerCKA в безшумен режим. 
• Стартирайте конфигурационния файл eSignerCKATool.exe с вашите идентификационни данни за акаунта, TOTP секрет и режим, за да генерирате локален master.key. 
• Стартирайте eSignerCKATool.exe, след което го разтоварете, за да регистрирате сертификата в хранилището за сертификати на Windows. 
• Прочетете отпечатъка на сертификата от Сертификат:\ТекущПотребител\Моят и го прехвърлете на signtool.exe (или OpenVsixSignTool за .vsix пакети). 
• Качете папката с лог файлове на eSignerCKA като артефакт за изграждане, така че грешките да могат да бъдат отстранявани. 

4. eSigner CodeSignTool: CI/CD интеграция 

4.1 Общи стъпки за настройка (всички платформи) 

Работните процеси на CodeSignTool следват едни и същи двуетапни модели навсякъде: етапът на изграждане създава артефакта, а етапът на подписване извлича Docker образа на кодовия подписвач на SSL.com и го подписва. Подходът на Docker означава, че една и съща основна команда работи почти непроменена в CircleCI, GitHub Actions, GitLab CI, Travis CI, Jenkins, Azure DevOps и BitBucket — различава се само синтаксисът на околния конвейер. 

Необходими променливи/секрети на средата: 

Необходими входни данни: 

5. Примерни работни процеси 

Примерни работни процеси са предоставени в следните ръководства на SSL.com: 

eSigner CKA: 

• Как да интегрирате eSigner CKA с CI/CD инструменти: Предоставени са ръководства за GitHub Actions, Azure Pipeline, GitLab CI, CircleCI и Travis CI. 

eSigner CodeSignTool, за всяка платформа: 

• CircleCI 

• Действия на GitHub 

• GitLab CI 

• Травис CI 

• Дженкинс CI 

• Azure DevOps 

• BitBucket 

6. Отстраняване на често срещани грешки 

Ако нищо от горните не реши проблема, поддръжката на SSL.com може да помогне с персонализирани настройки или настройки за подписване с голям обем.