NAUTH

A Kubernetes operator for managing decentralized authentication & authorization for NATS

NAuth allows platform teams to provide easy multi-tenancy support for development teams by providing Account & User CRD:s that conveniently packages:

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

Note

This project is still in early and active development. There will likely be breaking changes before getting to 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.

Pre-requisites

NAuth requires NATS to be installed in the cluster, since NAuth integrates with NATS (over NATS) to provide the account JWT:s. See examples of how to setup NATS with JWT auth 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 k8s secrets.

You can provide and resolve these secrets in three ways:

Warning

NATS_URL and the implicit label-based lookup path are deprecated and will be sunset in favor of explicit NatsClusterRef + NatsCluster resources (tracking: #102).

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.

C. (Deprecated) Use the legacy label-based lookup together with NATS_URL:

• nauth.io/secret-type: system-account-user-creds
• nauth.io/secret-type: operator-sign

You can see a full operator example setup here. For a more secrets related example on how to set up NAuth using explicit secrets lookup based on NatsClusterRef and NatsCluster resources, 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 & 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.

Import an existing NATS Account

Use this to "observe" an account that already exists in the NATS cluster. NAuth will fetch the JWT from NATS and update the account status, but it will never push a new JWT.

Required Secrets

• Account root seed secret labeled: account.nauth.io/id=$ACCOUNT_PUBKEY, nauth.io/secret-type=account-root and nauth.io/managed=true.
• Account signing seed secret labeled: account.nauth.io/id=$ACCOUNT_PUBKEY, nauth.io/secret-type=account-sign and nauth.io/managed=true.

Account CR example

apiVersion: nauth.io/v1alpha1
kind: Account
metadata:
  name: my-acc
  labels:
    account.nauth.io/id: $ACCOUNT_PUBKEY
    nauth.io/management-policy: observe        # observe-only

Note: the System Account required by NAuth itself can only be observed and reconciliation of such an Account CRD without nauth.io/management-policy: observe label will fail.

Nauth Development

Check out the CONTRIBUTING guide.

Join our Slack

We co-locate with the NATS Slack in our own channel