> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nats-io/nats-server/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```hocon theme={null}
authorization {
  token: "secret_token_here"
}
```

Or via command line:

```bash theme={null}
nats-server --auth secret_token_here
```

### Client Connection

```bash theme={null}
nats-cli pub test "hello" --server="nats://secret_token_here@localhost:4222"
```

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

## Username/Password Authentication

Traditional username and password credentials.

### Single User

```hocon theme={null}
authorization {
  user: "admin"
  password: "$2a$11$W2zko4z4nZC5z6o7FPNbO.4qGOsQWiPCqQ3O0kJLKLQP5WtHLx4KW"
}
```

Or via command line:

```bash theme={null}
nats-server --user admin --pass secret_password
```

### Multiple Users

```hocon theme={null}
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:

```bash theme={null}
# Generate bcrypt hash
nats server passwd
Enter password: ****
Reenter password: ****
$2a$11$W2zko4z4nZC5z6o7FPNbO.4qGOsQWiPCqQ3O0kJLKLQP5WtHLx4KW
```

<Tip>
  The server warns if plaintext passwords are detected in the configuration.
</Tip>

### Connection Deadlines

Expire user credentials after a specific time:

```hocon theme={null}
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

```bash theme={null}
# Generate a user NKey
nats-server -k user
```

Output:

```
User public key: UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ
User private key: SUACSSL3UAHUDXKFSNVUZRF5UHPMWZ6BFDTJ7M6USDXIEDNPPQYYYCU3VY
```

<Warning>
  Store the private key securely. Never commit it to version control.
</Warning>

### Server Configuration

#### Single NKey User

```hocon theme={null}
authorization {
  users = [
    {nkey: "UCKASD5KPQQYHB6KYD7RC62VZQN7VRU5NN2BKL7UFBQ3UBYAJQPVNHSQ"}
  ]
}
```

#### Multiple NKey Users

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

#### With Account Assignment

```hocon theme={null}
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:

```bash theme={null}
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

```hocon theme={null}
operator: "/path/to/operator.jwt"

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

### Account JWT Example

Account JWTs define account-level claims:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```hocon theme={null}
accounts {
  PROD: {
    signing_keys: [
      "ADKXVKMR3VF7JXJK7H3KVZJFG7WR7SWZ7GBFZ6U5D4NBJQABTQUWZDJM"
    ]
  }
}
```

## Authentication Callouts

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

### Server Configuration

```hocon theme={null}
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:

```hocon theme={null}
authorization {
  auth_callout: {
    issuer: "ACCOUNT_KEY"
    account: "AUTH"
    xkey: "XABC..."  # XKey for encryption
  }
}
```

## TLS Certificate Mapping

Map TLS certificate properties to users:

```hocon theme={null}
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:

```hocon theme={null}
authorization {
  timeout: 2.0  # seconds
}
```

Or via command line:

```bash theme={null}
nats-server --auth_timeout 2
```

## Related Topics

* [Security Overview](/operations/security)
* [Authorization & Permissions](/operations/authorization)
* [TLS Configuration](/operations/tls)