Replacing the HTTPS certificate

The IAM appliance presents its services using an HTTPS interface. The web interface is realized by an nGinx web server. During the first installation of nGinx (the iam-app-web-proxy package), self-signed certificates based on the server hostname are created. A self-signed certificate is not suitable for most uses, and thus it needs to be replaced.

Replacing the HTTPS certificate

  1. Certificate and key requirements.

  2. Upload a private key and certificate (potentially including the chain) to the appliance.

  3. Replace the certificate and key.

  4. Save the root certificate to a trusted certificate storage.

  5. Restart the iam-web-proxy service and related services.

  6. Check.

Certificate and key requirements

  • The private key is in the PEM format without password, size 2048b (for RSA keys) or more.

  • The signing algorithm for the certificate is at least SHA-256.

  • The certificate is is the x509 PEM format, x509v3 extensions are supported.

    • The server certificate has not only the CN part of the distinguished name but also a x509 extension subjectAltName. This is because modern browsers often ignore CN.

    • If a certificate chain needs to be supplied (intermediate certificate authorities), their certificates are placed in the same file, also in the PEM format. The order of certificates in the file is (top to bottom):

      1. Server certificate.

      2. Certificate of the CA which issued the server certificate.

      3. Other CA certificates in the order of chain trust (going up).

An example of file with a private key
[root@localhost secrets]# cat current_web_cert.key
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAwuOKM39s1uqEVq+ngNaGgqpPNAPfu1NF7GThfPGgCa3e0Xjf
/gRZZygwqMnWfPTcgxDkK43xWo95nMmnAzsjn5S9/PX1fP+Sb4AYn+a8EOaZxy9x
... abbreviated...
MjvCAQKBgBnOMJTEtWTAXtQo6gR5q5WSvGhv/xOg+VymOYNIiIoOg49dfieEtOCN
3D53ENWGL60+C4fkY6lQw1Vog2rJ5Gm16XA6iAxBNI1Wf6zrZsMmKbyPtXFHAyZc
imNeWy2jGCnsGft1diBBrgUxPCz1k+gLlWIvqs4Nr9tx+hzTR0sn
-----END RSA PRIVATE KEY-----
An example of file with a server certificate
[root@localhost secrets]# cat current_web_cert.crt
-----BEGIN CERTIFICATE-----
MIICzjCCAbagAwIBAgIUQbCKf99dSmVlucvY8TyQGVQieNgwDQYJKoZIhvcNAQEL
BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTIxMDEyMDE0NDAxMFoXDTIyMDEy
... abbreviated ...
SvOiau16nBSe5wHzFqX3M1HsJp9X+j3PjOtGPDqf3mG6/NYzgqFlHC0bWCnMEZtl
sGh4k0AB/W7AxTKN4KwgY7YaqFwcLZveHcbSSztlmNt9YXIhNXzWvuYIbuyhBMuW
04k=
-----END CERTIFICATE-----
// other certificates from the trust chain may follow

Upload a private key and certificate to the appliance.

Use the SCP protocol to upload to files to the server. On Linux, the basic scp command can be used. On Windows, a client utility WinSCP can be used. Using a selected tool, upload the certificate and the key to the server, the target directory is /data/volumes/web-proxy/secrets/.

Replace the certificate and key

After we upload the certificate and the key to the server, we have two new (https_new.*) and two old (current_web_cert.*) files.

[root@localhost ~]# cd /data/volumes/web-proxy/secrets/
[root@localhost secrets]# ll
total 16
-rw-r--r--. 1 root root 1034 Jan 20 14:40 current_web_cert.crt
-rw-------. 1 root root 1675 Jan 20 14:40 current_web_cert.key
-rw-r--r--. 1 root root 1034 Jan 28 09:33 https_new.crt
-rw-------. 1 root root 1675 Jan 28 09:33 https_new.key

In the directory /data/volumes/web-proxy/secrets/, we create a backup of the original certificate and key and deploy the new ones.

[root@localhost secrets]# cp current_web_cert.key current_web_cert.key.orig
[root@localhost secrets]# cp current_web_cert.crt current_web_cert.crt.orig

[root@localhost secrets]# mv https_new.crt current_web_cert.crt
mv: overwrite 'current_web_cert.crt'? y
[root@localhost secrets]# mv https_new.key current_web_cert.key
mv: overwrite 'current_web_cert.key'? y

Change ownership, permissions and labels.

[root@localhost secrets]# chown root:root current_web_cert.crt current_web_cert.key
[root@localhost secrets]# chmod 644 current_web_cert.crt
[root@localhost secrets]# chmod 600 current_web_cert.key

[root@localhost secrets]# restorecon current_web_cert.crt current_web_cert.key

Save the root certificate to a trusted certificate storage

Some IAM appliance services use HTTPS communication through the iam-web-proxy service. After replacing the web proxy certificate, the communication may stop working, making some parts of the appliance unavailable for users.

If you have already saved for example a root certificate CA to /data/volumes-shared/cacerts/ and this certificate is still a part of the trust chain of the deployed certificate, you can skip following steps.
Copy the certificate chain to trusted certificates
[root@localhost secrets]# cp current_web_cert.crt /data/volumes-shared/cacerts/some_new_name.crt
Edit the file and remove each certificate except the last one
[root@localhost secrets]# nano /data/volumes-shared/cacerts/some_new_name.crt

Restart the iam-web-proxy service and related services

Finally, restart the web proxy service. Some IAM appliance services may shortly become unavailable.

[root@localhost ~]# systemctl restart iam-web-proxy

After this, if you are unable to authenticate to some IAM appliance component, this service needs to be restarted.

Restart the CzechIdM and CAS services
[root@localhost ~]# systemctl restart iam-czechidm iam-cas

Check

Using the browser to access some IAM services, check that the new certificate is correctly deployed.

If needed, you can restore the original certificate from the backup you created (*.orig files created in a previous steps). After that, we need to repeat the steps to change the permissions for the files and restart the services.