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:

  • 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!

See also

This process is covered in RESTCONF Service Setup with Certificate-Based Authentication and NACM but the user portion is copied here for easy reference.

To generate a new certificate for r1-myuser:

tnsr(config)# pki private-key r1-myuser generate key-length 4096
tnsr(config)# pki signing-request settings clear
tnsr(config)# pki signing-request set common-name r1-myuser
tnsr(config)# pki signing-request set digest sha256
tnsr(config)# pki signing-request r1-myuser generate
tnsr(config)# pki signing-request r1-myuser sign ca-name r1-selfca days-valid 365 digest sha512 purpose client

Warning

The names in these certificates must also be members of a group with appropriate access in NACM. See RESTCONF Service Setup with Certificate-Based Authentication and NACM for details. NACM uses the certificate common name to determine user access.

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 archive 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"
   }
}

}