Choose one term and use it consistently: JWT or OAuth 2.0

[cjcenizal]

This is important for folks who are trying to decide between API Keys and JWT. We can help them find the information they need if we can consistently frame it as either a choice between "API Keys vs JWTs" or "API Keys vs OAuth" but if we surface both of these in the UI it sounds like there are more than two options for folks who aren't familiar with JWT and OAuth.

[forrestbao]

I second this.

[amin2718]

The more correct term is OAuth 2.0. JWT is more of an implementation detail, and OAuth 2.0 is not backward compatible with 1.0, hence why it would be better to share the version.

[eskibars]

+1 to being consistent, but I don't know that I agree if there's a more/less correct term here, and I think we would be remiss to use "either" JWT "or" OAuth 2.0.

OAuth 2.0 is a pretty complicated spec, with many different "flows" and within each flow, many different mechanisms/schemas of authentication. Technically, it's entirely possible to use some OAuth 2.0 flows with Basic authentication, for example. And it's entirely possible (and not all that uncommon) to use JWTs without OAuth at all.

The additional detail of calling out using JWTs within OAuth is useful, because for someone with the technical knowledge, JWTs are themselves decomposable. For example, if you take the following JWT that was issued by Vectara:

eyJraWQiOiJiNWJjWllpNExLdjhtNVV3aUIxSUdvS3lJQkcxYXU1eFpxWlNoR2IybnhRPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI4NWFhYzgyZC1mZTVlLTQ2ZmQtOWZmZi04Y2EwZGNkNGZiNDQiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfcERCbm8wcXF4IiwiY29nbml0bzp1c2VybmFtZSI6InNoYW5lQGVza2liYXJzLmNvbSIsIm9yaWdpbl9qdGkiOiJkMmY0NDY5Zi0xOTViLTQ4NGYtYTJlYi0xYTkzMDM0MDhhYzQiLCJhdWQiOiIzbzZidmxxa3RiMDI1aWgxaWoxNXRuc3RyZSIsImV2ZW50X2lkIjoiYmU5YzZjZGEtODdmYi00OTZiLTlhMmMtOTI0MWFkMzAwNjNjIiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE2OTA4MjYwNDksImV4cCI6MTY5MTQzODg2MSwiaWF0IjoxNjkxNDM1MjYxLCJqdGkiOiIwYzAwZWM1ZC04NWViLTQ1OGQtYTgwNy1hZDRhMDFjMjdjODYiLCJlbWFpbCI6InNoYW5lQGVza2liYXJzLmNvbSJ9.Mu7E9qjbM1VFWOmP1Csx-C9o6bpSN2f6OMQ13zxBCBP0x3VbA36mKJz7fWBAfsazXWA3vms1a7kr3Gswxhy-UB7kCP7aa4sc_0vO4hPvBI1VneQdfz77Vv5ThHta2FjgYFok11OKJLXWNdXBfWMDeaV4oQg9McwBzzcMXde7EyC5M5ASp14EALCUiNWdrLo5FKITF-R6XMWxMUvmvv6nxHnAQY3bWvAf5JvRuPhaPv7bIblfpC2LOzw5WuPkRKzKAi-i5I6DTOZpTq_ftU1DGfW2R6vNVmKkIZTH-4_fNn-NHlDdMVqzXUooA-p9B7EudATqhiXwf5Rvg4-2tidqFA

And you plug it into a tool like https://jwt.io/, you can find the issuer, the expiration time, the auth time, what username it was associated with, etc. This is, of course, because JWTs are structured and you can inspect the internals of them. It's common in an enterprise context to get requests to be able to verify the signature of JWTs with e.g. a public key and to be provided with the details of the expected inner structure.

So to me, the right path forward is to call out that we use OAuth 2.0 with a client_credentials grant, and that we use JWT "Bearer" tokens in the implementation. That's obviously a ton of information to try to stuff into the sidebar, so I'd recommend that we consciously be inconsistent between the sidebar and the content, but be consistent within any sidebars and be detailed within any content.

[forrestbao]

Maybe just "Bearer token"? It is widely used in many web APIs and users are very clear on its meaning.

[eskibars]

The problem with "Bearer token" is the same as using "OAuth 2.0". It's not inaccurate but it's not detailed enough for enterprises. A bearer token doesn't need to be in JWT form: a bearer token could be a random hex string (not terribly uncommon). JWT is more (useful) detail because it describes to a user how to parse it.

It's also entirely possible to use a Bearer token without OAuth at all

[amin2718]

Hi Shane, it sounds like you've thought this through pretty thoroughly. Everything you've written sounds fine.

to call out that we use OAuth 2.0 with a client_credentials grant, and that we use JWT "Bearer" tokens in the implementation

We can mention client_credentials grant, but we should avoid the suggestion that the platform limits customers to the client_credentials grant. Our API also supports Authorization Code Grants (wherein authentication is delegated to a third-party service like Google, a company's Okta instance, etc.), which we've taken advantage of for demos in the past, and I expect more customers will take advantage of in the future.

I know we recently removed the ability to create these directly from our console UI.

[cjcenizal]

So to me, the right path forward is to call out that we use OAuth 2.0 with a client_credentials grant, and that we use JWT "Bearer" tokens in the implementation. That's obviously a ton of information to try to stuff into the sidebar, so I'd recommend that we consciously be inconsistent between the sidebar and the content, but be consistent within any sidebars and be detailed within any content.

We currently have a page that describes OAuth 2.0, client credentials grant, and JWT tokens in detail: https://docs.vectara.com/docs/learn/authentication/oauth-2. How about for any page that focuses on JWT, we cross-link to this page with a "Learn about how JWT auth works" link? This way we can use consistent terminology in the side nav and in the content, and we won't need to try stuffing all the info into the sidebar.

FWIW, I think consistency between side nav and content is also natural in the case of most pages. In the example from the issue description, the page is titled "JWTFetch.cs" and its sibling pages all have titles that are similarly JWT-themed: https://docs.vectara.com/docs/getting-started-samples/JWTFetcher.cs. It makes sense for the parent section title to reflect this theme.