Signing Keys
As previously discussed, NKEYs are identities, and if someone gets a hold of an account or operator nkey they can do everything you can do as you.
NATS has strategies to let you deal with scenarios where your private keys escape out in the wild.
The first and most important line of defense is Signing Keys. Signing Keys allow you have multiple NKEY identities of the same kind (Operator or Account) that have the same degree of trust as the standard Issuer nkey.
The concept behind the signing key is that you can issue a JWT for an operator or an account that lists multiple nkeys. Typically the issuer will match the Subject of the entity issuing the JWT. With SigningKeys, a JWT is considered valid if it is signed by the Subject of the Issuer or one of its signing keys. This enables guarding the private key of the Operator or Account more closely while allowing Accounts, Users or Activation Tokens be signed using alternate private keys.
If an issue should arise where somehow a signing key escapes into the wild, you would remove the compromised signing key from the entity, add a new one, and reissue the entity. When a JWT is validated, if the signing key is missing, the operation is rejected. You are also on the hook to re-issue all JWTs (accounts, users, activation tokens) that were signed with the compromised signing key.
This is effectively a large hammer. You can mitigate the process a bit by having a larger number of signing keys and then rotating the signing keys to get a distribution you can easily handle in case of a compromise. In a future release, we’ll have a revocation process were you can invalidate a single JWT by its unique JWT ID (JTI). For now a sledge hammer you have.
With greater security process, there’s greater complexity. With that said, nsc doesn’t track public or private signing keys. As these are only identities that when in use presume a manual use. That means that you the user will have to track and manage your private keys more closely.
Let’s get a feel for the workflow. We are going to:
Create an operator with a signing key
Create an account with a signing key
The account will be signed using the operator’s signing key
Create an user with the account’s signing key
All signing key operations revolve around the global nsc flag -K or --private-key. Whenever you want to modify an entity, you have to supply the parent key so that the JWT is signed. Normally this happens automatically but in the case of signing keys, you’ll have to supply the flag by hand.
Creating the operator:
To add a signing key we have to first generate one with nsc:
On a production environment private keys should be saved to a file and always referenced from the secured file.
Now we are going to edit the operator by adding a signing key with the --sk flag providing the generated operator public key (the one starting with O):
Check our handy work:
Now let’s create an account called A and sign it with the generated operator private signing key. To sign it with the key specify the -K flag and the private key or a path to the private key:
Let’s generate an account signing key, again we use nk:
Let’s add the signing key to the account, and remember to sign the account with the operator signing key:
Let's take a look at the account
We can see that the signing key ADUQTJD4TF4O6LTTHCKDKSHKGBN2NECCHHMWFREPKNO6MPA7ZETFEEF7 was added to the account. Also the issuer is the operator signing key (specified by the -K).
Now let’s create a user and sign it with the account signing key starting with ADUQTJD4TF4O.
Check the user
As expected, the issuer is now the signing key we generated earlier. To map the user to the actual account, an Issuer Account field was added to the JWT that identifies the public key of account A.
Scoped Signing Keys
Scoped Signing Keys simplify user permission management. Previously if you wanted to limit the permissions of users, you had to specify permissions on a per-user basis. With scoped signing keys, you associate a signing key with a set of permissions. This configuration lives on the account JWT and is managed with the nsc edit signing-key command. You can add as many scoped signing keys as necessary.
To issue a user with a set of permissions, simply sign the user with the signing key having the permission set you want. The user configuration must not have any permissions assigned to it.
On connect, the nats-server will assign the permissions associated with that signing key to the user. If you update the permissions associated with a signing key, the server will immediately update permissions for users signed with that key.
Generate the signing key
Add a service to the account
Since the signing key has a unique role name within an account, it can be subsequently used for easier referencing.
To see the permissions for the user enter nsc describe user - you will see in the report that the user is scoped, and has the permissions listed. You can inspect and modify the scoped permissions with nsc edit signing-key - pushing updates to the account will reassign user permissions.
Template functions
Available as of NATS 2.9.0
Although scoped signing keys are very useful and improve security, by limiting the scope of a particular signing key, the permissions that are set may be too rigid in multi-user setups. For example, given two users pam and joe, we may want to allow them to subscribe to their own namespaced subject in order to service requests, e.g. pam.> and joe.>. The permission structure is the same between these users, but they differ in the concrete subjects which are further scoped to some property about that user.
Template functions can be used to declare the structure within a scope signing key, but utilize basic templating so that each user that is created with the signing key has user-specific subjects.
The following template functions will expand when a user is created.
{{name()}}- expands to the name of the user, e.g.pam{{subject()}}- expands to the user public nkey value of the user, e.g.UAC...{{account-name()}}- expands to the signing account name, e.g.sales{{account-subject()}}- expands to the account public nkey value, e.g.AXU...{{tag(key)}}- expandskey:valuetags associated with the signing key
For example, given a scoped signing key with a templated --allow-sub subject:
We can create two users in different teams.
The resulting --allow-sub permission per user would be expanded to:
and
Last updated