Авторизация
Основы аутентификации позволили order-svc и analytics-reader доказать личность и подключиться.
Сервер знает кто, но ещё не ограничил что: order-svc пока публикует и подписывается везде.
Авторизация задаёт разрешённые действия через темы.
Права относятся к темам
Право разрешает публикацию или подписку на набор тем. Отдельных ролей администратора и типов ресурсов нет: доступ выражается темами.
Все операции проходят через темы; request/reply — публикация и подписка на ответ. Их ограничение контролирует всё достижимое клиентом.
Есть независимые списки публикаций и подписок. Разрешение одного не даёт другого.
Подстановки как в темах: * — один токен, > — один или больше конечных. orders.> включает также orders.at.northpole, в отличие от orders.*.
Ограничение order-svc
Сервис публикует orders.created/shipped/canceled и иногда делает запросы. Ответы приходят во временные _INBOX.. Значит нужны публикации orders. и собственные inbox.
Добавьте permissions к прежнему пользователю:
authorization {
users: [
{
user: order-svc
password: s3cr3t
permissions: {
publish: {
allow: ["orders.>"]
}
subscribe: {
allow: ["_INBOX.>"]
}
}
}
{user: analytics-reader, password: an4lytics}
]
}
Publish allow orders.> разрешает события заказов.
Subscribe allow _INBOX.> разрешает ответы. Префикс настраиваем, это стандарт.
У analytics-reader блока нет, пока он не ограничен.
Allow закрывает остальное
Всё вне заданного allow запрещено.
publish: { allow: ["orders.>"] } закрывает billing.charge и $JS.API.>.
Без allow и deny доступ не ограничен, как у analytics-reader.
Пустой список не запрет: publish: [] разбирается как отсутствие списка. Запретить всё — publish: { deny: [">"] }.
default_permissions внутри authorization действует только на пользователей без собственного блока. Собственные права полностью заменяют стандарт, не сливаются. См. справочник.
Ограничение включается явным allow.
Deny сильнее allow
Для исключения из широкого orders.> не нужно перечислять все остальные темы:
publish: {
allow: ["orders.>"]
deny: ["orders.secret"]
}
Сервер проверяет allow, затем deny. Совпавший запрет отменяет разрешение: orders.created/shipped доступны, orders.secret — нет.
При сочетании списков последнее слово за deny.
Наблюдение отказа
Перезапустите с конфигурацией. orders.created разрешён, billing.charge отклоняется.
- CLI
#!/bin/sh
# order-svc is restricted to publishing orders.> and subscribing _INBOX.>.
# Assumed server config (top-level authorization block):
# authorization {
# users: [
# {
# user: order-svc
# password: s3cr3t
# permissions: {
# publish: { allow: ["orders.>"] }
# subscribe: { allow: ["_INBOX.>"] }
# }
# }
# {user: analytics-reader, password: an4lytics}
# ]
# }
# This shows an allowed publish succeeding and a denied publish being rejected.
# Connect as order-svc.
export NATS_USER=order-svc
export NATS_PASSWORD=s3cr3t
# Don't send these credentials to an unexpected server which the user might
# have previously configured. This mutates user-global state!
# A real production script might instead require the existence of a specific
# context name and export NATS_CONTEXT.
nats context unselect
# Stop processing this script if an error is seen
set -e
# Allowed: orders.created is covered by the publish allow-list "orders.>".
# Expected output:
# Published 91 bytes to "orders.created"
nats pub orders.created '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Denied: billing.charge is not on the allow-list, so the server rejects it
# and drops the message. The CLI exits 1 with:
# nats: error: nats: permissions violation: Permissions Violation for Publish to "billing.charge"
nats pub billing.charge '{"order_id":"ord_8w2k","amount_cents":4200}'
echo "oops: reached end without error (so billing.charge publish unexpectedly succeeded)"
14:19:45 Published 91 bytes to "orders.created"
nats: error: nats: permissions violation: Permissions Violation for Publish to "billing.charge"
Первый pub сообщает 91 байт и код 0, второй — код 1. Сырой ответ: -ERR 'Permissions Violation for Publish to "billing.charge"'.
Ошибка асинхронна, сообщение отбрасывается, соединение остаётся. Библиотеки журналируют, передают следующей операции или вызывают обработчик ошибок.
Запрещённый request выглядит как тайм-аут: никто не получил публикацию, ответ не придёт. API JetStream тоже запросы, поэтому nats stream info может вернуть context deadline exceeded. Смотрите серверный журнал:
[ERR] 127.0.0.1:57456 - cid:6 - "v1.51.0:go:NATS CLI Version v0.4.0" - "$G/user:order-svc" - Publish Violation - Subject "billing.charge"
Там указаны пользователь, $G и тема для поиска недостающего права.
Та же модель в JWT
В децентрализованной модели списки находятся в подписанных JWT и меняются nats auth:
nats auth user edit order-svc ORDERS --pub-allow "orders.>"
Каждый флаг заменяет список целиком: передавайте полный набор. Со scoped signing keys списки пользователя пусты, права заданы областью ключа записи. Правила сервера те же.
За рамками
Ещё три вида прав:
- Ответы, allow_responses: разрешение конкретного выданного reply без широкого publish.
- Группы очередей:
"orders.created billing-workers"позволяет только подписку в указанной группе, не обычную. См. permissions. - Импорт/экспорт — связь учётных записей, не пользователя; см. Межаккаунтный обмен.
Все поля — в permissions. Здесь publish, subscribe, allow, deny.
Типичные ошибки
Четыре основные ловушки:
Subscribe deny ломает ответы. subscribe: { deny: [">"] } запрещает inbox. Добавленный allow не поможет: deny сильнее. Замените запрет на allow _INBOX.>.
- CLI
#!/bin/sh
# Broken state: order-svc's subscribe section denies everything:
# permissions: {
# publish: { allow: ["orders.>"] }
# subscribe: { deny: [">"] }
# }
# A request subscribes to a temporary _INBOX.> subject before it publishes,
# and the deny blocks that subscription, so no reply can ever arrive.
# Connect as order-svc.
export NATS_USER=order-svc
export NATS_PASSWORD=s3cr3t
# Trace commands, so you can see the below happen
set -x
# The CLI is silent about the denial: it prints only
# Sending request on "orders.lookup"
# then waits out the timeout and exits 0 — no error. The violation appears
# in the SERVER log:
# [ERR] ... "$G/user:order-svc" - Subscription Violation - Subject "_INBOX.<random>", SID 1
# (Client libraries raise a timeout error on the request instead.)
nats req orders.lookup '{"order_id":"ord_8w2k"}' --timeout 2s || echo "exited $?"
# Fix: REPLACE the subscribe section in the server config — adding an allow
# next to the deny does nothing, because deny beats allow:
# subscribe: { allow: ["_INBOX.>"] }
# Reload the server and run the same request again, with a responder
# listening on orders.lookup. Expected output:
# Sending request on "orders.lookup"
# Received with rtt 652µs
# {"order_id":"ord_8w2k","status":"shipped"}
nats req orders.lookup '{"order_id":"ord_8w2k"}' --timeout 2s || echo "exited $?"
14:20:30 Sending request on "orders.lookup"
CLI в ошибочной схеме может просто ждать и завершиться 0; журнал показывает Subscription Violation - Subject "_INBOX.<random>", SID 1. Библиотеки возвращают тайм-аут. После исправления и запуска отвечающего запрос проходит:
14:20:11 Sending request on "orders.lookup"
14:20:11 Received with rtt 652µs
{"order_id":"ord_8w2k","status":"shipped"}
Отвечающему также нужен publish в reply. Для этого предназначен allow_responses.
Пропущенная тема тоже закрыта. orders.> уже включает orders.refunded, а перечисление только created/shipped — нет. Выбирайте шаблон реального пространства пользователя.
Слишком широкий > открывает всё, включая JetStream $JS.API.>. Ограничивайте префиксом, например orders.>.
Запрет незаметен под wildcard-подпиской. При allow orders.> и deny orders.audit.> точная подписка orders.audit.entry даёт Permissions Violation for Subscription to "orders.audit.entry". Широкая orders.> принимается, но audit фильтруется без ошибки и маркера пропуска. При потерях проверяйте deny.
- CLI
#!/bin/sh
# order-svc's subscribe section allows the wildcard but denies the audit branch:
# permissions: {
# publish: { allow: ["orders.>"] }
# subscribe: { allow: ["orders.>"], deny: ["orders.audit.>"] }
# }
# A literal subscribe to a denied subject fails loudly; a wildcard subscribe
# that overlaps the deny is accepted and silently filtered.
# Connect as order-svc.
export NATS_USER=order-svc
export NATS_PASSWORD=s3cr3t
# Loud: a literal subscribe to the denied subject is rejected. The CLI
# exits 1 with:
# Subscribing on orders.audit.entry
# nats: error: nats: permissions violation: Permissions Violation for Subscription to "orders.audit.entry"
nats sub orders.audit.entry
# Silent: the wildcard subscribe is ACCEPTED — no error, and nothing in the
# server log either. Leave it running (--wait exits after 4s without
# messages) and publish to both subjects from another terminal:
# nats pub orders.created '{"order_id":"ord_8w2k","status":"created"}'
# nats pub orders.audit.entry '{"order_id":"ord_8w2k","actor":"order-svc"}'
# Only orders.created is delivered; the server drops orders.audit.entry
# at delivery time. Expected output:
# Subscribing on orders.>
# [#1] Received on "orders.created"
# {"order_id":"ord_8w2k","status":"created"}
nats sub "orders.>" --wait 4s
18:02:37 Subscribing on orders.audit.entry
nats: error: nats: permissions violation: Permissions Violation for Subscription to "orders.audit.entry"
Точная подписка завершается 1, широкая принимает только разрешённое:
18:02:45 Subscribing on orders.>
[#1] Received on "orders.created"
{"order_id":"ord_8w2k","status":"created"}
Публикация audit успешна, но доставка отфильтрована без ошибки клиента и без строки нарушения в журнале.
Что уже готово
Order-svc ограничен задачей:
- Публикация orders.>, подписка
_INBOX.>. - Остальные публикации отклоняются и теряются.
- Analytics-reader пока не ограничен; оба в $G.
Два правила одинаковы для конфигурации и JWT: allow закрывает остальное, deny сильнее allow.
Что дальше
Пользователи ещё делят пространство тем. Создадим независимые учётные записи.
Перейдите к учётным записям и изоляции.
См. также
- permissions — поля.
- default_permissions — стандартные права.
- Темы — подстановки.
- Учётные записи — независимые пространства.