Skip to main content

Security overview

Zaris secures a cluster with three independent layers: encryption in transit, authentication, and authorization. You enable each layer on its own, so you can start with a plaintext development cluster and add security as your requirements grow.

Each layer answers a different question.

LayerQuestion it answersMechanism
EncryptionCan anyone on the network read or tamper with traffic?Transport Layer Security (TLS) on the data plane and the control plane.
AuthenticationWho is this caller?Signed bearer tokens, issued by the security layer and verified offline by each node.
AuthorizationIs this caller allowed to do this, here?Role-based access control (RBAC), deny-by-default.

The layers build on each other. Encryption protects the pipe, authentication establishes an identity over that pipe, and authorization decides what that identity may do. A development cluster can run with all three off. A production cluster typically runs with all three on.

A caller's connection passes through three independent layers — TLS encryption, token authentication verified offline, and RBAC authorization — before being accepted or rejected.

Two planes, two kinds of key​

Before the layers, one distinction makes everything else fall into place: Zaris has two planes, and they authenticate differently because they serve different callers.

PlaneWho uses itHow they actHow they authenticate
Control planePeople and operatorsThe web console and the admin cmdlets (Clustron.Zaris.AdminShell) — creating stores, changing config, reading security statusCredentials — a username and password. You sign in once; the login is exchanged for a session token.
Data planeApplications and servicesYour app connecting to a store to read and write keysA token — passwordless and self-contained, scoped to a store and role. Drop it into an environment variable or a Kubernetes secret.

The rule of thumb: credentials are for people, tokens are for apps. An operator signs in with a password (Connect-ZrManager -Credential, or the console sign-in page); an application presents a token (Connect-ZrStore -Token, or a token in its connection string). A convenience login for apps also exists — Connect-ZrStore -Credential exchanges a username/password for a data-plane token at connect — but the mental model to keep is people→password, app→token.

Console and cmdlets are at parity

Almost every action in this section can be done in the web console or with an equivalent AdminShell cmdlet — the console talks to the cluster through the same control-plane management API the CLI uses. Each step below shows both paths; pick whichever fits your workflow.

Encryption with TLS​

TLS is the protocol that encrypts a network connection and lets one side prove its identity to the other with a certificate. Zaris applies TLS to two separate planes, which you enable and reason about independently.

The data plane carries store traffic — between clients and nodes, and between nodes themselves.

  • Client to node uses server-authenticated TLS. The client validates each node's certificate against the cluster certificate authority (CA). A CA is the entity whose certificate signs — and so vouches for — the node certificates. The client itself is then identified by its token, not by a client certificate.
  • Node to node uses mutual TLS (mTLS) when the store's TLS Mode is MutualTls. In mutual TLS, each side presents a certificate and validates its peer's, so only enrolled members join the data plane. MutualTls is the mode Zaris applies by default when you enable TLS on a store.

The control plane is the Management Service and Web Console HTTPS. It is separate from data-plane TLS and is enabled independently with Enable-ZrManagementHttps. You can secure the console without encrypting store traffic, or the reverse.

note

"Mutual TLS" in Zaris refers to node-to-node authentication. External clients do not present a client certificate. They authenticate with a token over a server-authenticated TLS channel. This is the standard, scalable pattern: you issue a token per client instead of provisioning a certificate per client.

The mechanics of enabling TLS, and how each node obtains its certificate, are covered in TLS encryption.

Trust: where certificates come from​

The hard part of TLS is not encryption. It is trust — which CA signs the node certificates, and how clients come to trust that CA. A trust anchor is the certificate a client is configured to trust as the root of validation; every node certificate must chain back to it.

Zaris supports four trust models so you can align the cluster with your organization's existing public-key infrastructure (PKI) instead of working around it. All four produce the same end state — nodes present certificates that peers and clients validate against a trust anchor — but they differ in who holds the CA private key and whether Clustron signs the node certificates.

ModeWho holds the CA private keyClustron signs node certificatesTrust anchor distributed to clients
Auto-generated (Mode 0)The cluster generates a self-signed CAYesThe generated cluster CA (cluster-ca.crt)
Bring-your-own CA (Mode 1)You, and you give the CA key to the clusterYesYour CA root
Bring-your-own intermediate (Mode 2)You; you give only an intermediate to the clusterYesYour enterprise root
Pre-issued leaves (Mode 3)You; the key is never given to the clusterNoYour root, configured as a trust anchor

Choosing between them, and the exact configuration for each, is the subject of CA and trust modes. If you want a secure cluster with the least effort, use the default, Auto-generated: the cluster mints its own CA, issues each node a certificate automatically, and you distribute one public file to clients.

Authentication with tokens​

When authentication is enabled, every client connection presents a bearer token at the connection handshake (the "Hello"). A bearer token is a signed credential the holder presents to prove identity. The token is a signed JSON Web Token (JWT) issued by the security layer, the identity component embedded in the Management Service. Nodes verify the token offline against the issuer's public key. There is no per-request call to a central auth server on the hot path — verification happens once per connection.

An operator signs in to the control plane with a credential (Connect-ZrManager -Credential, or the console sign-in page). An application gets its data-plane token either by logging in with a credential at connect (Connect-ZrStore -Credential, which exchanges a username and password for a token) or — the usual pattern — by having an operator issue one ahead of time (New-ZrToken, New-ZrServiceAccount) and dropping it into a secret. See Authentication and tokens.

Authorization with RBAC​

Authentication establishes who. Authorization decides what. Zaris delegates authorization to the security layer, which evaluates a role-based model that is deny-by-default — an operation is refused unless a role granted to the caller explicitly permits it at the relevant scope.

  • Operations map to permissions such as data.read, data.write, and control-plane permissions like store.create.
  • Permissions are granted through roles (for example DataReader, DataWriter, ClusterAdmin) bound to a principal at a scope — for example, one store versus the whole cluster.
  • Scopes are hierarchical strings (zaris:cluster, zaris:store:orders). A grant at a higher scope covers the scopes beneath it.

See Authorization and RBAC for the permission catalog, the preset roles, and how to grant them.

How the layers map to deployment​

Zaris runs in two deployment models, and each lends itself to different trust modes.

  • Supervisor model — the Management Service creates and owns the nodes. Each node enrolls: it generates its keypair locally and sends a certificate-signing request (CSR) to the manager, gated by a one-time token. This is the natural home for the Auto-generated, BYO-CA, and BYO-intermediate modes, where Clustron does the signing.
  • Attach model — an external orchestrator (for example Docker Compose or Kubernetes) runs the nodes, and the manager only observes. Certificates are mounted into each node. This is the natural home for the Pre-issued leaves mode.

You are not locked in — the modes are configuration — but these pairings are the paths of least resistance. Deployment specifics are in the Deployment section.

Enabling security: the short version​

A fully secured supervisor-model cluster is a handful of steps. Note the shape: you secure the control plane once, then secure the data plane on each store.

# 1. CONTROL PLANE — bootstrap security and create the first admin login (username + password).
#    Enforcement turns on across all managers; the console and admin cmdlets now require sign-in.
Initialize-ZrSecurity -AdminSubject admin -AdminPassword (Read-Host -AsSecureString)

# 2. DATA PLANE — require a token to connect to the store, and encrypt its traffic. Per store.
Enable-ZrStoreSecurity -Store orders -Restart   # nodes now verify caller tokens
Enable-ZrStoreTls      -Store orders -Restart   # MutualTls node-to-node; clients use CA + token

# 3. Issue a token for an application (passwordless, scoped to the store and a data role).
New-ZrToken -Subject orders-app -Role DataWriter -Scope zaris:store:orders

# 4. Export the public cluster CA for clients (optional — clients can auto-fetch it at sign-in).
Get-ZrClusterCaCert -OutFile cluster-ca.crt

# 5. The application connects over TLS, presenting its token.
Connect-ZrStore -ConnectionString "zariss://10.0.0.10:7861/orders?token=env:ORDERS_TOKEN&ca=file:cluster-ca.crt"
Cluster security on ≠ your store is secured

Steps 1 secures only the control plane — the console and admin cmdlets. Until you run Enable-ZrStoreSecurity on a store (step 2), that store's data plane stays open: an application can still connect and read every key with no token. Likewise, enabling TLS alone gives you an encrypted but unauthenticated store — encryption is not authentication. Secure every store you care about: token first, then TLS.

Every step above has a web console equivalent too — the Security & TLS area enables cluster security, per-store token requirement, and per-store TLS, and mints tokens on the People/Applications tabs. For the full click-by-click and cmdlet walkthrough, see Secure a store end to end. Each concept is explained in depth in the pages that follow.

Next steps​