Skip to main content

Authentication and tokens

Encryption protects the channel; authentication establishes who is on the other end of it. When authentication is enabled, every client connection must present a valid bearer token — a signed credential the holder presents to prove identity — and every node verifies that token before serving a single operation.

Authentication is provided by the built-in security layer, the identity component embedded in the Management Service. This page covers enabling it and obtaining tokens; the model behind it (permissions, roles, scopes) is covered in Authorization and RBAC.

How it works​

A user logs in to the security layer and receives a signed JWT; the client presents it when connecting, and the node verifies the token offline against the issuer public key before accepting the connection.

  • Tokens are signed JWTs (JSON Web Tokens) issued by the security layer.
  • Nodes verify them offline against the cluster's shared public key — verification happens once per connection (at the Hello), never on the hot path, so authentication adds no per-operation network cost.
  • Tokens are self-contained: the admin embeds a role (for example DataWriter) at a store or cluster scope when issuing the token, so a node authorizes using only the public key plus the shared preset-role catalog — no policy store, no round-trip to the issuer.
  • A rejected token fails the connection with a clear reason (missing, invalid, or carrying no data-capable role for the store), not a hung socket.

Two planes to enable​

Authentication is enforced on two planes, and you turn each on separately.

  • Control plane — the Management Service. Initialize-ZrSecurity bootstraps the shared signing key and the first admin, then enforcement is on (Enable-ZrSecurity / Disable-ZrSecurity toggle it at runtime).
  • Data plane — a store's nodes. Enable-ZrStoreSecurity -Store <name> writes the shared public key into that store's node configs so the nodes verify caller tokens. It takes effect when the nodes restart; add -Restart to roll them now.

Bootstrap the control plane​

Security must already be enabled in each manager's configuration and the managers restarted; then bootstrap it. Provisioning generates the shared signing key on the first manager and fans the same key out to the rest, so every manager issues and verifies with one key. The admin token is printed once.

Initialize-ZrSecurity -AdminSubject admin -AdminPassword (Read-Host -AsSecureString)
  • Supplying -AdminPassword makes the first admin a real login user you can sign in with. Omit it for a token-only bootstrap.
  • Unless you pass -NoEnable, enforcement is turned on across all managers once the admin exists.
  • Check state any time with Get-ZrSecurityStatus (reports Enabled, Initialized, and the token Issuer).

Enable the data plane per store​

Enable-ZrStoreSecurity -Store orders -Restart

The web console does the same thing: Security & TLS → Require a token to connect (per store). In attach mode, where an orchestrator owns the nodes, the manager cannot push this change — the cmdlet reports "0 nodes updated" and the console shows the store as node-config + restart. There you declare the security block in the node config and restart; the store registration then records it. See Security and TLS.

Cluster security on ≠ your store is secured

Initialize-ZrSecurity / Enable-ZrSecurity secure only the control plane — the console and admin cmdlets. Each store's data plane stays open until you run Enable-ZrStoreSecurity (or the console's per-store toggle) on that store. Enabling TLS alone does not help: encryption is not authentication, so a TLS-only store is encrypted but still open to any client. Turn on token verification for every store that holds real data.

warning

Bootstrap and capture your admin credential before you rely on enforcement, or you can lock yourself out of your own cluster. Initialize-ZrSecurity exists precisely so the first administrator credential is in place before enforcement begins.

Authentication and TLS are independent. A common production order is: enable TLS first (so credentials never cross the wire in clear text), then bootstrap security and enable it per store.

Signing in as an operator (control plane)​

Credentials authenticate people to the control plane — the console and the admin cmdlets. This is separate from the data-plane token an application presents to a store.

  • Web console — once security is enabled, opening the console (or a fresh browser session) shows a Sign in page; enter the username and password of an identity created with New-ZrUser (or the bootstrap admin). The session is authenticated from then on.
  • AdminShell — sign in with Connect-ZrManager -Credential, which logs in against the Management Service and captures the returned session token so subsequent admin cmdlets are authenticated:
Connect-ZrManager -Managers "10.0.0.10:7801" -Credential (Get-Credential) -Force
# Logged in as 'admin'.  Add -SaveAs prod to persist it as a reusable workspace.
Get-ZrStore    # now authorized; without the login this is denied

Operators are created with New-ZrUser -Name <u> -Password (Read-Host -AsSecureString) [-Role <role> -Scope <scope>], and their password rotated with Set-ZrUserPassword. See Connect-ZrManager and New-ZrUser.

Obtaining a token​

Log in with a credential (typical)​

The client exchanges a username/password for a self-renewing token as part of connecting — you never handle the raw token. -Credential logs in against the Management Service at -ManagementUrl, captures the returned token for the session, and uses it for the data-plane connection. The password is used only for login and is not retained.

Connect-ZrStore -ConnectionString "zariss://10.0.0.10:7861/orders" `
                -Credential (Get-Credential) `
                -ManagementUrl "http://10.0.0.10:7801"

Present an existing token​

If your operator or pipeline already issued a token, present it directly in the connection string with ?token= (prefer token=env:VAR or token=file:/path to keep the secret out of the string):

Connect-ZrStore -ConnectionString "zariss://10.0.0.10:7861/orders?token=$token&ca=file:C:\certs\cluster-ca.crt"

Omit the token entirely (use a plain zaris://… or zariss://… string with no ?token=) when authentication is disabled.

Issue tokens and identities (operator)​

Operators mint credentials through the Management Service:

  • New-ZrUser -Name alice -Password (Read-Host -AsSecureString) [-Role StoreOperator -Scope zaris:store:orders] — creates a login user, optionally with a role.
  • New-ZrServiceAccount -Name orders-svc -Role DataWriter -Scope zaris:store:orders [-LifetimeMinutes N] — creates a passwordless machine identity and returns a token for an application. The token is shown once.
  • New-ZrToken -Subject app1 -Role DataWriter -Scope zaris:store:orders [-LifetimeMinutes 60] — issues a self-contained token for a subject without creating a persistent identity.

Revoke with Revoke-ZrToken -TokenId <jti> (a single token) or Revoke-ZrToken -Subject <subject> (all of a subject's tokens).

Tokens vs. certificates — why tokens?​

Clients authenticate with tokens, not client certificates, by design:

  • No per-client PKI. You don't provision and rotate a certificate for every application, script, or pod — you issue a token, which is cheap and revocable.
  • Identity, not just membership. A token carries the caller's subject and role claims, which authorization then evaluates. A client certificate would only prove "someone with a cert," not "who."
  • Node-to-node stays mutual TLS. Certificates still authenticate nodes to each other; tokens authenticate clients to nodes. Each mechanism is used where it fits.

Next steps​