Skip to main content

Connecting a secured client

Once a store has TLS and authentication enabled, a client must do two things when it connects: validate the node certificates against the cluster CA, and present a token. Zaris makes this a one-liner in the common case, while still supporting strict pinning when you need it.

The common case — one command​

For a cluster secured with the default (auto-generated CA), a client connects over TLS and logs in in a single call. When you sign in with -Credential/-ManagementUrl, the CA is fetched and cached from the Management Service automatically, so you don't have to distribute a file.

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

What happens:

  1. The zariss:// scheme turns on encryption; the client validates each node's certificate.
  2. With no ca= in the connection string, the client auto-fetches the cluster CA from -ManagementUrl (the public /security/tls/ca-root endpoint) and caches it per manager.
  3. -Credential logs in and captures a self-renewing token for the session.
  4. Subsequent operations run over the encrypted, authenticated connection.
note

CA auto-fetch relies on -ManagementUrl, which is only available on the -Credential sign-in path. If you connect with a pre-issued token in the string (?token=…) instead, supply the CA yourself with ?ca=file:/path/ca.pem (see below).

Pinning the CA explicitly​

In higher-assurance environments you may want to pin the CA rather than trust it on first fetch. Export the CA once, verify its thumbprint out-of-band, and pass it to the client.

# On an operator machine — export the public CA and read its thumbprint to verify:
Get-ZrClusterCaCert -OutFile cluster-ca.crt

# On the client — pin the exact CA:
Connect-ZrStore -ConnectionString "zariss://10.0.0.10:7861/orders?token=$token&ca=file:C:\certs\cluster-ca.crt"

The ca=file:… option accepts a path to cluster-ca.crt (you can also pass it out of band with -TlsCaCert, which additionally accepts the PEM contents inline). When your cluster uses your corporate CA (Modes 1–2), clients that already trust your root need nothing extra.

Using an existing token​

When a token was issued to a service or pipeline out-of-band, 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. Because a token supplied this way does not use -ManagementUrl, the CA cannot be auto-fetched — supply it with ?ca=file:… (or rely on the OS trust store when the cluster uses your corporate CA).

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

Testing without verification (development only)​

To connect to a self-signed cluster during development without setting up trust, you can bypass certificate validation:

Connect-ZrStore -ConnectionString "zariss://127.0.0.1:7861/orders?tlsInsecure=true"
warning

tlsInsecure=true disables certificate validation — it defeats the protection TLS provides against man-in-the-middle attacks. Use it only against a local development cluster, never in production.

Troubleshooting​

Zaris fails fast on secured-connection problems, so you rarely have to guess.

SymptomCauseFix
Connect fails immediately with a CA-fetch or CA-missing errorNo CA supplied and none could be auto-fetchedPass -TlsCaCert, or connect with -Credential/-ManagementUrl so the CA is fetched, or -TlsInsecureSkipVerify to test
Server certificate does not validateWrong CA pinned, or a CA swap happenedSupply the correct -TlsCaCert, or re-export it with Get-ZrClusterCaCert
Connection rejected as unauthorizedMissing, expired, or non-data-capable tokenRe-authenticate with -Credential, or present a token carrying DataReader/DataWriter/ClusterAdmin for the store
Connect hangs then times outReaching a plaintext port with -Tls, or a firewallCheck the endpoint/port and that the store actually has TLS enabled

A wrong-CA connection is designed to fail with an explanatory message rather than hang — if a secured connect stalls, suspect the endpoint or a firewall, not trust.

Checklist​

  • The zariss:// scheme in the connection string (TLS on).
  • CA available — auto-fetched via -Credential/-ManagementUrl, or pinned via ?ca=file:….
  • A token — via -Credential login or an explicit ?token=… in the string.
  • Endpoints in the string point at the store's client ports.

That is the whole client contract for a secured cluster.

Next steps​