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.
It summarized my understanding after a month of reading documentation, doing experiments, and generally banging my head against the wall.
(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.)
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.
> 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.
Adding the oauth calls into your app that already has a web server, job processing, and a db is way easier than integrating what ever weird stuff some random library does.
In practice, isn’t OAuth predominantly used to verify proof of email ownership? If so, why not just use magic links as sign up & sign in?
1. Sign in/up: Enter email (can be pre-filled by browser/app)
2. Click the email verification link or enter code if on different device.
3. Profit. No manual typing necessary, only clicks.
This is trivial to implement, and can be extended in the future with a simple standard for browsers/apps to automatically verify in the background (to avoid the tab-switching inconvenience in step 2). On iOS they auto-populate SMS codes in a similar fashion.
2FA can be out of scope, (many times not needed because email providers already have it). But if needed, it can be added as a second step after the email proof.
Please tell me what I’m missing. This seems, to me, like an excellent trade off between implementation simplicity, extensibility, user convenience and security.
For example - login system that merged LDAP/Kerberos/client cert/long-lived application token authentication into single system, that also linked said authentication system into all applications in the network, including making it possible to login to AWS Console using Kerberos (that one was twisty to get running, not because of OAuth2 but because of how it is handled by AWS IAM).
Also, I have used it to link in MFA systems of different kinds (it was definitely easier side than industry standard of using Radius)
In addition, this proposed system requires that every app has ability to send emails, which honestly is less simple than it sounds, especially today when sending to arbitrary public emails.
> this proposed system requires that every app has ability to send emails, which honestly is less simple than it sounds
For humans and especially end-users of consumer services, my observation is that the elaborate auth dances are using email ownership as last resort anyway, ie for account recovery and/or a trusted 3p that has verified the email. So the thought is simply to make that flow more convenient. Perhaps this is misguided.
This also means I have one place to support sending last resort emails
As for enterprise auth, a lot of places in fact do not use emails for identity. Sometimes there's more than one login id mapping to one identity (noticeable case - Kerberos/LDAP as done by Active Directory, where your login can come in email-style form and pre-AD form, and the email-style one doesn't have to correspond to an email)
(On a side note, I'm constantly annoyed/frustrated that after about 20 years of development, authentication codes/apps and smartcode verification are starting to be almost as secure and usable as the HTTPS client certificate support that was built into every browser as far back as the '90s)
But nevertheless widely used as de-facto identity, I assume because account recovery in case of lost credentials is paramount. At least 90% of my accounts would be stolen or lost, today, should I lose access to my email.
I don’t particularly like email, for many reasons. Especially that most people’s email can be blocked by a faceless corporation that suddenly bans you. That said, I think there are far worse options, such as endless iterations on proprietary and ad-hoc auth “standards”. At least to me, the technical challenges of hardening email seem far less intimidating than educating the public on a new system.
> apps and smartcode verification are starting to be almost as secure and usable as the HTTPS client certificate support
I agree that client certs are greatly under-utilized and poorly supported by eg reverse proxies, but how would they help here? What’s the user flow for non-technical Joe to acquire a client cert to pay his bills?
Sure, but that's your choice. If you want to make your Google account require 3 factor authentication and a 10 minute timeout, you can, and from the perspective of any site logging you in via OAuth from Google, nothing changes. Even if 90% of users are going to use email only, it's nice to not force everyone down to that lowest common denominator.
> I agree that client certs are greatly under-utilized and poorly supported by eg reverse proxies, but how would they help here? What’s the user flow for non-technical Joe to acquire a client cert to pay his bills?
I just feel that if we'd put half the effort people put into SMS 2FA, authenticator apps, password managers and all that into making a better UX for client certificates, we'd be further along. Ah well.
In short it works when you can see it as a guideline instead of a standard.
I abstracted it away behind a "token provider" interface, so I can just instantiate the right one for the job.
There's some incantations to get the request right, but I found most documentation decent so just follow that.
One service required I implemented RFC 8693 token exchange, which turned out to be trivial since I could represent it as one "token provider" instance wrapping another.
Failures can still be opaque though, especially when using the tokens.
- Send user to example.com
- Eventually they're sent back to yoursite.com with a ?code=abc
- Call example.com/OAuth to exchange ?code=abc for access token and refresh token
- You're done (for now)
- When access token expires, call example.com/OAuth to exchange refresh token for a new access token and refresh token
The tricky part is that a bunch is implementation specific, so memorising the above only gets you half way to implementing with another provider.
But the application currently has it's own authorization policy in a flat file which organizes users into groups and gives groups permission to take certain actions, a simple RBAC. I'd like to refactor this so that the authorization is delegated to the OAuth server.
Ideally I want to be able to ask a keycloak/okta server "now that user X is authenticated, are they part of the group Y?".
Since this isn't a common use case and everything is so abstract it's been very difficult to find an obvious path forward.
As I could not find any pre-existing good guidance on solving this, I ended up implementing it by having the resource servers (i.e. APIs) check the token using token introspection endpoint at the auth server (not the RFC version of introspection, just private one for now but I may add the RFC compliant version as well so it could be called by 3rd parties as we have not yet rolled out this OAuth2 based setup for our customers). Part of that return information from the introspection endpoint is this permission mapping between logical entities and scopes, so the resource server can know to which entities caller has which scopes. Of course, as our access tokens are not JWT and just opaque (encrypted) data, the introspection endpoint then need to decrypt it - just so it can quickly validate expiration etc. - and if valid, fetch a matching copy from the database that has more contextual information than what's encoded inside the client-supplied access token. Otherwise, the length would be prohibitive if token would be fully self-contained with these extra information.
Maybe this same kind of method could be used for your use case as well, encoding authorization policy adjacent to the access token in your backend, and looked up by app using it after it has received the token?
Overall I found it fairly OK, it's a bit of a learning curve when you're just used to basic user/pass, but it's fine.
However the main issue is that when it's not working it's very opaque. This is even worse when trying to _use_ the tokens.
I spent many hours trying to figure out why my Client Credentials tokens wouldn't work for logging on to Office365's IMAP server, only to spend half an hour searching and finding some Microsoft community forum post saying it wasn't implemented yet... they only supported Authorization Code flow. This has been fixed they say, I'll know later today cause that just came up as a priority ticket...
All you get back is some "nope", with no way to figure out why.
[1]: https://learn.microsoft.com/en-us/azure/active-directory/dev...
[2]: https://learn.microsoft.com/en-us/azure/active-directory/dev...
[3]: https://learn.microsoft.com/en-us/azure/active-directory/dev...
I spent a lot of time making sure I did everything as by the book as possible and , in the end, I had a good experience and felt confident in my implementation, and like I understood all the moving parts. I even got help in a SO thread from an auth0 employee.
Auth0 could have been anything, here... On the same project, I kind of did the same thing with vite/react/tailwind client and fast api backend where I touched every piece of it, made every decision, and made sure I was really confident. This was in my own little vacuum where a big part of the app was just creating my perfect little sandbox. Stuff gets way more complicated when you have to hustle to get stuff over the line or you're trying to cram so new auth implementation in to an 8 yr old app that's been walked around on by dozens of engineers slamming out slop to close a ticket.
(Note: I know auth0 is a little more on-rails than implementing auth0 without it. They tend to have pretty good guides if you're using current hotness like react or fastapi)
1) skimming for limited context
2) copying and pasting random code
3) trying it with print statements
4) getting stuck
5) repeating steps 1-3 until it works
I get the problem though, many of the libraries are not great or simply difficult to use
I have rough understanding of oauth but never had to dive in.
Don't ask me why, I thought the whole point of OAuth was that example.com was allowed to access identity.com. Instead, example.com opens a hidden identity.com iframe and does what do I know?
At my old job, users could specify their own IdentityProvider for their instance, which added a whole layer of complexity.
Now we have found out that a different team has implemented their side of OAuth completely wrong: Their device flow ("Open in app and enter 56474") doesn't poll automatically. Instead, user have to click "try now" manually. The whole auth is lost when the device restarts.
I'm not surprised Microsoft lost control of Bing because they implemented OAuth wrong for one of the services displayed there.
1. Read loads of docs, end up pretty confused
2. Find a library that seems to do what I want
3. Install this huge library full of opaque code doing...things
4. Have an impossible time troubleshooting issues
5. Get scared ("I'm almost certainly doing something wrong here") and give up
I find it hard to have much faith in security standards like this. I want them small, well defined and understandable and OAuth does not meet any of these criteria in my experience.