As someone who has never used OAuth2 before, this article was not helpful at all. Calling it a "complete guide" is a total overstatement.
@brap, sorry it wasn't helpful. It's aimed at folks who want to protect APIs, but maybe I missed the mark.
This article (which I co-authored) may be more helpful: https://fusionauth.io/learn/expert-advice/oauth/modern-guide...
It was also discussed here on HN, if you want some different perspectives: https://news.ycombinator.com/item?id=29752918
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.
[1]: https://docs.microsoft.com/en-us/azure/active-directory/deve...
I think this may have been an oversight during the final editing process. I ended up having to split this up into two articles, as you surmised.
The second one is a blow by blow of the authorization code grant (and how an API should validate a token) and will be published later this week.
But I should have caught that we promised the code in the intro and removed that.
- Authorization server, roll your own, run your own (like Ory Hydra), or use third-party (like Azure AD)?
- Tokes, if you can choose, should you go with opaque tokens, JWT or something else? What about token lifetimes?
- When you get a token from a client, how do you validate that the token is valid?
There's probably more, but I feel at least these points should be included in a "complete guide".
Change the title and it's a fine OAuth blog post. edit: for example, add ", part 1 - introduction".
> 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!
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.
No worries, I appreciated the feedback. That's one of the magical parts of HN comments.
Unfortunately part 2 is already edited and ready to go and so won't cover the choice of authorization server; it kinda assumes you are using one.
Here's an HN comment I made that covers the dimensions of what to think about: https://news.ycombinator.com/item?id=26411197
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.
No worries!
> I think something like a “Todos API with OAuth2 from scratch with code snippets”
Here you are: https://fusionauth.io/learn/expert-advice/oauth/modern-guide... and here's the github repo for the code in it: https://github.com/FusionAuth/fusionauth-example-modern-guid...
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.
A "complete guide" to this is still sorely lacking -maybe because it just is that complicated and can not be dumbed down?
I found these resources helpful:
* 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
* Podcast episode about OAuth with the author of "OAuth2 in Action" https://www.se-radio.net/2019/08/episode-376-justin-richer-o...
[1]https://engineering.intility.com/article/implementing-oauth2...