The one that I find easiest to understanding is still the one that I wrote about a decade ago when I first had to work with OAuth 2. All others I understanding by mapping what they said to concepts in mine, and that seems to work pretty well.
My document is available at https://metacpan.org/dist/LWP-Authen-OAuth2/view/lib/LWP/Aut.... Even though you're unlikely to ever use that library or language, you may find it worthwhile.
Perhaps it's a semi-consequence of Perl being perceived as old and crusty, and popular with old crusty people who are merely trying to get things done without fluff (at least speaking for myself).
Reminds me of Data::Manip, another favorite of mine.
Thanks for taking the time to write this (and implement all that nonsense).
The crustiness in this case was enhanced by my grumpiness over some frustrating debugging sessions, and having to go through a lot of very confusing documentation to get there. That grumpiness shows through in a couple of places.
For example I understand why Google decided that I was asking for the same permission too often, and began handing me codes that would not work. And also wouldn't explain what was wrong with the code that I just got.
It summarized my understanding after a month of reading documentation, doing experiments, and generally banging my head against the wall.
> OAuth 2 makes it easy for large service providers to write many APIs that users can securely authorize third party consumers
If I'm trying to write a Mastodon client, I'm reading this line piece by piece:
> OAuth 2 makes it easy for large service providers
"service providers" OK, that must be the Mastodon service.
> ... to write many APIs that users
"users" That must be me
> ... can securely authorize third party consumers
"consumers" OK... that's also me?
If you're trying to write a Mastadon client, then the Mastadon service is the service provider, you are the consumer, and the people who wish to use your client are the users.
The only thing I'd suggest is putting the terminology first, so readers can first correct their misconceptions from all the terrible literature around this.
That's because there are many ways you could use a document like that. And the Terminology section is very overwhelming unless your goal is to understand how OAuth 2 REALLY works, and why it works that way.
(Only feedback I can think of is that it would be great to have a few diagrams... like from excalidraw or something. Am largely a visual learner.)