Authentication

Configure client authentication for NATS Server

Authentication Overview

NATS Server supports multiple authentication mechanisms to verify client identities. You can choose the method that best fits your security requirements and infrastructure.

Authentication Methods

NATS provides four primary authentication methods:

1. Token-based authentication - Simple shared secret
2. Username/password authentication - Traditional credentials
3. NKeys authentication - Cryptographic public-key authentication
4. JWT-based authentication - Decentralized authentication with claims

Token-Based Authentication

The simplest authentication method using a shared secret token.

Server Configuration

authorization {
  token: "secret_token_here"
}

Or via command line:

nats-server --auth secret_token_here

Client Connection

nats-cli pub test "hello" --server="nats://secret_token_here@localhost:4222"

Token authentication is suitable for development but should not be used in production. Prefer NKeys or JWT authentication.

Username/Password Authentication

Traditional username and password credentials.

Single User

authorization {
  user: "admin"
  password: "$2a$11$W2zko4z4nZC5z6o7FPNbO.4qGOsQWiPCqQ3O0kJLKLQP5WtHLx4KW"
}

Or via command line:

nats-server --user admin --pass secret_password

Multiple Users

authorization {
  users = [
    {
      user: "alice"
      password: "$2a$11$..."
    }
    {
      user: "bob"
      password: "$2a$11$..."
      permissions: {
        publish: ["events.>"]
        subscribe: ["results.bob.>"]
      }
    }
  ]
}

Password Hashing with BCrypt

Never store plaintext passwords. Use bcrypt hashing:

# Generate bcrypt hash
nats server passwd
Enter password: ****
Reenter password: ****
$2a$11$W2zko4z4nZC5z6o7FPNbO.4qGOsQWiPCqQ3O0kJLKLQP5WtHLx4KW

The server warns if plaintext passwords are detected in the configuration.

Connection Deadlines

Expire user credentials after a specific time:

authorization {
  users = [
    {
      user: "temporary"
      password: "$2a$11$..."
      connection_deadline: "2026-12-31T23:59:59Z"
    }
  ]
}

NKeys Authentication

Cryptographic authentication using Ed25519 public-key signatures. This is the recommended authentication method.

How NKeys Work

1. Server generates a random nonce
2. Client signs the nonce with its private NKey
3. Server verifies the signature using the public NKey
4. No passwords transmitted over the network

Generating NKeys

# Generate a user NKey
nats-server -k user

Output:

User public key: UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ
User private key: SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY

Store the private key securely. Never commit it to version control.

Server Configuration

Single NKey User

authorization {
  users = [
    {nkey: "UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ"}
  ]
}

Multiple NKey Users

authorization {
  users = [
    {
      nkey: "UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ"
      permissions: {
        publish: ["orders.>"]
        subscribe: ["results.>"]
      }
    }
    {
      nkey: "UDIBRYX7D2S2IXMOV4ABWSH5TJCF5YLQT3V7KTKSW5MBTXNBD7WKEWXY"
      permissions: {
        publish: ["events.>"]
        subscribe: ["_INBOX.>"]
      }
    }
  ]
}

With Account Assignment

accounts {
  ORDERS: {
    users: [
      {nkey: "UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ"}
    ]
  }
}

Client Configuration

Clients use a credentials file containing the NKey:

user.creds:

-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ...
------END NATS USER JWT------

************************* IMPORTANT *************************
NKEY Seed printed below can be used to sign and prove identity.
NKEYs are sensitive and should be treated as secrets.

-----BEGIN USER NKEY SEED-----
SUACSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY
------END USER NKEY SEED------

*************************************************************

Connect using credentials:

nats-cli pub test "hello" --creds=user.creds

JWT-Based Authentication

JWT (JSON Web Token) authentication enables decentralized auth with signed claims. This is the most sophisticated authentication method.

Operator Mode

Operator mode uses a hierarchical trust model:

Operator (root trust)
  └── Account (signed by operator)
       └── User (signed by account)

Server Configuration

operator: "/path/to/operator.jwt"

resolver: {
  type: full
  dir: "/path/to/jwt/accounts"
}

Account JWT Example

Account JWTs define account-level claims:

{
  "jti": "ACCOUNT_ID",
  "iat": 1234567890,
  "iss": "OPERATOR_KEY",
  "name": "Production",
  "sub": "AAAA...",
  "nats": {
    "limits": {
      "conn": 1000,
      "subs": -1,
      "payload": 1048576,
      "data": -1
    },
    "default_permissions": {
      "pub": {},
      "sub": {}
    }
  }
}

User JWT Example

User JWTs define user-level claims and permissions:

{
  "jti": "USER_ID",
  "iat": 1234567890,
  "iss": "ACCOUNT_KEY",
  "name": "Alice",
  "sub": "UCKA...",
  "nats": {
    "pub": {
      "allow": ["orders.>"]
    },
    "sub": {
      "allow": ["results.>", "_INBOX.>"]
    },
    "subs": -1,
    "data": -1,
    "payload": -1
  }
}

Dynamic Updates

JWT authentication supports dynamic updates without server restarts:

1. Update account or user JWT in the resolver
2. Server automatically picks up changes
3. Active connections continue with old credentials
4. New connections use updated credentials

Account Signing Keys

Accounts can delegate user signing to scoped keys:

accounts {
  PROD: {
    signing_keys: [
      "ADKXVKMR3VF7JXJK7H3KVZJFG7WR7SWZ7GBFZ6U5D4NBJQABTQUWZDJM"
    ]
  }
}

Authentication Callouts

Authentication can be delegated to an external service via the callout mechanism.

Server Configuration

accounts {
  AUTH: {
    users: [{nkey: "AUTH_SERVICE_NKEY"}]
  }
}

authorization {
  auth_callout: {
    issuer: "AUTH_ACCOUNT_KEY"
    account: "AUTH"
    auth_users: ["AUTH_SERVICE_NKEY"]
  }
}

Callout Flow

1. Client connects to server
2. Server publishes authentication request to $SYS.REQ.USER.AUTH
3. Auth service validates credentials
4. Auth service responds with signed User JWT
5. Server grants access based on JWT claims

Encrypted Callouts

Callout requests and responses can be encrypted:

authorization {
  auth_callout: {
    issuer: "ACCOUNT_KEY"
    account: "AUTH"
    xkey: "XABC..."  # XKey for encryption
  }
}

TLS Certificate Mapping

Map TLS certificate properties to users:

tls {
  cert_file: "server.pem"
  key_file: "server-key.pem"
  ca_file: "ca.pem"
  verify: true
  map_and_verify: true
}

authorization {
  users = [
    {
      user: "CN=alice,O=Company"
      permissions: {
        publish: ["orders.>"]
      }
    }
  ]
}

Authentication Timeouts

Clients must authenticate within the timeout:

authorization {
  timeout: 2.0  # seconds
}

Or via command line:

nats-server --auth_timeout 2

Related Topics

• Security Overview
• Authorization & Permissions
• TLS Configuration