Pros and Cons of JSON Web Tokens

JSON Web Tokens (JWTs) are a standard for OAuth 2.0 token format. The current (as of February 2020) implementation of OAuth 2.0 for MediaWiki in Extension:OAuth uses JWTs for tokens. There is a question about whether we should keep doing this. This page is for talking about the pros and cons of JWTs for MediaWiki and specifically Wikimedia sites.

Background
In OAuth 2.0, a token is a string of characters that represents a grant of rights by a user to a client application for accessing resources on a server. For example, if Alice wants to use Program X to manage her Wikipedia watchlist, she could obtain a token representing the read and edit watchlist right and Program X could use that token to read and update her watchlist with the Action API.

Most of the OAuth 2.0 spec is about how to obtain and use these tokens. In the spec, the token format is left up to the implementation.

There are two main strategies for formatting tokens.

The first is to use a very long randomly-generated string (say, hundreds or thousands of bytes) so it's not easily guessable by bad actors. On the server side, a representation of the grant of rights is stored in a database, with the token as a key. Something like: When the client app sends the token to the server, it can look up the token in the table, and check if the app has the rights to do what it's asking to do.

Another technique is to encode the grant information into the token itself. This is the approach used by JSON Web Tokens. The grant data is stored in a JSON blob, which is then compressed and digitally signed by the server; the resulting data is the token. When the token is presented to the server, the server can decode it, check the digital signature, and check the app's rights without doing a database lookup. JSON Web Tokens are a standard defined in RFC 7519.

Pros

 * Makes it easier to build APIs that support OAuth 2.0 outside of MediaWiki. Because the API server doesn't need to access a database table to determine if a token is valid, API servers built outside of MediaWiki are somewhat easier to build. They may still need to use the database or a MediaWiki API to get the data the user is asking for, though!
 * Lets client developers inspect tokens for debugging or other work. A client developer can use a JWT parser to determine what the grants are or the metadata about the grant. That's useful for debugging errors, validating that the token is complete and well-formatted, or just to figure out how to use the token.
 * JWTs are popular. Atlassian, Google, Microsoft and other platforms use JWTs for their OAuth 2.0 tokens. Authorization services like Okta and Auth0 also use them. Client developers are getting familiar with the tools.

Cons

 * Some people think that tokens should be opaque to clients. The OAuth 2.0 spec says "The string is usually opaque to the client".
 * It's possible to support API development outside of MediaWiki with an internal API for validating and decoding tokens.
 * Supporting JWTs requires managing RSA key files for developers, CI, and production.