Not op, but I found it a bit lacking given the title. From the article:
While I’ll dive further into how you actually use OAuth to protect an API in your system below, including code examples, [...]
I failed to find much concrete around how to use OAuth to protect an API, and no code samples. Is this a part one in a series? If so, it should be more clear about that perhaps.
edit: For example, I just had to secure my non-Azure API using access tokens issued by Azure AD. Lot of details[1] about how to verify that they're valid, actually issued by Azure AD (one does not simply download a certificate), and it's issued for the right thing.
That said, I found the why and standards section very nice, and the grant selection sections were helpful.
Thanks for this critique. I have limited ability to edit the post, but will try to answer these here.
> Authorization server, roll your own, run your own (like Ory Hydra), or use third-party (like Azure AD)?
If by 'roll your own' you mean 'use an open source library like Python's OAuthLib', all three of these are valid options. Really hard to give general guidance because it depends on the complexity of your application environment (1 app in rails? 10 apps with mix of custom and COTS?) and operational maturity (do you want to run your own server for compliance or control reasons? do you have the skills to do so?).
> Tokens, if you can choose, should you go with opaque tokens, JWT or something else? What about token lifetimes?
"if you can choose" is an important clause here. Many times it'll be dictated by the Authorization server you choose. All other things being equal I'd lean toward JWTs because of their widespread support, but I know others have other opinions.
Re: token lifetimes, this is something you need to threat model out (what happens if a token is stolen?). Generally recommend seconds to minutes for access tokens and longer lived refresh tokens. Also whether you should use token binding or can live with bearer tokens.
> When you get a token from a client, how do you validate that the token is valid?
That will be discussed in part 2 of this series, but in general you should validate the signature (if it is a signed token, often a JWT) or use introspection to ask the Authorization server if it is valid. Then you should validate the claims.
There is definitely more, but thanks for the feedback!
Thanks for the reply, good stuff. Most of this could go into part 2 I think.
For part two I would definitely want at least some discussion around choice of authorization server. I realize a full deep dive is too much, but at least list the options (use a lib, use your own server, use third-party) with some pros and cons or something like that.
If you do go into token generation and usage, and mention JWT, do mention the requirement to verify the alg field against expected value. Just given the issues it's caused in the past.
Anyway, hope I wasn't being too negative, that wasn't my intention.
I also have collected a series of essays around what to think about w/r/t outsourcing auth (including what kind of auth server to choose): https://leanpub.com/theultimateguidetooutsourcingyourauth . Here's a coupon for 50% off that book: hn-april . Or you can email me and I'll get you a copy; my contact info is in my profile.
Thank for the feedback about JWTs. My general recommendation is to use a well vetted open source library for the signature verification, which should handle the alg check. But calling it out is a good idea.
I do appreciate the effort, and sorry for being a dick with my earlier comment (bad mood).
I do feel though that this lacked concrete examples, and maybe should have taken a step or two back to explain the more basic concepts.
For example, who owns the authentication service, is it me (the todos developer) or a 3p? What exactly is the difference between all of these different tokens? What’s the actual protocol for issuing and using them? Etc.
I think something like a “Todos API with OAuth2 from scratch with code snippets” could have been super helpful for noobs like myself.
That assumes you aren't implementing the Authorization Server (it uses FusionAuth, but should work with other OAuth servers like Identity Server or Keycloak). If you want that experience, then I'd recommend buying this book: "OAuth2 in Action" https://www.manning.com/books/oauth-2-in-action which takes you through all of the nitty gritty. Seriously, you'll implement the whole thing. It's pretty cool.
Your sentiments and questions are all perfectly valid. I believe the majority of developers implementing oauth2 on their servers or integrating another service they need oauth2 for have not fully understood what they are doing. I know that's the case for me and I successfully implemented solutions for OIDC, saml, three-legged oauth2 and two-legged oauth2 on both the server and client. It's all an overengineered mess.
A "complete guide" to this is still sorely lacking -maybe because it just is that complicated and can not be dumbed down?
* Solving Identity Management in Modern Applications" walks through the identity life cycle in detail, from initial provisioning to deprovisioning. Concepts, standards, not a lot of code. Lots of focus on the workforce use cases (rather than customer). But still great: https://link.springer.com/book/10.1007/978-1-4842-5095-2
* "OAuth2 in Action", in contrast, builds an OAuth and OIDC server in JS, from scratch, so has lots and lots of code. Great section on tokens, and covers stuff beyond the standard OAuth grants, such as dynamic client registration.
https://www.manning.com/books/oauth-2-in-action
The biggest thing you have left out is one API calling another API which requires on-behalf-of flow. This is an extremely common scenario and yet mostly glossed over until the day you have to do it in a real enterprise to flow the delegated identity.
I have also made an attempt at writing an article for developers that want to implement Oauth2.[1] Not a complete guide, but a short(8min) read that aims to get you started.
