Tip

This is the documentation for the 23.02 version. Looking for the documentation of the latest version? Have a look here.

TNSR GUI Service with Client Certificate Authentication¶

This recipe covers setting up the TNSR GUI and accessing it using a client certificate.

Prerequisites¶

Before starting, configure the RESTCONF service and related settings as described in RESTCONF Service Setup with Certificate-Based Authentication and NACM but with the following suggested alterations:

Do not use SAN entries on any certificates, as that may cause issues with the certificates being recognized as being suitable for specific purposes.

This will be corrected in future versions of TNSR.
For environments with multiple TNSR instances, use a unique CA and certificate name for each TNSR instance as the way browsers track and suggest client certificates may make it difficult to distinguish between them otherwise.

For example, if a TNSR hostname is r1, then make the CA as r1-selfca and prefix user certificates with the hostname as well, such as r1-myuser. The server certificate should be using the hostname or IP address for its CN, so that should be sufficiently unique already.

Alternately, use the same CA on all TNSR instances by generating it on one system and then importing it into the others.

Enable the GUI Service¶

To enable the GUI service, use gui enable from config-restconf mode:

tnsr(config)# restconf
tnsr(config-restconf)# gui enable
tnsr(config-restconf)# exit

Create User Certificates¶

Each user accessing the GUI must have their own unique certificate.

Warning

Do not share certificates between multiple users!

Create PKCS#12 Archives¶

Most operating systems and browsers expect to import certificates as a PKCS#12 archive file ending in the extension .p12. Different operating systems and software have slightly different expectations about how these files are formed as well.

The separate certificate and private key files can be combined into a PKCS#12 archive using the TNSR CLI (PKCS#12 Archives). Alternately, this can be done with openssl in an appropriate shell on TNSR, macOS, Linux, FreeBSD, or any other similar OS shell that has openssl installed.

Export User Certificates¶

To generate PKCS#12 archives using OpenSSL, first export the user certificate data. This can be skipped if the PKCS#12 archives will be created in the TNSR CLI.

tnsr(config)# pki private-key r1-myuser get
-----BEGIN PRIVATE KEY-----
[key data]
-----END PRIVATE KEY-----

Copy all of this text, including the header and footer armor lines, and paste it into a new file named r1-myuser.key.

tnsr(config)# pki certificate r1-myuser get
-----BEGIN CERTIFICATE-----
[key data]
-----END CERTIFICATE-----

Copy all of this text, including the header and footer armor lines, and paste it into a new file named r1-myuser.crt.

Linux/Windows/FreeBSD/Other¶

To make a PKCS#12 which can be used by a Linux, Windows, FreeBSD, or other modern clients, use a high level of encryption:

Using the TNSR CLI:

tnsr# pki pkcs12 r1-myuser generate export-password abc12345
 key-pbe-algorithm AES-256-CBC certificate-pbe-algorithm AES-256-CBC mac-algorithm sha256

This will result in a file named r1-myuser-<timestamp>.p12 in the home directory of the TNSR CLI user running the command. Copy this file off using scp or similar and then copy it to the client system.

Using OpenSSL:

$ openssl pkcs12 -export -inkey ./r1-myuser.key \
  -in ./r1-myuser.crt -out ./r1-myuser.p12 \
  -certpbe AES-256-CBC -keypbe AES-256-CBC -macalg sha256

Enter and confirm a password when prompted. The client will require this password when importing the PKCS#12 archive.

macOS¶

macOS clients do not currently support high level encryption on PKCS#12 archive files, so an archive for those clients needs different, weaker, algorithms:

Using the TNSR CLI:

tnsr# pki pkcs12 r1-myuser generate export-password abc12345
 key-pbe-algorithm PBE-SHA1-3DES certificate-pbe-algorithm PBE-SHA1-3DES mac-algorithm sha1

This will result in a file named r1-myuser-<timestamp>.p12 in the home directory of the TNSR CLI user running the command. Copy this file off using scp or similar and then copy it to the client system.

Using OpenSSL:

$ openssl pkcs12 -export -inkey ./r1-myuser.key \
  -in ./r1-myuser.crt -out ./r1-myuser.p12 \
  -certpbe PBE-SHA1-3DES -keypbe PBE-SHA1-3DES -macalg SHA1

Enter and confirm a password when prompted. The client will require this password when importing the PKCS#12 archive. macOS will not import a PKCS#12 archive without a password.

Import User Certificates¶

Importing the certificate varies based on the OS and in some cases by browser.

Windows and macOS have integrated certificate storage which can be accessed by browsers for these purposes. Linux may vary based on distribution, but in many cases it’s simpler to import the certificate directly into the browser there.

Windows 10/11¶

To import the certificate into a Windows 10 or 11 client:

Open the directory containing the .p12 file in File Explorer
Double click the file to open the Certificate Import Wizard
Select Current User
Click Next
Confirm the path to the .p12 file is correct
Click Next
Enter the Password used when creating the .p12 file
Leave the remaining options at their defaults
Click Next
Select Place all certificates in the following store
Select Personal
Click OK
Click Next
Confirm the details look correct
Click Finish

macOS¶

To import the certificate into macOS, open the .p12 file in Finder (navigate to folder and double click it).

If prompted to enter the password immediately, enter the password and macOS will place the certificate into the Login keychain.

If the Keychain Access app opens and presents the Add Certificates wizard:

Select the login keychain
Click Add
Enter the password used when creating the .p12 file

Note

When using this certificate, the OS may prompt for keychain access.

Enter the login password for this user (not the PKCS#12 archive password) and click Always Allow.

This happens in any browser which uses this certificate method.

Warning

If the Keychain Access app fails to import the archive, or claims the password is incorrect, then the PKCS#12 archive was likely created with encryption unsupported by macOS. Create a new PKCS#12 archive for macOS as noted previously.

Firefox (Any OS, version 90 and later)¶

Click the three-line menu icon (“Hamburger”)
Click Settings
Click Privacy and Security
Scroll Down to Certificates (or search)
Click the View Certificates button
Click the Your Certificates header tab
Scroll down as far as possible until the buttons are visible

Note

There may be large volume of blank area, keep scrolling down.
Click the Import button
Find and select the .p12 file
Enter the password used when creating the .p12 file
Scroll back up and inspect the new entry to ensure it looks correct
Click OK to close the Certificates window
Close the Settings tab

Clear Past Certificate Decisions¶

If in the past, the user has skipped the certificate selection when attempting to access the TNSR GUI, Firefox may have cached that decision. To reset this:

Click the three-line menu icon (“Hamburger”)
Click Settings
Click Privacy and Security
Scroll Down to Certificates (or search)
Click the View Certificates button
Click the Authentication Decisions header tab
Find the TNSR instance in the list and select it
Scroll down as far as possible until the buttons are visible

Note

There may be large volume of blank area, keep scrolling down.
Click Delete
Click OK to close the Certificates window
Close the Settings tab

Chrome (Any OS)¶

Navigate to chrome://settings/certificates/ to open the certificate settings
Click the Your Certificates header tab
Click Import
Find and select the .p12 file
Close the Settings tab

Accessing the GUI¶

Navigate to the URL of the TNSR GUI, e.g. https://198.51.100.30/

If the browser presents a warning about not trusting the server certificate, that is expected since the CA which created the RESTCONF server certificate is self-signed. Allow the browser to continue loading the page.

Firefox¶

Select the appropriate certificate when prompted by the browser.

The prompt will have a drop-down menu of available certificates. Pick the appropriate one from the list and confirm.

Chrome¶

Select the appropriate certificate when prompted by the browser. The prompt will have a list of available certificates. If multiple certificates have the same name, they may be grouped under that name.

Safari¶

Select the appropriate certificate when prompted by the browser. The prompt will have a list of available certificates.

Edge¶

Select the appropriate certificate when prompted by the browser. The prompt will have a list of available certificates.

Troubleshooting¶

JSON/Unauthorized Error¶

If a client accessing the TNSR GUI encounters a JSON error stating that the URL was unauthorized, this typically indicates that the client browser did not send a certificate, or it sent a certificate that was not signed by the CA used by the RESTCONF server (server-ca-cert-path).

{
"ietf-restconf:errors" : {
   "error": {
      "error-type": "protocol",
      "error-tag": "access-denied",
      "error-severity": "error",
      "error-message": "The requested URL was unauthorized"
   }
}

}