Skip to content

Set up certificates and tokens

Trust the initial browser certificate before signing in. Use the remaining sections when you replace a certificate or configure monitoring.

Before you start

  • For Settings changes, sign in as the administrator. See Sign in for the first time.
  • The certificate and key for the browser address, or a private authority's root certificate.

Default browser identity

The default browser identity is generated and stored encrypted in tls/console-fallback.pem.age, and reused on restart. Separate Docker hosts and Kubernetes mount their own.

A browser warns about it the first time. Add it to each client's trust store after you check it through a channel you already trust, or install your own certificate. The certificate must cover every DNS name or IP address operators use. If an address changes, replace the certificate unless it already covers the new address.

On one Docker host, export only the public certificate through an authenticated host connection. Run from the repository root:

docker compose -f server/docker-compose.yml exec -T iris \
  openssl x509 -in /run/iris/tls/console-fallback.pem -outform PEM \
  > console-ca.pem
openssl x509 -in console-ca.pem -noout -sha256 -fingerprint

Use console-ca.pem in the operator trust store or as --cafile for tools/api-exercise.py. For separate hosts or Kubernetes, obtain the public certificate from the Console TLS bundle or its issuing authority instead. Never copy the combined runtime PEM: it also contains the private key.

Warning

Never disable TLS verification.

Install your own Console certificate

  1. Open Settings → TLS & trust.
  2. Upload the certificate and its private key. Leaf-only or full chain both work.
  3. Check the result. If the certificate was saved but reload was not confirmed, restart that Console. With several Console instances, restart the others too.
  4. Open a new trusted connection to each Console and verify its served certificate.

Uploading a certificate changes the saved override, but reload reaches only the Console that handled the request. A saved result alone does not prove a listener is using the replacement.

Install a root certificate authority

  1. Open Settings → TLS & trust.
  2. Paste or upload the certificate. It must be an X.509 certificate; one upload becomes one trust entry.
  3. Confirm the entry appears in the list.

Turn on the public bundle download

  1. Open Settings → TLS & trust.
  2. Set the download URL, starting with https://. Default: Cisco's Trusted Root Store, https://www.cisco.com/security/pki/trs/ios.p7b.
  3. Turn on automatic download. The server checks every 24 hours.
  4. Start a download and watch the job finish. Accepted: PEM, base64, a PKCS#7 bundle, and signed wrappers.

Create the scrape token

Do this only if a Prometheus server or collector scrapes the metrics listener. Create the token on the server host and give the scraper the same value as its credentials_file:

umask 077
mkdir -p ~/.config/iris
openssl rand -hex 32 > ~/.config/iris/observability-token
export IRIS_OBSERVABILITY_TOKEN_FILE_HOST=$HOME/.config/iris/observability-token
sudo chown 10001 "$IRIS_OBSERVABILITY_TOKEN_FILE_HOST"
printf 'IRIS_OBSERVABILITY_TOKEN_FILE_HOST=%s\n' \
  "$IRIS_OBSERVABILITY_TOKEN_FILE_HOST" >> server/.env

Both containers run as user and group 10001; the chown lets them read the file. Recreate the server container to pick up the mount; see Send telemetry to Splunk. For rotation, see Rotate credentials and certificates.

How the management credential is handled

The Console's management credential is compared against the current and previous values in constant time before route lookup or body buffering. It never appears in an environment value, URL, process argument, exception, or audit entry.

Credential files on Kubernetes

The same material arrives as Secrets, created before you apply the manifests. Install on Kubernetes has the commands. Create both current files, and the two previous files empty.

File Secret Format
current and previous iris-tier-auth Raw token or scoped JSON management record
current and previous iris-observability-auth The raw token value
headers iris-otlp-headers Comma-separated Name=Value headers
tls.crt and tls.key iris-console-tls The browser certificate
tls.crt and tls.key iris-management-tls The management certificate, with service names as subject alternative names

Verify

  • The Console settings view lists the certificate, the trust entries, and the download settings.
  • The Console loads with no warning from a client that trusts your authority, and keeps that certificate after a restart. A scrape with the token succeeds; one without it is refused.

Next steps