Підключення та mTLS-сертифікати

1. Загальна інформація

Для підключення до WSGATE використовується захищене HTTPS-з’єднання з взаємною TLS-аутентифікацією - mTLS.

Під час встановлення з’єднання:
▪️ клієнт використовує власний клієнтський сертифікат і приватний ключ;
▪️ UKRCARD перевіряє клієнтський сертифікат;
▪️ клієнт перевіряє довіру до сертифіката сервера UKRCARD.

Для WSGATE доступні тестове та продуктивне середовища.

2. Способи підключення

Для WSGATE доступні два способи підключення:

через VPN-канал до внутрішніх ресурсів UKRCARD;
через публічну адресу, доступну з мережі Інтернет.

Обидва способи підключення використовують mTLS.

Сертифікати для VPN-підключення та для підключення через публічну адресу не є взаємозамінними.

2.1. Підключення через VPN

Підключення через VPN виконується через VPN-канал до внутрішніх URL WSGATE.

Для доступу використовуються такі адреси:

Середовище	URL	IP-адреса для налаштування VPN
Тестове	https://pre-wsgate.ukrcard.com.ua	10.0.24.224
Продуктивне	https://wsgate.ukrcard.com.ua	10.0.11.230

Для VPN-підключення використовуються сертифікати, випущені внутрішнім центром сертифікації UKRCARD.

Для налаштування довіреного ланцюжка сертифікатів UKRCARD надає CA-сертифікат внутрішнього центру сертифікації та, за потреби, додаткові технічні параметри.

Важливо для чинних клієнтів: поточні сертифікати для VPN-підключення до WSGATE будуть відкликані 01.08.2026. До цієї дати необхідно отримати та встановити новий сертифікат для VPN-підключення.

Нові клієнти отримують актуальний сертифікат для VPN-підключення у межах стандартного процесу підключення.

2.2. Підключення через публічну мережу Інтернет

Для WSGATE також доступне підключення через публічні DNS-імена з мережі Інтернет.

Середовище	URL
Тестове	https://prewsgate.ukrcard.com.ua
Продуктивне	https://ewsgate.ukrcard.ua

Для підключення через публічну адресу необхідно використовувати окремий клієнтський сертифікат.

Сертифікати для VPN-підключення та для підключення через публічну адресу не є взаємозамінними.

Після завершення тестування клієнт може:

▪️ використовувати лише VPN-підключення;
▪️ використовувати лише підключення через публічну мережу Інтернет;
▪️ використовувати обидва способи підключення, наприклад один як основний, інший як резервний.

3. Реалізація та тестування інтеграції

3.1. Отримайте доступ до тестової платформи

Отримайте облікові дані

Вам призначається ідентифікатор зовнішньої системи ExtSystemid, які ви використовуватимете при генерації сертифіката. Також вам призначається логін login і пароль password, які ви використовуватимете надалі при кожному виклику API методів.

Оберіть спосіб підключення

Для тестового середовища необхідно обрати один зі способів підключення:

▪️ через VPN;
▪️ через публічну мережу Інтернет.

Обраний спосіб підключення визначає URL тестового середовища та тип клієнтського сертифіката, який необхідно отримати.

3.2. Отримайте клієнтський TLS-сертифікат

Згенеруйте приватний ключ і CSR

Відповідальна особа з вашого боку повинна створити запит на підпис сертифіката CSR (Certificate Signing Request):

Приклад команди для генерації CSR за допомогою OpenSSL:

openssl req -nodes -newkey rsa:2048 -keyout private.key -out request.csr -subj "/emailAddress=admin@ukrcard.ua/C=UA/O=NATIVE APPS/OU=IT/CN=F102_PURCHASE4_Tarascha_001" -sha256

Параметр	Опис
req	Використовується для створення запиту на підпис сертифіката (CSR)
-nodes	Генерує приватний ключ без шифрування (без запиту пароля на нього)
-newkey rsa:2048	Генерує новий ключ RSA довжиною 2048 біт
-keyout private.key	Файл, у який буде збережено приватний ключ
-out request.csr	Файл вихідного CSR-запиту
-subj	Визначає інформацію про сертифікат у форматі Distinguished Name (DN)
emailAddress	Email відповідального підрозділу або сервісу. На цей email буде відправлен підписаний сертифікат. А також на цей email прийде запит на подовження строка дії в майбутньому (наприклад: admin@ukrcard.ua)
C(Country)	Код країни (наприклад: UA)
O(Organization)	Назва компанії (наприклад: UKRCARD)
OU(Org Unit)	Відділ (наприклад: IT)
CN(Common Name)	Унікальний ідентифікатор сертифіката, що включає: 🔹 ExtSystemid (наприклад: F102_PURCHASE4) 🔹 Місто (наприклад: Tarascha) 🔹 Додатковий ідентифікатор (наприклад: 001)
-sha256	Використовує алгоритм хешування SHA-256

В результаті ви отримаєте:
- request.csr (Запит на підпис. Файл який треба відправити на підпис security@ukrcard.ua)
- private.key (Закритий ключ, який треба зберігати в захищеному місці!)

Приватний ключ private.key не передається до UKRCARD.

Надішліть CSR для підписання

Надішліть згенерований request.csr на email security@ukrcard.ua.

💡

Рекомендований формат листа:
Тема: Запит на підпис TLS-сертифіката для <назва компанії>
Вкладення: request.csr
У листі також зазначте:
▪️ тестове середовище;
▪️ обраний спосіб підключення: VPN або публічна мережа Інтернет;
▪️ за потреби - додаткові коментарі щодо підключення.

Для чинних клієнтів, які отримують новий сертифікат для VPN-підключення, необхідно зазначити, що сертифікат потрібен для заміни поточного сертифіката, та у CSR необхідно використовувати CN, який застосовувався раніше .

Для чинних клієнтів, які отримують сертифікат для публічного підключення, у CSR також необхідно використовувати CN, який застосовувався раніше.

Отримайте підписаний сертифікат

Після обробки запиту UKRCARD надсилає відповідь на email, указаний у CSR.

Ви отримаєте архів із підписаним сертифікатом.

💡

Архів може містити:
certificate.pem - підписаний клієнтський сертифікат;
ca-bundle.pem - ланцюжок довіри, який може знадобитися для налаштування.

Встановіть сертифікат і налаштуйте mTLS

Після отримання сертифіката:

▪️ Розпакуйте архів та отримайте файл certificate.pem.
▪️ Встановіть сертифікат у вашому сервісі відповідно до документації програмного забезпечення, яке виконує API-виклики.
▪️ Налаштуйте використання приватного ключа private.key.
▪️ За потреби додайте ca-bundle.pem для перевірки довіреного ланцюжка сертифікатів.
▪️ Переконайтеся, що під час з’єднання з WSGATE використовується клієнтський сертифікат certificate.pem.

3.3. Налаштуйте підключення до тестового середовища

Для підключення до тестового середовища:

Використовуйте URL тестового середовища відповідно до обраного способу підключення.
Для VPN-підключення налаштуйте маршрутизацію до IP-адреси 10.0.24.224.
Налаштуйте використання тестових login і password.
Налаштуйте mTLS із тестовим клієнтським сертифікатом та приватним ключем.
Перевірте встановлення HTTPS-з’єднання без помилок сертифіката.

3.4. Реалізуйте API-виклики

На основі документації WSGATE реалізуйте необхідні API-виклики у вашому сервісі.

Для тестування можна використовувати:
▪️ опис API-методів;
▪️ приклади запитів і відповідей;
▪️ тестові дані;
▪️ Postman collection, якщо вона надана для відповідного API.

3.5. Протестуйте погоджені сценарії

Перед переходом до продуктивного середовища необхідно виконати повне тестування інтеграції у тестовому середовищі WSGATE.

Під час тестування:
▪️ використовуйте тестові сертифікати та тестові API-endpoint-и;
▪️ переконайтеся, що всі запити коректно підписані;
▪️ виконайте погоджені API-операції;
▪️ перевірте обробку помилок і таймаутів;
▪️ за потреби перевірте обробку callback / webhook-повідомлень;
▪️ погодьте з технічною командою UKRCARD фінальні налаштування перед переходом до продуктивного середовища.

3.6. Отримайте підтвердження успішного проходження тестів

Після завершення тестування надайте результати команді UKRCARD.

Після підтвердження успішного проходження погоджених тестових сценаріїв можна переходити до підготовки продуктивного підключення.

4. Перехід до продуктивного середовища

4.1. Отримайте продуктивні облікові дані

Для продуктивного середовища UKRCARD надає:
▪️ продуктивний ідентифікатор зовнішньої системи ExtSystemid;
▪️ продуктивні login;
▪️ продуктивний password.

4.2. Отримайте клієнтський TLS-сертифікат

Для продуктивного середовища сформуйте та надішліть CSR відповідно до процедури, описаної в розділі 3.2. Отримайте клієнтський TLS-сертифікат.

Під час надсилання CSR зазначте:
▪️ продуктивне середовище;
▪️ обраний спосіб підключення;
▪️ продуктивний ExtSystemid.

Після обробки запиту UKRCARD надає підписаний сертифікат для продуктивного підключення.

4.3. Налаштуйте продуктивний endpoint і сертифікат

Для продуктивного підключення:

Використовуйте URL продуктивного середовища відповідно до обраного способу підключення.
Для VPN-підключення налаштуйте маршрутизацію до IP-адреси 10.0.11.230.
Налаштуйте продуктивні облікові дані.
Встановіть сертифікат для продуктивного підключення та відповідний приватний ключ.
За потреби додайте CA-сертифікат або ланцюжок довіри.
Перевірте встановлення mTLS-з’єднання з продуктивним WSGATE endpoint.

4.4. Погодьте та виконайте запуск

Перед запуском у продуктивному середовищі:

Узгодьте з UKRCARD дату переходу.
Виконайте пілотну операцію.
Отримайте підтвердження коректності виконання операції.
Після підтвердження запускайте продуктивний потік операцій.