Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Where can I find the JWT reference? #199

Open
marcusirgens opened this issue May 6, 2023 · 4 comments
Open

Documentation: Where can I find the JWT reference? #199

marcusirgens opened this issue May 6, 2023 · 4 comments

Comments

@marcusirgens
Copy link

marcusirgens commented May 6, 2023

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
Copy link

siredmar commented Dec 7, 2023

@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
Copy link
Member

aricart commented Dec 18, 2023

@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
Copy link
Member

aricart commented Dec 18, 2023

BTW super awesome to have the vault integration.

@ahirner
Copy link

ahirner commented Dec 18, 2023

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants