Security

TLS Encryption

We encourage you to secure the communication between your connector and the client. For the underlying technology, this means that you need to provide a certificate which is then used to encrypt the transferred data. Additionally, a trusted certificate allows the client to verify the server's identity.

Self-signed Certificates

Anyone can make their own certificates without the help from a certificate authority (CA). The only difference is that certificates you make yourself won't be trusted by anyone else. For local development, that's fine.

The simplest way to generate a private key and self-signed certificate for your connector is with these commands:

$ cd connector-starter
$ uv add --optional dev cryptography
$ uv run certificate generate

$ cd connector-starter
$ hatch run uv pip install cryptography
$ hatch run certificate generate

$ cd connector-starter
$ poetry add --optional dev cryptography
$ poetry run certificate generate

The certificate generation requires the cryptography package to be present. The command reads the server's uuid and host from your project's config.json file, if it exists, to configure the generated certificate.

If you do not already have a configuration file, you can create a default "config.json" file in your working directory:

uv run config create

hatch run config create

poetry run config create

The certificate generate command will prompt whether or not you want to update your config file to activate TLS encryption. This prompt can be suppressed with the addition of the -y flag to the command.

For more information about the available options, see:

uv run certificate generate --help

hatch run certificate generate --help

poetry run certificate generate --help

Enable Encryption

To enable TLS encryption for your connector, you need to provide a certificate and its corresponding private key in the config, if you ran certificate generate with --embed or -y or you accepted updates to your configuration file, your config is already up-to-date and ready to use with the connector start command.

uv run connector start --app unitelabs.connector_starter:create_app -v

hatch run connector start --app unitelabs.connector_starter:create_app -v

poetry run connector start --app unitelabs.connector_starter:create_app -v

When using a self-signed certificate, it might be necessary to add the certificate to the client's trust store in order for it to trust your connector. Otherwise connections might be rejected. Also make sure to keep your private key safe.

For more information about the connector start CLI options, see:

uv run connector start --help

hatch run connector start --help

poetry run connector start --help