​General description

To ensure secure interaction between the administrator and the NAICE system, protection is implemented for the following user interfaces: lemmus, gavia, larus, castor, and sterna. All HTTP traffic is fully encrypted using the TLS protocol, which prevents data interception and unauthorized access.

During the installation of NAICE services, two self-signed certificates are automatically generated for the user interfaces. This ensures secure HTTPS communication based on the parameters specified in the configuration. For more information about installing NAICE services, see the corresponding section.

Different certificates are generated for two groups of services:

  1. Administrative services:
    • Gavia REST API Gateway — external API for managing NAICE;
    • Lemmus, Authorization Server — authorization server for administrators;
    • Larus — administrator web GUI;
  2. Portal services:
    • Castor — API for portal configuration and portal-based authorization;
    • Sterna — portal web GUI.

If a third-party Certificate Authority (CA) is available, the self-signed certificates can be replaced with certificates issued by the same CA.

Installing a certificate issued by a third-party CA

Certificate requirements

The certificate must meet all of the following requirements to ensure correct operation with the NAICE service:

  1. The certificate must be in PEM or CRT format. Certificates in DER format or PKCS containers are not supported.
  2. The certificate key must either use AES encryption or have no encryption protection applied.
  3. The certificate and the private key must be stored in separate files.
  4. The password must not contain the following characters: $, ', ", `, brackets, or spaces.
  5. The certificate must contain the following attributes: 
    1. Subject: CN;
    2. X509v3 Key Usage: Digital Signature, Key Encipherment (must be marked as critical);
    3. X509v3 Extended Key Usage: TLS Web Server Authentication, TLS Web Client Authentication;
    4. X509v3 Subject Alternative Name: must include either a DNS name matching the server DNS name, or an IP Address matching the server IP address;
    5. If NAICE is deployed in a high-availability configuration without VRRP, the X509v3 Subject Alternative Name attribute must include the DNS name or IP Address of each NAICE server.

Preliminary steps before replacing the certificate

Replacing the self-signed certificate with a custom CA-signed certificate becomes possible only after the NAICE NAC system has been installed on the target host.

To replace the certificate with your own, you must set the appropriate variable values in the group_vars/all.yml file.

The certificate files must be located on the host from which the playbook is executed.

Description of parameters that must be configured before replacing the certificate:

Variable

Description

cert_path

Directory where the certificate will be placed on the target host is specified relative to the NAICE installation directory defined by the naice_address variable. Changing this variable is not recommended.

server_domainDNS name or IP address of the NAICE server.
cert_name

Parameter indicating which certificate should be replaced: the NAICE web GUI certificate ("server") or the web portal authorization certificate ("portal"). Only one certificate can be replaced during a single playbook execution.

key_password

Password for the server’s private key file, which will be written to .env. May be empty if no password is used.

cert_path_srcPath to the custom CA-signed server certificate file. Default: /etc/ssl/certs/server.crt
key_path_srcPath to the private key file for the server certificate. Default: /etc/ssl/private/server.key


If the server_domain variable contains the server DNS name, ensure that this name can be resolved by the DNS server used in the NAICE settings and on the administrator workstations that have access to the NAICE web GUI. Otherwise, access to the web GUI will become unavailable.

Replacing the certificate with a custom one

Before replacing the certificate, make sure that the values of the variables server_domain, cert_name, cert_path_src, key_path_src, and key_password are valid, and update them in ansible/group_vars/all.yml if necessary.

If the private key is not password-protected, the key_password variable must be left empty.

After configuring all the variables for replacing the certificate, run the following playbook:

ansible-playbook https-replacement-cert.yml

If the DNS name specified in the server_domain variable cannot be resolved from the host used to run the Ansible playbook, the playbook execution will fail and an error will occur.

Example error 
TASK [https : Check that host is resolvable] **************************************************************************************************************************************************
fatal: [common_host]: FAILED! => {
    "assertion": "server_domain is ansible.utils.resolvable",
    "changed": false,
    "evaluated_to": false,
    "msg": "Host naice3.test.loc is not resolvable"
}


During the execution of the playbook, you will be prompted twice to confirm the restart of the NAICE system. This confirmation is required in order to proceed with the certificate replacement.

  • If the restart is declined, the playbook will terminate, and the certificate replacement will not be performed.
  • If the restart is confirmed, the NAICE system will be restarted, which may lead to a short period of unavailability.

To replace the certificate without interactive restart confirmation:

ansible-playbook https-replacement-cert.yml -e "confirm_restart=yes"

Certificates and private keys are always stored using the names specified by the cert_name variable (server.crt / server.key and portal.crt / portal.key). When copying or generating certificates, the files will be written using these names and the existing files will be overwritten.

It is important to consider that the restart may affect ongoing system operations, so it is recommended to perform it during a low-load period or at a time when the impact on users is minimal.

Instructions for replacing the certificate for a high-availability NAICE installation

Replacing certificates in a high-availability configuration using VRRP

In this deployment scheme, the domain name used to access the NAICE web GUI must resolve only to the NAICE VIP address. Ensure that there are no entries in the DNS settings or hosts files that point to the individual IP addresses of the nodes.

  1. The same NAICE certificate must be used on both nodes.
  2. Certificate replacement must be performed sequentially on the first and second NAICE nodes.
  3. The address of the node on which the certificate replacement will be performed must be specified in the inventory/hosts.yml file.

To replace the certificate, perform the following steps:

Before running the playbook, carefully review the sections Preliminary steps before replacing the certificate and Replacing the certificate with a custom one.

  1. Determine which NAICE node is the VRRP master and which is the VRRP backup.
  2. Specify the address of the VRRP master in the inventory/hosts.yml file.

  3. Run the https-replacement-cert.yml playbook on the VRRP master.

  4. Verify that NAICE is accessible using the domain specified in the certificate.

  5. Specify the address of the VRRP backup in the inventory/hosts.yml file.

  6. Run the https-replacement-cert.yml playbook on the VRRP backup.

  7. Transfer the VRRP master role to the second node (VRRP backup). To do this, run the following command on the host that currently holds the VIP address:
    sudo systemctl restart keepalived
  8. Verify again that NAICE is accessible using the domain specified in the certificate.
  9. Transfer the VRRP master role back.

Replacing certificates in a high-availability configuration without using VRRP

In this deployment scheme, each host will have its own domain name. This requires each of these names to be specified in the certificate within the X509v3 Subject Alternative Name attribute. Each of these domain names must be resolvable by the DNS server configured on the virtual machines intended for NAICE installation and on the administrator workstations.

  1. The same NAICE certificate must be used on both nodes.
  2. Certificate replacement must be performed sequentially on the first and second NAICE nodes.
  3. The address of the node on which the certificate replacement will be performed must be specified in the inventory/hosts.yml file.
  4. The server_domain variable in the group_vars/all.yml file must contain the domain name of the virtual machine with NAICE on which the certificate replacement will be performed.

To replace the certificate, perform the following steps:

Before running the playbook, carefully review the sections Preliminary steps before replacing the certificate and Replacing the certificate with a custom one.

  1. Specify the address of the first node in the inventory/hosts.yml file.
  2. Specify the domain name of the first node in the server_domain variable of the group_vars/all.yml file.

  3. Run the https-replacement-cert.yml playbook for the first node.

  4. Verify the availability of NAICE using the domain name of the first node.

  5. Specify the address of the second node in the inventory/hosts.yml file.
  6. Specify the domain name of the second node in the server_domain variable of the group_vars/all.yml file.

  7. Run the https-replacement-cert.yml playbook for the second node.

  8. Verify the availability of NAICE using the domain name of the second node.

Removing third-party certificates and restoring the default configuration

After replacing a certificate, the previous certificate will be overwritten. If it is necessary to revert to a self-signed certificate, it must be reissued.

Reissuing a certificate is performed by deleting the previously installed certificates and rerunning the installation playbook.

Delete the installed certificates using the following command (if a high-availability installation is used, the certificates must be deleted on each NAICE node):

# Default NAICE installation directory: /etc/docker-naice
sudo rm -v <NAICE installation directory>/https/*

After deleting the certificates, rerun the installation playbook.

For a stand-alone installation:

ansible-playbook install-naice.yml

For a high-availability installation using VRRP:

ansible-playbook reservation-naice-services.yml -i inventory/hosts-cluster.yml

For a high-availability installation without using VRRP:

ansible-playbook geo-naice-services.yml -i inventory/hosts-geo.yml

Viewing certificate parameters

Retrieving NAICE web GUI and web portal metrics based on SSL certificate parameters

View metrics or retrieve nginx parameters using the following command:

For NAICE web interface:

echo | openssl s_client -showcerts -connect <IP address or domain name>:443 2>&1 | openssl x509 -noout -dates

For NAICE portal web interface:

echo | openssl s_client -showcerts -connect <IP address or domain name>:8443 2>&1 | openssl x509 -noout -dates

Nginx provides a method that returns SSL certificate information in JSON format.
The method returns the following certificate details: issuer, start date, and expiration date.

Example output:

notBefore=Feb 25 04:32:04 2026 GMT
notAfter=Feb  1 04:32:04 2126 GMT

Retrieving GAVIA and LEMMUS metrics based on SSL certificate parameters

Link for retrieving full certificate information

For naice-gavia:

curl -k https://<IP address or domain name of the host for NAICE>:8080/actuator/info

For naice-lemmus:

curl -k https://<IP address or domain name of the host for NAICE>:8083/actuator/info
Example of full certificate information in JSON format 
{"certificationInfo":"[\n[\n  Version: V3\n  Subject: CN=naice.eltex.loc\n  Signature Algorithm: SHA256withRSA, OID = 1.2.840.113549.1.1.11\n\n  Key:  Sun RSA public key, 2048 bits\n  params: null\n  modulus: 20486967698613267930909072363030876768829382668037653959787293720836693037928105253241476741132543189024216394802025956688056563424715596228948534991165300263386817165467478160825626126485740592732390380827272721590133814642584953058405940822026985924893382111244494224675400688570979828213773583419015857751195999453517367776747967524791333248346299091289472585316995257682843651922067607138984537621206898106292347585416976597088550184844009552218272531760031782701234470695835451229760735228708466934677559090711246811340726563284325073340020794600896874630686783268793254419061795884880349881938140092553567913571\n  public exponent: 65537\n  Validity: [From: Wed Feb 25 04:31:57 UTC 2026,\n               To: Fri Feb 01 04:31:57 UTC 2126]\n  Issuer: CN=naice.eltex.loc\n  SerialNumber: 6b:91:5f:9f:fd:8a:aa:af:d1:49:ad:9d:5a:d3:5e:2f:f8:68:a0:dc\n\nCertificate Extensions: 4\n[1]: ObjectId: 2.5.29.37 Criticality=false\nExtendedKeyUsages [\n  serverAuth\n  clientAuth\n]\n\n[2]: ObjectId: 2.5.29.15 Criticality=true\nKeyUsage [\n  DigitalSignature\n  Non_repudiation\n  Key_Encipherment\n  Key_Agreement\n  Key_CertSign\n]\n\n[3]: ObjectId: 2.5.29.17 Criticality=false\nSubjectAlternativeName [\n  IPAddress: 100.110.3.35\n]\n\n[4]: ObjectId: 2.5.29.14 Criticality=false\nSubjectKeyIdentifier [\nKeyIdentifier [\n0000: D2 9A 06 D5 1F 13 45 D1   68 C3 EB 3C 08 26 DB 5C  ......E.h..<.&.\\\n0010: FE E5 92 00                                        ....\n]\n]\n\n]\n  Algorithm: [SHA256withRSA]\n  Signature:\n0000: 7F 27 56 8D 5F E5 98 59   1A 82 0B 43 BB 24 19 AA  .'V._..Y...C.$..\n0010: 8B A0 19 2E B2 12 63 6C   2B 2D B1 19 11 61 B4 58  ......cl+-...a.X\n0020: B7 10 91 F8 A5 60 54 98   0C D5 D9 88 2C 3F 53 C6  .....`T.....,?S.\n0030: 40 75 EC 49 CC 05 13 25   70 A2 43 55 67 86 D5 E7  @u.I...%p.CUg...\n0040: E6 60 50 CD 4F 1B 79 DB   9C 33 E1 BE 18 77 68 65  .`P.O.y..3...whe\n0050: FD 58 5B 6C BA 5C FA DB   4E 12 3B B4 1E 29 75 2A  .X[l.\\..N.;..)u*\n0060: 72 BD 4F DA 7D 99 3F 7B   D4 33 4C C8 10 EB 4E F2  r.O...?..3L...N.\n0070: 90 5A 57 BD 39 C3 D5 DA   DF 18 A2 6C 86 45 3E 0C  .ZW.9......l.E>.\n0080: 0A C7 E7 EF 88 16 E1 8F   DF 81 0D 92 45 9A 46 7A  ............E.Fz\n0090: 61 D3 0B A0 5E DA 7F F6   EF 35 5B E1 4F 91 D8 02  a...^....5[.O...\n00A0: 75 0A 99 52 5F 2F 24 A0   0C 7A 44 77 4E 4A F4 31  u..R_/$..zDwNJ.1\n00B0: D1 F9 35 BC BD A3 DF 08   71 16 AC 32 D4 F6 BF EE  ..5.....q..2....\n00C0: 9F B5 25 58 64 08 BA D5   79 3C B7 77 E4 25 9B 92  ..%Xd...y<.w.%..\n00D0: 51 A6 38 21 F6 09 BA B1   20 C8 E1 69 9E 04 44 B6  Q.8!.... ..i..D.\n00E0: 43 A3 A9 99 63 72 53 B1   F9 36 9F E5 35 5E F8 02  C...crS..6..5^..\n00F0: F1 F5 6B 16 40 FA F3 73   68 48 7E 47 97 B8 92 D4  ..k.@..shH.G....\n\n]"}

Link for retrieving full certificate information

For naice-gavia:

https://<IP address or domain name of the host for NAICE>:8080/actuator/prometheus

For naice-lemmus:

https://<IP address or domain name of the host for NAICE>:8083/actuator/prometheus
# HELP cert_valid_from The start date of the validity period in milliseconds
# TYPE cert_valid_from gauge
cert_valid_from{application="lemmus"} 1.771993917E12
# HELP cert_valid_to The end date of the validity period in milliseconds
# TYPE cert_valid_to gauge
cert_valid_to{application="lemmus"} 4.925593917E12

The resulting metrics cert_valid_from and cert_valid_to correspond to the certificate’s validity start and end timestamps in milliseconds.

To verify the dates, use the following commands in the terminal:

          Convert the value to an integer:

printf "%9.0f\n" <value of cert_valid_from or cert_valid_to>
Example of an integer after conversion
4925593917000

          Convert the resulting integer to a date:

date -d@<converted_integer>
Example of a date after conversion
Wed Nov 10 03:30:00 AM +07 158055

          The result will be a readable certificate validity start date.

Viewing certificates from the operating system console

To display detailed certificate information, run the following command:

# For the NAICE web GUI certificate
sudo openssl x509 -in <NAICE installation directory>/https/server.crt -text -noout

# For the web portal authorization certificate
sudo openssl x509 -in <NAICE installation directory>/https/portal.crt -text -noout


  • Нет меток