​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.

Different certificates are generated for two groups of services:

  1. Administrative services
    • Gavia REST API Gateway — external API for managing entities;
    • 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.

Using a self-signed certificate

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.

Generating a self-signed certificate

To create a self-signed certificate, use the playbook https-generate-self-signed-cert.yml.

Running this playbook produces the following files:

  • server.crt — the server certificate;

  • server.key — the server’s private key, stored unencrypted and usable without a password.

The certificate files are always stored in the NAICE installation directory at /etc/docker-naice/https/


To regenerate the self-signed certificate, use the following playbook:

ansible-playbook --ask-become-pass https-generate-self-signed-cert.yml -e "cert_update=true"

Self-signed certificate parameters

During system installation, the certificate uses the parameters specified in group_vars/all.yml. If necessary, these variable values can be overridden.

VariableDefault valueDescription
cert_updatefalse

Whether the certificate should be updated / whether certificate files should be replaced (false or true)

server_namenaice.eltex.loc

The domain name used for generating the self-signed certificate

The self-signed certificate is generated with a validity period of 100 years (36,500 days).

If server_name is overridden, the NAICE server must be able to resolve the specified domain name.

To display detailed information about the certificate, run the following command from the directory /etc/docker-naice/https/:

sudo openssl x509 -in server.crt -text -noout

Using a custom certificate

If a CA-signed certificate is available, it is possible to replace the self-signed certificate with your own.

Requirements for a custom certificate

The certificate must meet all of the requirements listed below to ensure proper operation with the NAICE service.

  1. The certificate must be in PEM or CRT format.
  2. Certificates in DER format or PKCS containers are not supported.
  3. The certificate must support AES encryption only.
  4. The certificate and the private key must be provided as separate files.
  5. The password must not contain the following characters: $, ', ", `, brackets, or spaces.
  6. The certificate must include the following attributes:
    1. Subject: CN;
    2. X509v3 Key Usage: Digital Signature, Key Encipherment (must be critical);
    3. X509v3 Extended Key Usage: TLS Web Server Authentication, TLS Web Client Authentication;
    4. X509v3 Subject Alternative Name: must include a DNS name corresponding to the service name.

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

server_domainThe domain name specified in the certificate.
cert_name

Indicates which certificate should be replaced: server or portal. 

key_passwordPassword for the server’s private key file, which will be written to .env. May be left empty.
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

The NAICE server must be able to resolve the domain name specified for NAICE.

When NAICE is deployed with high availability, the domain name must resolve only to the NAICE VIP address.

Ensure that DNS settings and host files contain no records pointing to individual node IP addresses.

Additional information on high-availability configuration.

Certificates and private keys are always stored using the names defined by the cert_name variable (server.crt / server.key and portal.crt / portal.key). During copying or generation, the files will be written under these names.

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.

To replace the certificate, use the following playbook:

ansible-playbook --ask-become-pass https-replacement-cert.yml


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 --ask-become-pass https-replacement-cert.yml -e "confirm_restart=yes"

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.

After the playbook completes, the files will be copied to the directory specified by crt_dir, default: /etc/docker-naice/https/.

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


To maintain NAICE system availability during certificate replacement, perform the following steps:

  1. Determine which NAICE node is the master_host and which is the backup_host.

  2. Run the playbook https-replacement-cert.yml on the master_host.

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

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

  4. Run the playbook https-replacement-cert.yml on the master_host.

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

  5. Verify once again that NAICE is accessible using the domain specified in the certificate.


When NAICE is deployed with high availability, the domain name must resolve only to the NAICE VIP address.

  • Ensure that DNS settings and host files contain no records pointing to individual node IP addresses.

For more information about roles in the high-availability configuration, see the corresponding section.


Viewing certificate parameters

Retrieving LARUS and STERNA metrics based on SSL certificate parameters

You can view metrics or retrieve nginx parameters using the following command:

echo | openssl s_client -showcerts -connect <IP address or domain name>:<443 (larus) or 8443 (sterna)> 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=Aug  4 08:14:38 2025 GMT
notAfter=Jul 11 08:14:38 2125 GMT

Retrieving GAVIA, LEMMUS, and CASTOR metrics based on SSL certificate parameters

Using actuator/info

Link for retrieving full certificate information:

https://<IP address or domain name of the NAICE host>:<8080 (gavia) or 8083 (lemmus) or 8095 (castor)>/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: 19244592885475727591973145804052002034715276745688810459592682276624574339289714069390648805663844950493082500671680699974612649148885698147031400812366597436819722090519472978779492176874177689443467318254708203814163695096868570728315644268961799172054505486971282328942255036955199791178556482256075226107529873779029072878837743602610516019748566847538857795089954010308667413953659603937496147436360006786890382206576197887488769197674705025298289751739634932569724858451487383295432993837619972538208504938563542405133655077876461948127428572892216476675974892639568474369206197573001576242096576121618430483647\n  public exponent: 65537\n  Validity: [From: Thu Dec 05 10:23:44 GMT+07:00 2024,\n               To: Sat Nov 11 10:23:44 GMT+07:00 2124]\n  Issuer: CN=naice.eltex.loc\n  SerialNumber: 4b:ba:13:9a:a4:a2:a8:a2:25:95:31:9d:a7:7a:d4:f3:ee:28:7e:ac\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  DNSName: naice.test.loc\n]\n\n[4]: ObjectId: 2.5.29.14 Criticality=false\nSubjectKeyIdentifier [\nKeyIdentifier [\n0000: 22 71 29 0D DD 79 55 15   7B 08 99 FF B7 86 1E 60  \"q)..yU........`\n0010: 88 E7 0B 7B                                        ....\n]\n]\n\n]\n  Algorithm: [SHA256withRSA]\n  Signature:\n0000: 19 79 88 53 3B 6C 9E 0E   6E 55 3C C9 BA A0 A5 62  .y.S;l..nU\u003C....b\n0010: FA 13 65 6F C0 D6 A3 CC   C8 19 42 02 08 B7 E2 7B  ..eo......B.....\n0020: 9B 86 7B 80 6E BD 28 27   F4 2B 75 72 B6 A1 1B 84  ....n.('.+ur....\n0030: 5D 24 66 ED 07 18 53 53   CC 4C C3 D5 0A A6 4C 30  ]$f...SS.L....L0\n0040: F1 D4 C4 D1 0C A8 26 56   B6 D9 4C 9F B4 6E 46 54  ......&V..L..nFT\n0050: F9 CA 06 70 7D 28 F3 26   B7 8B 6B C1 55 74 6A 9A  ...p.(.&..k.Utj.\n0060: 8C F7 3D 76 9B C7 F1 CF   C0 2E A4 00 E3 3F CF B3  ..=v.........?..\n0070: 3B F8 26 B7 64 F0 70 96   59 99 6C D5 83 41 31 4B  ;.&.d.p.Y.l..A1K\n0080: A6 65 B1 C1 09 86 95 AD   5A 7B 85 B1 2B 21 76 2B  .e......Z...+!v+\n0090: 63 0D CB 2E FD 07 22 05   0A AE A7 4B F3 D2 9A 0C  c.....\"....K....\n00A0: 40 12 4C DC 58 3E 4D 00   5D 92 52 7F 7C A1 5B F2  @.L.X\u003EM.].R...[.\n00B0: A8 B8 90 A9 52 7B 28 BF   5F 72 1A 70 0F FC 3C E2  ....R.(._r.p..\u003C.\n00C0: 40 88 96 4C 22 0D 2B 89   62 61 C8 3C 16 C8 36 ED  @..L\".+.ba.\u003C..6.\n00D0: 01 00 00 53 33 26 B2 72   5C D0 CC 58 0C A7 D8 B0  ...S3&.r\\..X....\n00E0: 99 12 CC 16 4A 40 49 CA   60 BC 2B 63 4E E7 CB 24  ....J@I.`.+cN..$\n00F0: E4 67 5B B4 15 70 DE 60   86 4A 85 82 9E 9D F7 0B  .g[..p.`.J......\n\n]"
}

Using actuator/prometheus

Link for retrieving certificate validity information:

https://<IP address or domain name of the NAICE host>:<8080 (gavia) or 8083 (lemmus) or 8095 (castor)>/actuator/prometheus
# HELP cert_valid_from The start date of the validity period in milliseconds
# TYPE cert_valid_from gauge
cert_valid_from{application="Gavia"} 1.733369024E12
# HELP cert_valid_to The end date of the validity period in milliseconds
# TYPE cert_valid_to gauge
cert_valid_to{application="Gavia"} 4.886969024E12

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
1733369024000

          Convert the resulting integer to a date:

date -d@<converted_integer>
Example of a date after conversion
Sat May 23 07:06:40 +07 56781

          The result will be a readable certificate validity start date.

  • Нет меток