Skip to content
Nauth

Getting Started

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

Installation

Section titled “Installation”

NAuth supports installation through packaged Helm charts.

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

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

Prerequisites

Section titled “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 these credentials as Kubernetes Secrets:

Since v0.6.0: NAuth resolves NATS connection and credential references through the NatsCluster resource.

Define a NatsCluster resource with either spec.url or spec.urlFrom, plus spec.operatorSigningKeySecretRef and spec.systemAccountUserCredsSecretRef.

Then choose how accounts target that cluster:

  • For single-cluster deployments, configure the controller with NATS_CLUSTER_REF (namespace/name). With the Helm chart, set nats.clusterRef.name and optionally nats.clusterRef.namespace.
  • For multi-cluster deployments, set spec.natsClusterRef on each Account.

By default, an operator-level NATS_CLUSTER_REF is strict: account-level refs must match it. Set NATS_CLUSTER_REF_OPTIONAL=true when accounts without spec.natsClusterRef should use the operator cluster by default while still allowing explicit overrides.

Operator setup

Section titled “Operator setup”

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 to create your own operator
  • review the examples, which contain a static operator and corresponding NATS configuration

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

Manage accounts and users

Section titled “Manage accounts and users”

Since v0.1.0: Account and User resources are the core NAuth workflow.

NAuth’s main workflow is to declare NATS accounts and users as Kubernetes resources. The controller creates the NATS account JWT, keeps it updated from Account.spec, and creates user credentials for each User.

Create an account:

apiVersion: nauth.io/v1alpha1
kind: Account
metadata:
  name: example-account
  namespace: my-team
spec:
  natsClusterRef:
    namespace: nats
    name: my-nats-cluster
  accountLimits:
    conn: 100
    imports: 10
    exports: 10
  natsLimits:
    subs: 100

Create a user for that account:

apiVersion: nauth.io/v1alpha1
kind: User
metadata:
  name: example-user
  namespace: my-team
spec:
  accountName: example-account
  permissions:
    pub:
      allow:
        - foo.>
    sub:
      allow:
        - foo.>

NAuth writes the resulting user credentials to a Kubernetes Secret named <user>-nats-user-creds in the same namespace. For the full API surface, see the API reference.

Already have NATS accounts you do not want NAuth to manage yet? Use observe mode to read existing account claims into status before migrating them into spec.

More on decentralized JWT Auth

Section titled “More on decentralized JWT Auth”

It is recommended to have an understanding of how decentralized authentication and authorization for NATS works before using NAuth. Hands-on manifests are available in the examples directory, including account, user, import/export, and cluster reference scenarios.

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.

Play