Основы аутентификации
Сервер без защиты допускает всех, кто достигает порта. Добавим первый список пользователей.
Аутентификация связывает соединение с пользователем. Простейший способ — список в конфигурации сервера.
Централизованная аутентификация
Полный список хранится в nats.conf.
Сервер сравнивает предъявленные данные со списком и не обращается к внешнему сервису.
Это удобно небольшой редко меняющейся группе пользователей, когда конфигурацией владеет одна команда.
Include может временно облегчить рост, разнеся данные по файлам. Считайте это отсрочкой перехода от централизованной модели.
Данные входа order-svc
Платформе нужны order-svc и analytics-reader.
Они задаются в users блока authorization, имя — user, далее данные входа:
authorization {
users: [
{ user: order-svc, password: s3cr3t }
{ user: analytics-reader, password: an4lytics }
]
}
Пара user/password order-svc / s3cr3t определяет пользователя. Оба пока в $G; учётные записи разделят их позже.
Для одного пользователя можно задать user/password прямо в authorization без массива.
timeout ограничивает аутентификацию, стандарт — две секунды. Числа означают секунды, длительности требуют кавычек (timeout: "500ms"; голое 1m разбирается числом). Поля — в справочнике.
Запустите:
nats-server -c nats.conf
-c задаёт файл. Теперь order-svc может войти.
Подключение order-svc
CLI передаёт два флага, библиотека — поля вызова connect. Опубликуем прежний заказ в orders.created:
- CLI
#!/bin/bash
# Connect as the centralized user `order-svc` and publish the canonical
# order message to orders.created.
#
# --user / --password send the credentials at connect time. The server
# matches them against its config user list and accepts the publish.
# Wrong credentials are rejected at connect time, before any publish,
# with: nats: error: nats: Authorization Violation
nats pub orders.created \
--user order-svc \
--password "s3cr3t" \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Expected output:
# 14:18:38 Published 91 bytes to "orders.created"
14:18:38 Published 91 bytes to "orders.created"
Данные совпали, сервер принял 91 байт. Неверный пароль отклоняется ещё до публикации:
nats pub orders.created "test" --user order-svc --password wrong
nats: error: nats: Authorization Violation
Без данных возникает та же Authorization Violation, как при неизвестном пользователе. Ответ не раскрывает, какая часть неверна.
Аутентификация выполняется при установлении соединения и определяет его пользователя. Разрешённые действия — отдельная Авторизация.
При прозрачном переподключении новый канал проходит проверку снова.
Другие данные входа
Конфигурация поддерживает user/password, NKey и token; модель та же.
User/password сравнивает отправленный пароль с сохранённым.
NKey хранит только открытый ключ вместо пары user/password; смешение запрещено. Клиент подписывает одноразовый запрос закрытым seed, не передавая секрет:
users: [
{ nkey: UAPZQH4MNJCOVEJFERB3NFSIROQ5RE7CGBEPKAZSB6QB7IQHBKXHZPVP }
]
Создайте пару, внесите открытый ключ и подключитесь с seed:
- CLI
#!/bin/sh
# Generate a user nkey and authenticate with it. The server config
# holds only the public key; the private seed stays with the client.
# Generate the keypair. The private seed goes to user.nk and nothing
# is printed; `show` prints the matching public key for the config.
nats auth nkey gen user --output user.nk
nats auth nkey show user.nk
# UAPZQH4MNJCOVEJFERB3NFSIROQ5RE7CGBEPKAZSB6QB7IQHBKXHZPVP
# Put that public key in the server's user list:
# authorization { users: [ { nkey: UAPZQH4MNJCOVEJFERB3NFSIROQ5RE7CGBEPKAZSB6QB7IQHBKXHZPVP } ] }
# Connect with the seed file. The client signs the server's nonce with
# the seed, so the secret never crosses the wire. A seed the server
# doesn't know fails with: nats: error: nats: Authorization Violation
nats pub orders.created \
--nkey user.nk \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Expected output:
# 18:02:29 Published 91 bytes to "orders.created"
UAPZQH4MNJCOVEJFERB3NFSIROQ5RE7CGBEPKAZSB6QB7IQHBKXHZPVP
18:02:29 Published 91 bytes to "orders.created"
nats auth nkey gen пишет seed в user.nk без вывода, show печатает открытый ключ, pub использует seed. Неизвестный ключ даёт Authorization Violation. Подробнее — в Децентрализованной аутентификации.
Token — общий секрет без имени, задаваемый верхним authorization { token: "shared-secret-rotate-me" }. Не бывает отдельным для пользователя, действует на сервер и подходит простым внутренним схемам. В главе token означает это, не JWT.
CLI --user означает также токен: без password отправляется как token и может скрыть неверную настройку.
Хранение паролей
Открытый пароль допустим учебному ноутбуку, но не доступной другим конфигурации.
При запуске сервер сам предупреждает:
[WRN] Plaintext passwords detected, use nkeys or bcrypt
Храните bcrypt вместо пароля: клиент всё ещё отправляет исходное значение, сервер сравнивает с односторонним хешем. Утечка файла не раскрывает готовый пароль.
Создайте хеш. Начальный пробел может исключить строку из истории некоторых оболочек; вообще будьте осторожны с секретами во флагах:
nats server passwd --pass "s3cr3t-rotate-me-later"
$2a$11$4I9tIK1JVbttZYtn.F.Jse5iY5ves4EtYWIpjlwyvgVYHJc8yTvk.
Без pass ввод интерактивен; generate создаёт сильную фразу, cost увеличивает стандартную стоимость 11. Меньше десяти символов отклоняется с password should be at least 10 characters long, поэтому пример использует s3cr3t-rotate-me-later.
Префикс $2a$11$ означает bcrypt Go со стоимостью 11. Другие варианты распознаются ради совместимости, но не полагайтесь на них. Остальное сравнивается открыто; строки с $ зарезервированы под хеши, не начинайте ими обычный пароль.
Вставьте хеш вместо пароля; кавычки необязательны. Конечная точка, если есть, входит в значение:
authorization {
users: [
{ user: order-svc, password: "$2a$11$4I9tIK1JVbttZYtn.F.Jse5iY5ves4EtYWIpjlwyvgVYHJc8yTvk." }
{ user: analytics-reader, password: an4lytics }
]
}
Клиент использует s3cr3t-rotate-me-later, из которого получен хеш. После хеширования всех записей предупреждение исчезает. Далее для читаемости снова короткий s3cr3t.
Token тоже может содержать bcrypt-хеш, при этом клиент отправляет исходный токен.
Bcrypt защищает файл, не передачу открытого секрета. Нужен TLS.
За рамками
mTLS может отображать сертификат прямо в пользователя; это часть Шифрования и TLS.
При динамических пользователях и множестве арендаторов централизованный файл неудобен. Режим оператора решает масштабирование.
Типичные ошибки
При конфигурационных данных входа:
Отсутствие аутентификации. Без authorization порт открыт всем. Добавьте пользователей и проверяйте отказ nats: error: nats: Authorization Violation. no_auth_user может допустить анонимных как именованного пользователя даже со списком: включайте осознанно, см. Учётные записи.
Открытые пароли. Не игнорируйте Plaintext passwords detected, use nkeys or bcrypt. Используйте хеш nats server passwd.
Секреты в git. Пароль и даже хеш в конфигурации — секрет. После попадания в историю нужна ротация. Используйте окружение или хранилище секретов, реальный файл исключите через .gitignore.
Пароль в URL. nats://order-svc:s3cr3t@localhost:4222 попадает в историю, список процессов и журналы. Сохраните именованный контекст, передавая "$NATS_PASSWORD", затем используйте имя:
- CLI
#!/bin/sh
# Keep order-svc's credential out of the connection URL (and out of shell
# history and server logs) by storing it in a named context.
#
# A URL like nats://order-svc:s3cr3t@localhost:4222 leaks the password
# into every log line and your shell history. A context holds the
# credential separately and is selected by name.
# Save the credential once, in a named context.
# Beware that this does still expose the secret to process listings,
# which may affect systems with untrusted users, but only does so once
# (at context creation, not at context use).
# The assignment to the variable will still appear in shell history!
# (Some shells can be configured to skip recording lines which start
# with whitespace).
NATS_PASSWORD='s3cr3t'
nats context add orders \
--server localhost:4222 \
--user order-svc \
--password "$NATS_PASSWORD" \
--description "ORDERS platform, order-svc user"
# Unset the variable once the context is saved.
unset NATS_PASSWORD
# Make it the active context.
nats context select orders
# Now connect with no credential on the command line at all. The publish
# uses the stored credential from the `orders` context.
nats pub orders.created \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Expected output:
# 14:19:37 Published 91 bytes to "orders.created"
14:19:37 Published 91 bytes to "orders.created"
Контекст хранит пароль. Экспортированный NATS_PASSWORD вызывает WARNING: Shell environment overrides in place using NATS_PASSWORD; не экспортируйте или удалите после сохранения.
Оболочка Unix подставляет реальный пароль до запуска команды, поэтому другие пользователи всё ещё могут увидеть аргумент процесса. Окружение современных Unix обычно другим не раскрывается.
Что уже готово
Есть:
- Сервер с nats-server -c nats.conf.
- Два пользователя authorization в $G и знание bcrypt.
- Проверка успешного заказа и отказа неверному паролю.
Что дальше
Личность order-svc известна, но действия пока не ограничены. Добавим права.
Перейдите к Авторизации.
См. также
- authorization — поля и timeout.
- Авторизация — действия пользователя.
- Основные понятия → Безопасность — краткий обзор.