IPF Certificates

You are accessing the IP Fabric GUI using a secure TLS connection. A self-signed server certificate is automatically generated during the IP Fabric deployment. But by the nature of SSL/TLS, the self-signed server certificate cannot be trusted – as indicated in an SSL/TLS error in the web browser (for example, NET::ERR_CERT_AUTHORITY_INVALID in Google Chrome).

We recommend you replace the self-signed server certificate with your own server certificate signed by a trusted certificate authority.

Usually, the server certificate replacement can be handled via Settings → System → IPF Certificates and consists of the following steps:

generate a CSR (certificate signing request)
sign the generated CSR with a trusted certificate authority
upload the signed server certificate

Important

Only a certificate that is the result of signing a CSR generated with Settings → System → IPF Certificates → Generate can be uploaded to IP Fabric with Settings → System → IPF Certificates → Upload and used as IP Fabric’s server certificate.

In the Miscellaneous section, we also describe how to handle some special requirements in regard to certificates – when Settings → System → IPF Certificates on its own is not sufficient.

Generate CSR (Certificate Signing Request)

Subject Alternative Name

Short Subject Alternative Names (only hostnames without a domain name) are not accepted by all CAs (certificate authorities). To remove it from the CSR, switch off the Include DNS short name in CSR SAN toggle.

Only some characters allowed in fields

The fields Organization name, Department, City, State / Province must match the following regular expression: /^[A-Za-z0-9.,\/_@%^:=+ -]*$/

it must contain only these characters: A-Z a-z 0-9 .,/_@%^:=+ -

This is for security reasons.

If this is too restrictive, please follow the instructions in Generate CSR with Special Characters.

Go to Settings → System → IPF Certificates.
Fill out the Create a CSR (Certificate Signing Request) form.
Click Generate (in the top-right corner).
A file called nimpee.csr will be downloaded.

Sign Generated CSR

This step depends on the vendor and version of your certificate authority. So please check the vendor’s documentation.

Upload Signed Server Certificate

Warning

Only PEM (Base64-encoded) certificate format is supported.

Warning

Only a certificate that was created by signing the most-recent CSR can be uploaded to IP Fabric! If you generate another CSR before uploading the certificate created from the previously generated CSR, the certificate will not be applied.

Important

If you are signing a certificate by a certificate authority that also has intermediate certificates, the whole certificate chain needs to be included in the final certificate uploaded to IP Fabric in one continuous file:

-----BEGIN CERTIFICATE-----
(Base64 server certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Base64 intermediate certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Base64 root certificate)
-----END CERTIFICATE-----

Go to Settings → System → IPF Certificates.
Click Upload (in the top-right corner).
Drag and drop the new certificate or use Select file to upload it.
While the new certificate is being installed, the IP Fabric GUI can be unresponsive for a few seconds.
Refresh the IP Fabric GUI in your browser.

Miscellaneous

Generate CSR with Special Characters

Let’s consider an example where we enter Test Company with & (please note that the character & is not allowed) as the Organization name. After filling in the remaining fields, when we click Generate, an Invalid Input error will be displayed.

If any special characters are required in any of the mentioned fields, you may use the following steps:

Fill out the Create a CSR (Certificate Signing Request) form, but avoid any special characters (in our example, we replaced Test Company with & with Test Company with):
Click Generate.
- In the browser, a file called nimpee.csr will be downloaded - please do not use this file.
- The files customer.conf, customer.key, and customer.csr will be generated in the directory /opt/nimpee/conf.d/ssl-cust on the IP Fabric appliance. It’s important to note that customer.csr will be identical to nimpee.csr.
Log in to the IP Fabric CLI as the osadmin user.
Change to root:
```
sudo su
```
Change to the /opt/nimpee/conf.d/ssl-cust directory:
```
cd /opt/nimpee/conf.d/ssl-cust
```
Remove customer.key and customer.csr (will be re-generated in step 8):
```
rm customer.key customer.csr
```
Modify customer.conf (for example with vi customer.conf; in our example, we changed Test Company with to Test Company with &):

Generate new customer.key and customer.csr files using the modified customer.conf:

openssl req -new -config customer.conf -keyout customer.key -out customer.csr

Check the new customer.csr:

openssl req -in customer.csr -noout -text

Download the new customer.csr (for example with scp) for signing.

Once you have the signed certificate ready, navigate to Settings → System → IPF Certificates and click Upload to begin the process of uploading the certificate.

Additionally Add Entire Certificate Chain

A new, unmodified certificate file might contain only the server certificate itself without the certificate chain (intermediate and root certificates).

This might be sufficient for your browser (as it most probably already has the corresponding intermediate and root certificates), but not for SSO.

SSO requires the certificate to have the entire certificate chain (including the intermediate and root certificates).

After uploading such a certificate via Settings → System → IPF Certificates → Upload, you will encounter the following error while logging in to IP Fabric via SSO:

{"code":"API_AUTHENTICATION_FAILURE","message":"Authentication Failure","errors":[{"message":"Error: unable to verify the first certificate"}]}

Tip

Alternatively, you may append the intermediate and root certificates to the certificate file before uploading it via Settings → System → IPF Certificates → Upload – as described above in Upload Signed Server Certificate.

To ensure that the certificate on the IP Fabric appliance has the entire certificate chain, do the following:

Log in to the IP Fabric CLI as the osadmin user.
Change to root:
```
sudo su
```
Change to the /etc/nginx/ssl directory:
```
cd /etc/nginx/ssl
```
Verify that the server.crt file indeed has only the server certificate itself:
```
grep 'CERTIFICATE' server.crt
```
(the command should return only one pair of -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)
Make a backup of server.crt:
```
cp server.crt server.crt.bkp
```
Append the immediate and root certificates to server.crt:
```
vi server.crt
```
In case you do not have the immediate and root certificates readily available:
1. Open the IP Fabric GUI in your browser.
2. Click the lock icon in the browser’s address bar and download the entire certificate chain:
  
  Google Chrome: Connection is secure → Certificate is valid → Details → Export… → Base64-encoded ASCII, certificate chain
  
  Mozilla Firefox: Connection is secure → More information → View Certificate → Download → PEM (chain)
3. Go to the IP Fabric CLI.
4. Clear the content of server.crt:
```
echo '' > server.crt
```
5. Copy the content of the entire certificate chain and paste it into server.crt:
```
vi server.crt
```

Verify that the MD5 hashes of server.crt and server.key are identical:

Example

root@ipfabric:/etc/nginx/ssl# openssl x509 -noout -modulus -in server.crt | openssl md5
(stdin)= 9dcfd46578b9dffe06ca0146607f6153
root@ipfabric:/etc/nginx/ssl# openssl rsa -noout -modulus -in server.key | openssl md5
(stdin)= 9dcfd46578b9dffe06ca0146607f6153

Danger

Do not proceed with the next step if the MD5 hashes do not match!

Restart the nginx web server:
```
systemctl restart nginx
```
Check if the nginx web server is running:
```
systemctl status nginx
```
Try to log in to IP Fabric via SSO again.

Add Custom SSL Certificate

In case you require a custom SSL certificate (prepared completely outside IP Fabric) and cannot use Settings → System → IPF Certificates, follow this guide to replace the self-signed certificate manually.

Important

Please ensure that the FQDN (DNS name) of the IP Fabric appliance is set as your custom certificate’s Subject Alternative Name. Having the FQDN as the certificate’s Subject or Common Name is not sufficient.

Log in to the IP Fabric CLI as osadmin.
Change to root:
```
sudo su
```
Change to the /etc/nginx/ssl directory:
```
cd /etc/nginx/ssl
```

Backup the previous server certificate and its private key:

mv server.crt server.crt.bkp
mv server.key server.key.bkp

Upload the new certificate chain and private key to the /etc/nginx/ssl/ directory
1. They have to have the same names as those previous ones – server.crt and server.key
2. server.crt needs to contain the new SSL certificate and full certificate chain in PEM format
3. server.key needs to contain the new SSL certificate’s private key in decrypted PEM format
The certificate chain in server.crt must have the following sequence:
1. server certificate
2. intermediate certificate(s)
3. root certificate
Make sure that the new server.key has the same owner and group (root:autoboss) and permissions (-rw-r-----) as the old one:
```
chown root:autoboss server.key
chmod 0640 server.key
```
Verify that the MD5 hashes for server.crt and server.key are identical:
Example
```
root@ipfabric:/etc/nginx/ssl# openssl x509 -noout -modulus -in server.crt | openssl md5
(stdin)= 9dcfd46578b9dffe06ca0146607f6153
root@ipfabric:/etc/nginx/ssl# openssl rsa -noout -modulus -in server.key | openssl md5
(stdin)= 9dcfd46578b9dffe06ca0146607f6153
```
Danger

Do not proceed with the next step if the MD5 hashes do not match!

If the MD5 hashes do not match, check if the certificate chain is in the correct order and if the private key corresponds to the server certificate.
Restart the nginx web server:
```
systemctl restart nginx
```
Check if the nginx web server is running:
```
systemctl status nginx
```
Verify that the new certificate works correctly by visiting the IP Fabric main GUI in the browser.