Received onprint, the above example shows no message flow between user
aassociated with account
B. Messages are delivered only within the same account. That is, unless you explicitly define it.
nats-server -c <filename>) In order to make any changes, every participating nats-server config file in the same security domain has to change. This configuration is typically controlled by one organization or the administrator.
Ufor various types.
Sstands for seed. The remainder is the same as in public keys.
-Vtracing, you can see the signature in the
CONNECTmessage (formatting added manually).
INFOmessage (formatting added manually). Since
telnetwill not authenticate, the server closes the connection after hitting the authorization timeout.
nats-serverdoes not read this value. The referenced NKEY's role determines the JWT content.
nats-serveris configured to trust an operator. Meaning, the Operator JWT is part of its server configuration and requires a restart or
nats-server --signal reloadonce changed. It is also configured with a way to obtain account JWT in one of three ways (explained below).
nats-server. The clients also possess the private NKEY corresponding to the JWT identity, so that they can prove their identity as described above.
nats-serverthen independently obtains the current Account JWT from its configured source. The server can then verify that signature on the User JWT was issued by an NKEY of the claimed Account, and in turn that the Account has an issuer of the Operator and that an NKEY of the Operator signed the Account JWT. The entire three-level hierarchy is verified.
mem-resolver, except you do not have to modify server config if accounts are added/changed.
nats-resolver: Same as
url-resolver, just uses NATS instead of http
nats-account-server. Will eventually converge on the union of all account JWTs known to every participating
nats-serverto exclusively write into.
nats-resolveris the clear recommendation.
iat) time of signing. This time is in seconds since Unix epoch. It is also used to determine which of two JWTs for the same subject is more recent. Furthermore JWT documents have an issuer, this may be an (identity) NKEY or a dedicated signing NKEY of an item one level above it in the trust hierarchy. A key is a signing key if it is listed as such in the JWT (above). Signing NKEYs adhere to same NKEY roles and are additional keys that unlike identity NKEY may change over time. In the hierarchy, signing keys can only be used to sign JWT for the role right below them. User JWTs have no signing keys for this reason. To modify one role's set of signing keys, the identity NKEY needs to be used.
jwt.sig = sign(hash(jwt.header+jwt.body), private-key(jwt.issuer))(jwt.issuer is part of jwt.body) If a JWT is valid, the JWT above it is validated as well. If all of them are valid, the chain of trust between them is tested top down as follows:
CONNECTmessage (formatting added manually), containing a JWT and signed nonce. (output copied from
sign(jwt.sig, jwt.issuer) == hash(jwt.header+jwt.body)(issuer is part of body)
sign(jwt.sig, jwt.issuer) == hash(jwt.header+jwt.body)(issuer is part of body).
user.credswere to contain a JWT where the maximum message payload is limited to 5 bytes
nscenvironments, explained later):
nats-serverto check if the exporting account gave explicit consent.
nats-server --signal reloadto re-read all configured account JWTs.
nats-resolverlisten on a dedicated update subject of the system account and applied if the file is valid.
nats-resolverwill also also update the corresponding JWT file and compensate in case the update message was not received due to temporary disconnect.
nats-serveroffers (administrative) services and monitoring events.
nsccli to generate and manage operator/accounts/user. Even if you intend to primarily generate your Accounts/User programmatically, in all likelihood, you won't do so for an operator or all accounts. Key Management and how to do so using
nscwill also be part of this section.
-iis provided. When used, referencing accounts/keys is easier.
nsc envwill show where NKEYS/JWT are stored and what current defaults are. For testing you may want to switch between nsc environments: Changing the (JWT) store directory:
nsc env --store <different folder>Changing the (NKEY) store directory by having an environment variable set:
export NKEYS_PATH=<different folder>
nats-serverdoes not read them at all. Because names do not relate to identity, they may collide. Therefore, when using
nsc, these names need to be keep unique.
nsc add operator -n <operator-name> --sysThe command
nsc edit operator [flags]can subsequently be used to modify the operator. For example if you are setting the account server url (used by
nscdoes not require them being specified on subsequent commands.
nsc edit operator --account-jwt-server-url "nats://localhost:4222"
-o) and store it in the key directory (
--store) The output will display the public portion of the signing key, use that to assign it to the operator (
nsc generate nkey -o --storefollowed by
nsc edit operator --sk OB742OV63OE2U55Z7UZHUB2DUVGQHRA5QVR4RZU6NXNOKBKJGKF6WRTZ. To pick the operator signing key for account generation, provide the
-ioption when doing so.
nats-serveroffers system services as will be explained below in the system-account section. To access these services a user with credentials for the system account is needed. Unless this user is restricted with appropriate permissions, this user is essentially the admin user. They are created like any other user.
--sk generatewill create an NKEY on the fly and assign it as signing NKEY.
nsc describe operator --rawand store the output in a file named
operator.jwt. The option
--rawcauses the raw JWT to be emitted.
nsc add operator -u operator.jwt
--forceoption during the last step. This will overwrite the stored operator JWT.
nsc generate nkey -o --storein this environment instead 2. Exchange the public key with the Administrator/Operator via a way that assures you sent the public key and not someone elses. 3. Perform
nsc edit operator --skin the operator environment 4. Refresh the operator JWT in this environment by performing the import steps using
nsc describe account -n SYS --rawand store the output in a file named
SYS.jwt. The option
-nspecifies the (system) account named
SYS. 2. Exchange the file. 3. Import the account
nsc import account --file SYS.jwt4. Perform
nsc generate nkey -u --storein this environment 5. Exchange the public key printed by the command with the Administrator/Operator via a way that assures you sent the public key and not someone elses. 6. Create a system account user named (
-n) any way you like (here named
sys-non-op) providing (
-k) the exchanged public key
nsc add user -a SYS -n sys-non-op -k UDJKPL7H6QY4KP4LISNHENU6Z434G6RLDEXL2C64YZXDABNCEOAZ4YY2in the operator environment. (
-areferences the Account
SYS.) 7. If desired edit the user 8. Export the user
nsc describe user -a SYS -n sys-non-op --rawfrom the operator environment and store it in a file named
-nreferences the user
sys-non-op) 9. Exchange the file 10. Import the user in this environment using
nsc import user --file sys.jwt
--storeto avoid unnecessary key copies. Then the public/private signing NKEYS are exchanged together with the system account user as creds file. A creds file can be generated with
nsc generate creds -a SYS -n sys-non-opand imported into this environment with
nsc import user --file sys.jwt. If the signing key is generated before the operator is imported into this environment, operator update falls away.
nsc add account -n <account name> -iIn case you have multiple operator signing keys
-iwill prompt you to select one.
nsc edit account [flags]can subsequently be used to modify the account. (Edit is also applicable to the system account)
-a) and store it in the key directory maintained by nsc (
--store) The output will display the public portion of the signing key, use that to assign it to the account (
nsc generate nkey -a --store
nsc edit account --sk ACW2QC262CIQUX4ACGOOS5XLKSZ2BY2QFBAAOF3VOP7AWAVI37E2OQZXTo pick the signing key for user generation, provide the
-ioption when doing so.
nsc describe account -n <account name> --raw. Store the output in a file named
import.jwt. 2. Exchange the file with the Administrator/Operator via a way that assures it is your JWT and not someone elses. 3. In the operator environment import the account with
nsc import account --file import.jwt. This step also re-signs the JWT so that it is no longer self-signed. 4. The Administrator/operator can now modify the account with
nsc edit account [flags]
--forceoption during the last step. This will overwrite the stored account JWT.
nats-resolver: Every environment with a system account user that has permissions to send properly signed account JWT as requests to:
$SYS.REQ.CLAIMS.UPDATEcan upload and update all accounts. Currently,
nsc pushuses this subject.
$SYS.REQ.ACCOUNT.*.CLAIMS.UPDATEcan upload and update specific accounts.
nsc generate config <resolver-type>as a utility that generates the relevant NATS config. Where
--nats-resolverfor the corresponding resolver. Typically the generated output is stored in a file that is then included by the NATS config. Every server within the same authentication domain needs to be configured with this configuration.
nats-serverthat responds will be listed. In case you get fewer responses than you have servers or a server reports an error, it is best practice to resolve this issue and retry. The NATS resolver will gossip missing JWTs in an eventually consistent way. Servers without a copy will perform a lookup from servers that do. If during an initial push only one server responds there is a window where this server goes down or worse, loses its disk. During that time the pushed account is not available to the network at large. Because of this, it is important to make sure that initially, more servers respond than what you are comfortable with losing in such a way at once.