Documentation: Where can I find the JWT reference?

[marcusirgens]

I'm currently integrating with NATS and am trying to find a reference that describes the JWTs used throughout the system.

• There is some information on the website under the "Basics" page for the nsc tool, but it does not describe the fields on the JTWs.

• The Decentralized JWT Authentication/Authorization page links to the Nkey reference, the Ed25519 reference, the nsc tool, the "basics" page, and the "In Depth Guide":

• The In Depth Guide is over 90 000 characters of text in tutorial format, but as far as I can tell, it does not describe the "schema" used.

  As an aside, it does say this:

  The NATS JWT library on the other hand is written in Go. This may not be your language of choice.

  While Go is my language of choice, it is not what I'm currently using for this project, and I'd rather not exec the nsc binary to create JWTs.

There is some more information spread around on the website, but I am really struggling to find a definitive reference that describes the capabilities of the JWTs in a non-walkthrough format that exhaustively lists the fields that I can, should or must use to identify users, operators, accounts, etc., and I find my self trying to decipher various implementations, hoping that the struct I bumped into in one of the nats-io repositories is "the right one".

I know my experience is a single data point, but I'm frustrated by this. The NATS protocol, tooling and server technology is fascinating and appealing, but the lack of technical documentation in the form of specifications and reference documents is causing me a lot of friction.

Have I missed something? Is this documentation available somewhere, or am I simply not expected to create credentials using other tools than the nsc tool?

[siredmar]

@marcusirgens we have put a lot of effort into building a plugin for Hashicorp Vault, since we need a smart way to manage operators, accounts and users.
Take a look at our project: https://github.com/edgefarm/vault-plugin-secrets-nats
You also might want to check out the Kubernetes Operator for this Vault plugin: https://github.com/edgefarm/provider-natssecrets

Besides that, i am also missing a JWT reference in the docs.

[aricart]

@marcusirgens Yes, there are some documentation gaps that require mapping many different documentation sources across repos to provide the complete overview. As you have figured out, nkeys are the identities of the equation. The JWTs are simply the limits associated with the entities. All of these concepts cross over directly from the server configuration settings.

There's work on a new library for building and managing the entities, which offers a higher level of abstraction than JWTs (which is really just a model for communicating the configuration), https://github.com/synadia-io/jwt-auth-builder.go, but that codebase is still in the early stages.

The delegated managing of the credentials is something we still need to address. Usually the need is to manage the assignment of limits to accounts, which is usually a rather specific logic. There is planning also to address the storage of JWTs and secrets outside of nsc which will help for large scale setups.

[aricart]

BTW super awesome to have the vault integration.

[ahirner]

There's work on a new library for building and managing the entities

How will that square with managing permissions and some accounts/users declaritively?
Re: nats-io/terraform-provider-jetstream#106 (reply in thread)