Connectivity and mTLS Certificates

Подивится українською

1. General Information

WSGATE uses a secure HTTPS connection with mutual TLS authentication — mTLS.

When establishing a connection:
▪️ the client uses its own client certificate and private key;
▪️ UKRCARD verifies the client certificate;
▪️ the client verifies trust in the UKRCARD server certificate.

Test and Production environments are available for WSGATE.

2. Connection Methods

WSGATE supports two connection methods:
▪️ through a VPN channel;
▪️ through the public Internet.

Both connection methods use mTLS. Certificates for VPN connectivity and connectivity through the public address are not interchangeable.

2.1. VPN Connection

VPN connectivity is provided through a VPN channel to internal WSGATE URLs.

Environment	URL	IP Address for VPN Configuration
Test	https://pre-wsgate.ukrcard.com.ua	10.0.24.224
Production	https://wsgate.ukrcard.com.ua	10.0.11.230

Certificates issued by the UKRCARD internal certification authority are used for VPN connectivity.

For configuring the trusted certificate chain, UKRCARD provides the CA certificate of the internal certification authority and, where required, additional technical parameters.

Important for existing clients: current certificates used for VPN connectivity to WSGATE will be revoked on 01 August 2026. A new certificate for VPN connectivity must be obtained and installed before this date.

2.2. Public Internet Connection

Connectivity through the public Internet is provided through public WSGATE DNS names.

Environment	URL
Test	https://prewsgate.ukrcard.com.ua
Production	https://ewsgate.ukrcard.ua

A separate client certificate must be used for connectivity through the public address.

Certificates for VPN connectivity and connectivity through the public address are not interchangeable.

After completing testing, the client may:
▪️ use VPN connectivity only;
▪️ use connectivity through the public Internet only;
▪️ use both connection methods, for example, one as the primary connection and the other as a backup.

3. Integration Implementation and Testing

3.1. Obtain Access to the Test Platform

Obtain Credentials

You will be assigned an external system identifier, ExtSystemid, which you will use when generating the certificate.

You will also be assigned a login and password, which you will use when calling API methods.

Select a Connection Method

For the Test environment, select one of the following connection methods:
▪️ through VPN;
▪️ through the public Internet.

The selected connection method determines the Test environment URL and the type of client certificate that must be obtained.

3.2. Obtain a Client TLS Certificate

Generate a Private Key and CSR

The responsible person on the client side must create a certificate signing request - CSR (Certificate Signing Request).

Example OpenSSL command for generating a CSR:

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

Parameter	Description
req	Creates a certificate signing request CSR
-nodes	Generates a private key without password encryption
-newkey rsa:2048	Generates a new 2048-bit RSA key
-keyout private.key	File used to store the private key
-out request.csr	File containing the generated CSR
-subj	Specifies certificate information in the format Distinguished Name (DN)
emailAddress	Email address of the responsible department or service (Example: admin@ukrcard.ua)
C(Country)	Country code, for example UA
O(Organization)	Company name
OU(Org Unit)	Department name
CN(Common Name)	Unique certificate identifier, which includes: 🔹 ExtSystemid (for example: F102_PURCHASE4) 🔹 City (for example: Tarascha) 🔹 Additional identifier (for example: 001)
-sha256	Uses the SHA-256 hashing algorithm

As a result, two files are created:

• request.csr - the CSR that must be sent to UKRCARD for signing
  
• private.key - the private key, which must be stored securely

Do not send the private.key private key to UKRCARD.

Send the CSR for Signing

Send the generated request.csr file to: security@ukrcard.ua

Existing clients obtaining a new certificate for VPN connectivity must specify that the certificate is required to replace the current certificate and must use the CN previously used in the CSR.

Existing clients obtaining a certificate for public connectivity must also use the CN previously used in the CSR.

Receive the Signed Certificate

After processing the request, UKRCARD sends a response to the email address specified in the CSR.

You will receive an archive containing the signed certificate.

Install the Certificate and Configure mTLS

After receiving the certificate:
▪️ Extract the archive and obtain the certificate.pem file.
▪️ Install the certificate in your service according to the documentation of the software that performs API calls.
▪️ Configure the use of the private.key private key.
▪️ Where required, add ca-bundle.pem to validate the trusted certificate chain.
▪️ Ensure that the certificate.pem client certificate is used when connecting to WSGATE.

Configure Connectivity to the Test Environment

To connect to the Test environment:

1. Use the Test environment URL according to the selected connection method.
2. For VPN connectivity, configure routing to IP address 10.0.24.224.
3. Configure the use of the Test login and password.
4. Configure mTLS using the Test client certificate and private key.
5. Verify that the HTTPS connection is established without certificate errors.

Implement API Calls

Based on the WSGATE documentation, implement the required API calls in your service.

For testing, you can use:
▪️ API method descriptions;
▪️ request and response examples;
▪️ test data;
▪️ a Postman collection, where provided for the relevant API.

Test the Agreed Scenarios

Before moving to the Production environment, complete full integration testing in the WSGATE Test environment.

During testing:
▪️ use Test certificates and Test API endpoints;
▪️ ensure that all requests are signed correctly;
▪️ perform the agreed API operations;
▪️ verify error and timeout handling;
▪️ where required, verify callback / webhook notification processing;
▪️ agree the final configuration with the UKRCARD technical team before moving to the Production environment.

Obtain Confirmation of Successful Test Completion

After completing testing, provide the results to the UKRCARD team.

Once the successful completion of the agreed test scenarios is confirmed, you may proceed with preparing the Production connection.

4. Transition to the Production Environment

4.1. Obtain Production Credentials

For the Production environment, UKRCARD provides:
▪️ a Production external system identifier, ExtSystemid;
▪️ a Production login;
▪️ a Production password.

4.2. Obtain a Client TLS Certificate

For the Production environment, generate and submit a CSR in accordance with the procedure described in section 3.2. Obtain a Client TLS Certificate.

When submitting the CSR, specify:
▪️ the Production environment;
▪️ the selected connection method;
▪️ the Production ExtSystemid.

After processing the request, UKRCARD provides a signed certificate for Production connectivity.

4.3. Configure the Production Endpoint and Certificate

For Production connectivity:

1. Use the Production environment URL according to the selected connection method.
2. For VPN connectivity, configure routing to IP address 10.0.11.230.
3. Configure the Production credentials.
4. Install the certificate for Production connectivity and the corresponding private key.
5. Where required, add the CA certificate or trust chain.
6. Verify that an mTLS connection to the Production WSGATE endpoint can be established.

4.4. Agree and Perform the Launch

Before launching in the Production environment:

1. Agree the transition date with UKRCARD.
2. Perform a pilot operation.
3. Obtain confirmation that the operation was processed correctly.
4. After confirmation, start processing Production operations.