We are hiring! Apply here
Authentication and Authorization

When the user logs in, the client downloads a profile and extracts the user identification from the client certificate issued by the server. The authorization is driven by simple RBAC (role-based access control), which can be extended for other more advanced authorization schemes in the future.

Cluster setup TLS

Fluvio cluster must have TLS enabled for the authorization mechanism to kick in. With TLS enabled, both SC and SPU will ensure all subsequent traffic to and from the client is encrypted via mTLS. As part of TLS configuration, the cluster administrator must also define an authorization policy file (described below).

To create a Fluvio cluster with TLS enabled, you must provide the following certs and keys:

  • CA cert
  • Client cert and key
  • Server cert and key
  • Authorization policy file

For development and testing, you can use self-signed certs and keys. For production, you should use certs and keys signed by a trusted CA. It is important to note that the client cert and key must be signed by the same CA as the server cert and key. Otherwise, the client will not be able to connect to the server. In addition, the system admin must specify domain name (DNS) that cluster is bound to. This is required for TLS to work properly.


Self signed certs

For self-signed certs, you can use sample certs templates in fluvio.


Authorization policy file

Fluvio currently implements a simple type level permission model. The authorization policy file is a JSON file that contains a list of permission entries for the role. Each entry contains a type and a list of permissions. Tye type can be one of the following object types. Current list of types are:

  • CustomSpu
  • Spu
  • Topic
  • Partition
  • SpuGroup
  • SmartModule
  • TableFormat

Each object type can have one or following permissions:

  • All
  • Read
  • Write

The All permission means the user has all permissions for the object type. For example, following is a policy file. It contains a two roles: Root and User. The Root role has all permissions for all object types. The TopicUser role only has read permission for Topic object type.

    "Root": {
        "CustomSpu": [
        "Partition": [
        "Spu": [
        "Topic": [
        "SpuGroup": [
        "ManagedConnector": [
        "SmartModule": [
        "TableFormat": [
    "TopicUser": {
        "Topic": [


Note that, In order to set up and operator cluster as an adminstrator, “Root” role with full access to all objects is required.


Authorization Scope file

The scope file contains mapping of users to roles. For example, here is a sample scope file that maps user user1 and user2 to TopicUser role. The Root role is mapped to user root.

    "Root": [
    "TopicUser": [

The user id comes from the X509 client certs. It is mapped to CN. For example, this is a simple command to generate a client cert with CN set to user1.

openssl req -new -key <client_key> -out <client.csr> -subj "/C=US/ST=CA/O=MyOrg, Inc./CN=user1"

The client cert with CN set to user1 can be used to connect to Fluvio cluster. The Fluvio cluster will map the user1 to TopicUser role.


Provisioning Fluvio cluster with TLS

Once all the certs and keys are ready, you can provision a Fluvio cluster with TLS enabled. Note that client certs must have user “root” (default policy mapping) in order to provision the cluster. Here is syntax to provision a Fluvio cluster with TLS enabled.

fluvio cluster start --tls --domain <domain> --ca-cert ca_cert --server-cert <server_cert> --server-key <server_key> --client-cert <client_cert> --client-key <client_key> --authorization-policy <policy_file> --authorization-scope <scope_file>

The domain must match DNS suffice in order to TLS to work properly. For example, if you are using self-signed certs, you can use local or localhost as domain. If you are using certs signed by a trusted CA, you can use the domain name that is registered with the CA.

Connecting to Fluvio cluster with TLS

In order to connect to Fluvio cluster with TLS enabled, you must provide client certs and keys. They must be signed by the same CA as the server cert and key. In addition, it must have CN(user) that is in the authorization scope file. The client TLS certs and key can be either provided in the fluvio profile file or specified in the env variables. Here is an section of fluvio profile file that contains client certs and keys. Currently TLS certs must be manually copied to config file.

domain = "fluvio-cluster.mydomain.com"
key = """