Skip to main content
Version: 3.9.0


By default, all Resoto components communicate with each other via HTTPS using Transport Layer Security (TLS).

The trust between components is established using a PSK that is used to derive a key used to sign JWTs.

Resoto Core runs a Public Key Infrastructure (PKI) including a Certificate Authority (CA). Upon start, all components will request a certificate from the CA.

Pre-Shared Key (PSK)

Each Resoto component accepts a --psk flag (which can alternatively be supplied using the environment variables RESOTOCORE_PSK, RESOTOWORKER_PSK, RESOTOMETRICS_PSK and RESOTOSHELL_PSK).

The value of the flag is a pre-shared key—a common passphrase that all components know about.

From this passphrase, a 256 bit key is derived using PKCS#5 password-based key derivation function 2 with HMAC as its pseudo-random function (PBKDF2-HMAC) and a random salt. This derived key is then used to sign JWTs.

JSON Web Token (JWT)

If a PSK is provided, every request that a component makes to Resoto Core must provide a valid Authentication header with a JWT signed using the PSK.

This is true for encrypted HTTPS and unencrypted HTTP requests, meaning that if TLS is turned off (--no-tls) but a PSK was specified, the request will still be authenticated (just not encrypted!).

Certificate Authority (CA)

By default, Resoto's built-in CA will be used.

Alternatively, a custom CA cert and key can be provided to Resoto Core using the --ca-cert and --ca-cert-key flags.

Or, if you are already running a CA or have externally signed certificates (e.g., Let's Encrypt) they can be used using the --ca-cert, --cert and --cert-key flags for all components. If the key is protected by a passphrase, --cert-key-pass can also be specified.

The following sections explain the steps Resoto automatically performs when using the built-in CA.

Establishing Trust

Resoto Core has two API endpoints, /ca/cert and /ca/sign.

The former serves the core's public CA root certificate. Upon startup, all other components will request this root certificate from Resoto Core without validating the TLS connection.

However, Resoto Core encodes the certificate's SHA256 fingerprint into a JWT which is signed with the previously mentioned PSK.

When a component downloads untrusted root certificate, it compares its fingerprint with the one the core has encoded into the JWT. If the fingerprints match the CA's root certificate is stored as a valid root certificate and from then on trusted.

Any HTTPS requests between components and Resoto Core from this point forward are validated against the CA root certificate.

Component Certificates

Once trust is established, each component requests a certificate from the CA by creating a private RSA key in memory and a Certificate Signing Request (CSR) using that key.

The CSR is then sent to /ca/sign, which returns a signed certificate.

Like any other request, this one includes a JWT signed with the PSK. This way, the CA knows it can trust the requesting component before returning a signed certificate.

Components will automatically renew certificates one day before their expiration.

Custom Certificates

Resoto Shell can be used to create custom certificates. This is useful for securing the connection to other components like ArangoDB or Prometheus.

To create a certificate, open Resoto Shell and execute:

> certificate create --common-name arangodb.local --dns-names arangodb.local localhost --ip-addresses
​Received a file arangodb.key, which is stored to ./arangodb.key.
​Received a file arangodb.crt, which is stored to ./arangodb.crt.

See certificate Command for more information.

Securing ArangoDB

  1. Create a certificate and combine the two outputted files into a single PEM file:

    $ cat arangodb.crt arangodb.key > arangodb.pem
    $ chmod 600 arangodb.pem
  2. Copy the PEM certificate file to your directory of choice and start ArangoDB using the following flags:

    --server.endpoint ssl://localhost:8530 --ssl.keyfile /path/to/arangodb.pem
  3. Set the value of resotocore's --graphdb-server startup flag to https://localhost:8530.


When interfacing with Resoto's API endpoints, it is possible to integrate with Resoto Core using the same transport encryption and authentication utilized by Resoto's components.

Retrieving and Validating the CA Certificate

The Resoto CA certificate can be retrieved at https://localhost:8900/ca/cert (replace localhost with the hostname or IP where Resoto Core is running).

In a Python 3 REPL with resotolib installed, execute the following:

>>> from import get_ca_cert
>>> from resotolib.x509 import write_cert_to_file
>>> ca_cert = get_ca_cert(resotocore_uri="https://localhost:8900", psk="changeme")
>>> write_cert_to_file(cert=ca_cert, cert_path="./resoto_ca.crt")

Alternatively, the CA cert can be retrieved without verifying it.

$ curl -k https://localhost:8900/ca/cert > resoto_ca.crt

Generating a JSON Web Token

The following will return http headers that contain a valid JWT for the provided PSK:

>>> from resotolib.jwt import encode_jwt_to_headers
>>> encode_jwt_to_headers(http_headers={}, payload={}, psk="changeme", expire_in=3600)
{'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInNhbHQiOiJuSVEzU3M5TGVNS1JHYUNQUEJxMnlBPT0ifQ.eyJleHAiOjE2NDkzNzI1MTR9.KXAmijfSsV-taO3890qJNzXKXng1u38eU6PTrDYTgVs'}

Executing Resoto CLI Commands with curl

Use the retrieved CA cert and generated http headers with curl in a shell to talk to the Resoto API:

$ auth_header="Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInNhbHQiOiJuSVEzU3M5TGVNS1JHYUNQUEJxMnlBPT0ifQ.eyJleHAiOjE2NDkzNzI1MTR9.KXAmijfSsV-taO3890qJNzXKXng1u38eU6PTrDYTgVs"
$ resoto_command="search is(resource) | count"
$ curl --cacert resoto_ca.crt -H "$auth_header" -H "Content-Type: text/plain" -H "Accept: application/json" -X POST -d "$resoto_command" https://localhost:8900/cli/execute

Disabling Security Features

Resoto installations are secure by default, but it is possible to disable some of the security features.


Disabling security features is not recommended and should only be done in a trusted environment.

Disabling Authentication

Resoto's authentication infrastructure is based on the PSK provided to Resoto Core on startup.

If a PSK is not provided, authentication is not required to access Resoto's API endpoints.

Disabling TLS

Resoto Core can be started without TLS using the --no-tls flag.


This change also needs to be reflected in the startup parameters of all other components because it affects the Resoto Core URL.

Contact Us

Have feedback or need help? Don’t be shy—we’d love to hear from you!




Some Engineering Inc.