Skip to main content
Star us on GitHub Star

Console Deployment

Installation​

Install the Package​

The package installs the console files in /opt/openziti/share/console.

Install the console package
sudo apt install openziti-console

Or, configure the package repository and install with this one-liner.

Configure the package repository and install openziti-console
curl -sS https://get.openziti.io/install.bash | sudo bash -s openziti-console

Install from GitHub​

Console versions >= 3.0.0 from GitHub may be used.

  1. Download a release.

    wget https://github.com/openziti/ziti-console/releases/latest/download/ziti-console.zip

  2. Unzip in a directory that is mounted the controller's filesystem namespace.

    sudo mkdir -p /opt/openziti/share/console
    sudo unzip -d /opt/openziti/share/console ./ziti-console.zip

Configuration​

  1. In /var/lib/ziti-controller/config.yml, ensure you have an API binding zac on the same web listener where edge-management is bound. Ensure the location matches the path to the console files.

    - binding: zac
      options:
        location: /opt/openziti/share/console
        indexFile: index.html

  2. Restart the controller service if you edited the configuration.

    sudo systemctl restart ziti-controller.service

  3. Visit the controller's web address in a browser to access the console.

    https://ctrl.ziti.example.com:1280/zac/

  4. Console certificate option - The console is served from the controller's API and can be used with the default API certificate. The controller can be configured to present a different certificate for the console when the API is accessed by a distinct URL for the console. For more information about using alternative server certs with the controller, see: the configuration reference for the identity property.

Authenticate with an Admin Client Certificate​

  1. Enroll an admin identity. Link to instructions

  2. Unwrap the JSON file to obtain the certificate and private key.

    ziti ops unwrap admin2.json

  3. Compose a keystore from the certificate and private key. The -legacy flag is necessary when importing the keystore into some versions of macOS Keychain Access.

    openssl pkcs12 -export -in admin2.cert -inkey admin2.key -out admin2.p12 -name "admin2" -legacy -password 'pass:mypassword'

  4. Import the keystore:

    • macOS: Import into System Keychain via Keychain Access application for Google Chrome. You can run a terminal command or double-click the keystore file or drag it onto the login keychain to import it.

      security import admin2.p12 -k ~/Library/Keychains/login.keychain -T /Applications/Google\ Chrome.app -P 'mypass'

    • Windows: Import into the Windows Certificate Store (Personal store) via certmgr.msc.

    • Linux: Import into your browser's certificate store or system certificate store (e.g., Chrome Settings > Privacy and Security > Security > Manage certificates).

  5. Visit the console in your web browser. The browser will prompt with a list of imported client certificates. Select the one you imported in the previous step.

  6. Press the "LOGIN" button without entering a password.

Using Public Certificates​

It is possible to remove certificate based security warnings.

By default, the OpenZiti Controller is configured with a certificate issued by its self-signed PKI. Unless you've specifically added this certificate to all your web browsers, this will result in modern browsers showing a warning when accessing the console UI.

Although not strictly a security issue, it's convenient to use certificates from a widely trusted CA such as Let's Encrypt, ZeroSSL, etc. Using a certificate from a widely trusted CA will very likely ensure any console user does not receive this warning.

Assuming you are serving the console from the controller, you can configure the OpenZiti Controller to serve an alternate server certificate using the alt_server_certs configuration stanza.

Steps​

  1. Create and validate your certificates (for example with Let's Encrypt Certbot)
  2. Alter the controller configuration using example below as a guide
  3. Restart the ziti-controller service

See the example configuration here:

web:
  - name: client-management
    identity:
      ...
      alt_server_certs:
      - server_cert: "/etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/fullchain.pem"
        server_key:  "/etc/letsencrypt/live/<YOUR_DOMAIN_NAME>/privkey.pem"

At this point, the controller service should use the certificates for the ZAC, removing any "Potential Security Risk" warnings.

note

See The Console and Alternative Server Certificates for more details on how to use public certificates within your enviromment.