API tokens do not need to be JWT's

[ItalyPaleAle]

Fixes #2329

[msfussell]

This is a good update. However there are a couple more things to cover;

1. Can you also add the same clarity to the reverse, Dapr to App calls in this topic?http://localhost:1313/operations/security/app-api-token/ for the JWT token

2. This update also made me think that in some SDKs, they set the API_TOKEN on each call on your behalf (for example in the .NET SDK) and I believe these are read via the DAPR_API_TOKEN token for the SDK (and the reverse APP_API_TOKEN). Worth confirming this and then adding this Into the clients section of these docs, so that people using the SDKs know that this is taken care of. Need to check which SDK do this and for those that do not, we need to raise issue to track this work.

3. Q: In the SDKs, in the methods called by Dapr to app (for example subscribe endpoint), do they enforce the APP_API_TOKEN?

[ItalyPaleAle]

Thanks for the review @msfussell .

I have updated the app-api-token page too as per your point 1.

As per the other two points, looking into the SDKs it seems that only the Go and PHP SDKs today implement those behaviors automatically. There's an open issue in the .NET one: dapr/dotnet-sdk#835

[msfussell]

The dotnet issue that you reference above should really be addressed and all the SDKs should honor the env variables values both ways.

[ItalyPaleAle]

I agree with you on that. We should involve the maintainers of each SDK in that, however.

In the meanwhile, do you think this PR can be merged? Even without the SDK updates (which can take months), I don't think it's necessary to block these changes.

[msfussell]

@ItalyPaleAle These are all good changes and yes we can take the docs. My only feedback is that it is possible to use a JWT as well as random byte sequence, and in fact we even show this in these diagrams here. https://dapr.io/. So I would still keep an edit version of the JWT text below, saying this is another approach.

Note, while Dapr itself is actually not the JWT token issuer in this implementation, being explicit about the use of JWT standard enables federated implementations in the future (e.g. OAuth2).

To configure API authentication, start by generating your token using any JWT token compatible tool (e.g. https://jwt.io/) and your secret.

Note, that secret is only necessary to generate the token, and Dapr doesn't need to know about or store it

[ItalyPaleAle]

The proposed docs say:

Dapr uses shared tokens for API authentication. You are free to define the API token to use.

Although the example uses a random string, any sequence of characters would work, including a JWT: Dapr treats them as opaque tokens. However, I'm wary of explicitly mentioning JWTs because they're a confusing topic to a lot of people and I am concerned that mentioning them could cause more confusion with regards to Dapr.

[github-actions]

Stale PR, paging all reviewers

[msfussell]

The proposed docs say:

Dapr uses shared tokens for API authentication. You are free to define the API token to use.

Although the example uses a random string, any sequence of characters would work, including a JWT: Dapr treats them as opaque tokens. However, I'm wary of explicitly mentioning JWTs because they're a confusing topic to a lot of people and I am concerned that mentioning them could cause more confusion with regards to Dapr.

Can you be more specific here about confusing? These are just tokens. If we want to show Dapr independence for the token we have to mention at least two examples to show how/why. JWT was the other example I had in mind, so not clear why this would be confusing.

[ItalyPaleAle]

So to Dapr, API tokens are opaque strings. Which means that they can be anything, including JWTs but also the name of your pet or the entire text of Dante's Inferno.

With opaque tokens, however, the correct thing to use is random data, which is what allows you to get the most entropy per byte. In fact, each random byte (before it's encoded to base64) contains exactly 8 bits of entropy (by definition), and nothing else can have higher density of entropy. Using random data allows you to get the shortest tokens with the highest amount of entropy, so it's the most efficient at a given level of desired security. (Of course the random data is then base64-encoded, which makes the tokens slightly longer but preserves the amount of entropy). This means that suggesting anything else is recommending to weaken the security of the system, or making it less efficient.

With regards to JWTs specifically, I also have an another concern. You can say that there are 2 kinds of developers: those who understand JWTs, and those who don't, and the latter group is likely bigger.

For those who do not understand JWTs, seeing them mentioned there is adding unnecessary confusion. JWTs are indeed complicated beasts and cause people to get lost into the world of HMACs and digital signatures. Also, because lots of people don't understand JWTs, there are myths around such as that JWTs are insecure (which is a popular argument you can read online, especially in beginner articles, and it's not really about JWTs themselves but more about how they're stored/handled), or worse that they are encrypted (they can be, but they normally aren't) so developers may store sensitive data in them.

For those who do understand JWTs, seeing them mentioned here would be confusing. When I read the docs, I couldn't really understand myself why JWTs were mentioned.
JWTs are self-contained tokens, which are designed to carry certain claims. It's expected that the application that receives them will decode & validate the JWT, and do something with the claims it contains. They're the opposite of opaque tokens, in fact! The current Dapr docs suggest to generate a JWT but are not saying what claims to include (first source of confusion - if they are tokens meant to carry information, developers need to know what information to include), what key to sign them with (second source of confusion: if they need to be validated, information on the keys need to be included), and then how to pass information on issuer and key to Dapr.

I actually would recommend removing the JWT icon from the diagrams on dapr.io and replacing them with a more generic token icon.

[msfussell]

Explanation makes sense. In that case, lets raise a PR to update the Website diagrams

[ItalyPaleAle]

Where are the sources for that? I found the PNGs here but I can't find the source assets (like SVG or PSD or whatever): https://github.com/dapr/website/tree/master/static/images

[msfussell]

Where are the sources for that? I found the PNGs here but I can't find the source assets (like SVG or PSD or whatever): https://github.com/dapr/website/tree/master/static/images

See linked issue for the diagram source.

[msfussell]

LGTM