nauth

NAuth

A Kubernetes operator for managing decentralized authentication and authorization for NATS

NAuth allows platform teams to provide easy multi-tenancy support for development teams by providing Account and User CRDs that package:

• Account creation and updates
• Account exports and imports
• User creation and credentials delivery

[!NOTE] This project is still in early and active development. Expect breaking changes before a stable release.

Installation

NAuth supports installation through packaged Helm charts.

helm install nauth oci://ghcr.io/wirelesscar/nauth --create-namespace --namespace nauth

A nauth-crds chart is also available for installing CRDs separately, which works alongside the main chart with crds.install=false.

Prerequisites

NAuth requires NATS to be installed in the cluster, since NAuth integrates with NATS to provide account JWT data. See examples of how to set up NATS with JWT authentication together with NAuth in the examples directory.

NAuth requires the system account user credentials and the operator signing key NKey seed to be provided as Kubernetes Secrets.

NAuth resolves these credentials through a NatsCluster. Choose one of these reference patterns:

A. For single-cluster deployments, set NATS_CLUSTER_REF on the NAuth controller (namespace/name, for example nats/my-nats-cluster) and define the secrets in that referenced NatsCluster (spec.operatorSigningKeySecretRef and spec.systemAccountUserCredsSecretRef).

• Default behavior (NATS_CLUSTER_REF_OPTIONAL=false) is strict mode: account-level spec.natsClusterRef must match NATS_CLUSTER_REF.
• NATS_CLUSTER_REF_OPTIONAL=true is explicit opt-in default mode: accounts without spec.natsClusterRef use NATS_CLUSTER_REF, while accounts may override with their own ref.
• Recommended migration to per-account explicit refs:
  1. Set NATS_CLUSTER_REF with NATS_CLUSTER_REF_OPTIONAL=false.
  2. Add the same spec.natsClusterRef to all existing Account resources.
  3. Remove NATS_CLUSTER_REF and rely on explicit spec.natsClusterRef in each Account.

B. Define an explicit spec.natsClusterRef reference in each Account CR to a specific NatsCluster.

For an example that defines a NatsCluster, explicit spec.natsClusterRef, and the required credential Secret references, see the cluster reference scenario.

Getting started

Running a large NATS cluster requires that the operator is secured properly. If you do not already have an operator, try out the operator-bootstrap utility which comes with NAuth.

You can also use nsc directly to create a throw-away operator and system account.

More on decentralized JWT Auth

Check out this video for a comprehensive description on how decentralized JWT Auth works. In order to work with NAuth, it's important to have an understanding of how the basics work.

Observe existing NATS accounts

NAuth can observe an existing NATS account without taking ownership of its JWT. Use this when migrating accounts into NAuth or recovering desired state from an existing cluster.

See the observe existing accounts guide for the required Secret labels and Account resource example.

Contributing

Contributions are welcome. Open an issue for bugs, ideas, or larger changes, and read the CONTRIBUTING guide for local setup and PR guidance.

Community

NAuth discussions happen in the project Slack channel