5 ms·

An illustrated guide to OAuth

355 points by egonschiele 1y ago

politelemon 1y ago
This is well written and helped me understand quite a bit. I think a pkce edition would be appreciated considering how prevalent and recommended it is.
- mdaniel 1y ago
  Depending on if you're shopping for the server or the client side of the implementation, I actually found the RFC's example section was actually helpful https://datatracker.ietf.org/doc/html/rfc7636#appendix-B https://datatracker.ietf.org/doc/html/rfc7636#appendix-B The only thing that jammed me up, even while preparing this comment, is that they named both parameters very similar to one another which is :-( One can think of the whole exchange as a way for the client to prove future knowledge, but only actually transmitting the held back "secret" during token redemption. Let's use just a random integer 1. r = randomInt() 2. future = base64(sha256(r)) 3. /authorize?client_id=cid-123&code_challenge_method=S256&code_challenge=${future} The server has to retain the ${future} in durable storage, because it's going to need access to it, plus the ${code} that it's about to return, in step 5 4. <-- &code=abc789 5. /token?code=abc789&code_verifier=${r} Now, the server can repeat that same sha256 dance from step 2 and establish that the client presenting "r" means it really was the same requester in step 3, because no one else, even with that same IP address and same access to the client_id sniffed in transit, could have known "r" for sufficiently random values of "r", thus proving their key during code exchange
- calexanderaz 1y ago
  Here’s a description of all the major flows of OAuth 2.0, along with a visual description of PKCE (and the attack it prevents) https://youtu.be/tpIXmmV4ib4 https://youtu.be/tpIXmmV4ib4
fcpguru 1y ago
where is the "session fixation" / token hijacking attack graphic? The history of 1.0 and the rush to put out OAuth 1.0a I will always remember. The year was 2008 and us yammer engineers implemented this new best practice auth system. It went live. And then suddenly a few days later someone in the office proved how the hijack was possible.
- 7bit 1y ago
  Why is that relevant. We are at OAuth 2.0. who cares about what's been 17 years ago?
  - brabel 1y ago
    2.1 is just around the corner.
    - ted_dunning 1y ago
      And 2008 is still 17 years ago.
      - brabel 1y ago
        What??
  - fcpguru 1y ago
    i guess it's not. just past trama. I had to talked about it. Better now.
gethly 1y ago
I am implementing oauth right now, along with oidc. I must say that for such a simple concept, getting to the facts that help me to actually implement it is insanely hard. I have no idea why but everywhere i look it just seems like it only scratches the surface and you get no tangible information that you can use to actually implement it in code. I ended up mostly browsing the specs and grok was insanely helpful to explain meaning of various things where information was lacking or buried deep in documentation/specifications. I would say this was the first time where i actually appreciated these new "AIs", which i don't use at all.
- aurecchia 1y ago
  Are you implementing an auth server or integrating with one? Regardless, the last time I dug into this topic I ended up feeling the same. The web is littered with articles that scratch the surface and only cover the basics. They often leave out the details, which IME ended up making things more difficult to understand. What was the most helpful, as you said, was to follow the RFCs and the OIDC spec directly. What might also be useful, if you are implementing an auth server, is to look at existing implementations. Duende IdentityServer (https://github.com/DuendeSoftware/products/tree/main/identity-server https://github.com/DuendeSoftware/products/tree/main/identit...) is the most widely-used one in the .NET space.
  - commandlinefan 1y ago
    > Are you implementing an auth server or integrating with one? And OAuth has somehow managed to be _harder_ to integrate with an existing implementation of than just to implement from scratch.
  - peterldowns 1y ago
    Ancient, but potentially also helpful due to documentation and tests, is my old django implementation: https://github.com/peterldowns/djoauth2 https://github.com/peterldowns/djoauth2 . I’m sure it doesn’t run out of the box anymore due to Django changes but maybe another good reference server.
  - olavgg 1y ago
languagehacker 1y ago
This is a nice one! Reminds me of the [beer garden analogy](https://www.stevetecharc.com/blog-posts/understanding-oauth-web-server-flow-a-beer-garden-analogy https://www.stevetecharc.com/blog-posts/understanding-oauth-...) which I also thought was a good entree into OAuth.
tiffanyh 1y ago
> The example I'm going to use is YNAB. If you haven't used it, YNAB is like a paid version of Mint. I'm glad this analogy was used ... because I too feel like OAuth and Open Banking is effectively the same thing. Am I alone thinking that and/or why is it actually two different things?
TofuLover 1y ago
I don't think the part about front and back channels is quite correct. GET and POST requests are both encrypted in HTTPS -- including the URL (but not the domain, as DNS resolution happens separately). Front and back channel are more to do with trust boundaries, and what information is public vs private from the client's perspective.
- cathalc 1y ago
  Yeah this made zero sense to me - I have never seen someone consider POST secure because it can't "be seen". Security through obscurity and all that...
  - doublerabbit 1y ago
    Is there anyway to secure a POST request at the backend, without client side encryption? The server processing the POST is still receiving the information posted regardless if the client is HTTPS or not. Say, you're attempting login, the password is still received by the server and which you do with whatever when processing. What's not stopping someone from injecting a trace on that receiving function? In other-words, How would you secure the server processing the POST request information?
    - BrandoElFollito 1y ago
      You can't. It is just a matter of reducing the risk surface. With a GET someone may add parameters, with a POST they would send the data in the post (which is often the main point of a POST). Since all typical web servers/processors only loh the call and not the body there is a lesser probability of a leak. I am writing this as someone who manages cybersecurity and is offering faced with not enough information in investigations because of that. This is also the reason that I used "typical" and "usually" above - it is pretty weird what people send and how they process what they receive.
- aszen 1y ago
  Main point is that the url is store in browser history and is never private.
ttb-2134 1y ago
This is one of the best OAuth explainers out there. Amazing
homakov 1y ago
IMO OAuth2 is very poorly designed. It has several structural issues: "Connect this OAuth provider" hijack your main account, redirect hijack allows to leak either auth codes through Referrer or access_token through #hash passing, "state" CSRF token is optional and usually ignored etc I have an old writeup on that and solution to it https://sakurity.com/oauth https://sakurity.com/oauth - better analyze it with LLM if interested in authorization protocols
- ted_dunning 1y ago
  Your comments are so highly abbreviated as to be nearly impossible to understand. I suspect that unintelligibility is leading to it being heavily downvoted. The addition of the comment about LLMs isn't really helping.
  - homakov 1y ago
    I wasn’t criticizing the guide — just pointing out real OAuth2 pitfalls that still affect users. The spec itself made mistakes: • Silent account hijack via “Connect this provider.” • Redirect leaks of code (via Referrer) or access_token (via #hash). • CSRF because state was optional and often ignored. The point is: these aren’t obscure edge cases, they’re structural issues baked into the protocol.
  - derangedHorse 1y ago
    His comments are also outdated. Browser binding with a separate nonce is standard practice by big identity providers, redirect uris are typically strictly validated, implicit flow without pkce is being phased out, and most browsers protect against a lot of would-be csrf attacks with strict samesite cookie headers.
chrisgd 1y ago
Love the illustrations! Great descriptions, thank you
pinoy420 1y ago
[dead]
losvedir 1y ago
This is a pretty good guide! I didn't get any AI slop vibes from it, so I'm assuming it was handwritten, which I appreciate. I think I would suggest that PKCE is not really "less secure" than a client secret. It serves somewhat of a different purpose, and is actually frequently recommended even with a client secret. Its main purpose is "flow integrity" and ensuring that the same client is involved all the way through the redirects. I think it also didn't really put the authorization code grant in context with the other possibilities. This really covered the "3 legged redirect" flow pretty well, which is what most people associate with OAuth. But the OAuth2 framework has a bunch of different grants you can use for different purposes. The Client Credentials one is pretty common, for server-to-server use cases, as well as fancier versions of it like the JWT Bearer flow. Finally, taking an advantage of general OAuth2 discussion, since I've been noodling on it myself from the point of view of creating an "app ecosystem": since the redirect_uri is such an integral part of the security of it, and recommendations are for exact matches now rather than just prefixes and wildcards and such, how do folks handle OAuth2 when the app isn't owned by a single entity, but rather something like ServiceNow or Backstage which is self-hosted? That is, you want your resource server to behave like "this was a request from a customer's ServiceNow instance", and all such requests are in some sense related. However, they're not really the same client, because you can't manage a client secret across all the installations. It's somewhat like a mobile app, which also can't manage a client secret, but that at least can share the same underlying OAuth Client because it can register a single, unique redirect URI. I have other questions about things like how to fit the client credentials grant into a multi-tenant system... if these are things you've worked on, I'd love to hear from you! My email should be on my profile here.
iamcreasy 1y ago
Very clearly written article. Please write follow ups exploring other OAuth flows.
Pet_Ant 1y ago
This could have used a crudely animated .gif to pull it all together. Or even a slide show or something.
chasil 1y ago
https://archive.ph/fm9Ax https://archive.ph/fm9Ax
tbarbugli 1y ago
> anyone can see what URLs you are visiting this is not correct with HTTPS (query params are not part of the plain text)
osdev 1y ago
Also agree with some of the comments here that majority of articles about OAuth are incredibly verbose, but really hard to actually implement without concrete examples. I personally think having Curl requests as part of the examples would solve this problem.

355 points by egonschiele 1y ago

This is well written and helped me understand quite a bit. I think a pkce edition would be appreciated considering how prevalent and recommended it is.

mdaniel 1y ago
Depending on if you're shopping for the server or the client side of the implementation, I actually found the RFC's example section was actually helpful https://datatracker.ietf.org/doc/html/rfc7636#appendix-B https://datatracker.ietf.org/doc/html/rfc7636#appendix-B The only thing that jammed me up, even while preparing this comment, is that they named both parameters very similar to one another which is :-( One can think of the whole exchange as a way for the client to prove future knowledge, but only actually transmitting the held back "secret" during token redemption. Let's use just a random integer 1. r = randomInt() 2. future = base64(sha256(r)) 3. /authorize?client_id=cid-123&code_challenge_method=S256&code_challenge=${future} The server has to retain the ${future} in durable storage, because it's going to need access to it, plus the ${code} that it's about to return, in step 5 4. <-- &code=abc789 5. /token?code=abc789&code_verifier=${r} Now, the server can repeat that same sha256 dance from step 2 and establish that the client presenting "r" means it really was the same requester in step 3, because no one else, even with that same IP address and same access to the client_id sniffed in transit, could have known "r" for sufficiently random values of "r", thus proving their key during code exchange
calexanderaz 1y ago
Here’s a description of all the major flows of OAuth 2.0, along with a visual description of PKCE (and the attack it prevents) https://youtu.be/tpIXmmV4ib4 https://youtu.be/tpIXmmV4ib4

fcpguru 1y ago

where is the "session fixation" / token hijacking attack graphic? The history of 1.0 and the rush to put out OAuth 1.0a I will always remember. The year was 2008 and us yammer engineers implemented this new best practice auth system. It went live. And then suddenly a few days later someone in the office proved how the hijack was possible.

7bit 1y ago
Why is that relevant. We are at OAuth 2.0. who cares about what's been 17 years ago?
- brabel 1y ago
  2.1 is just around the corner.
  - ted_dunning 1y ago
    And 2008 is still 17 years ago.
    - brabel 1y ago
      What??
- fcpguru 1y ago
  i guess it's not. just past trama. I had to talked about it. Better now.

gethly 1y ago

I am implementing oauth right now, along with oidc. I must say that for such a simple concept, getting to the facts that help me to actually implement it is insanely hard. I have no idea why but everywhere i look it just seems like it only scratches the surface and you get no tangible information that you can use to actually implement it in code. I ended up mostly browsing the specs and grok was insanely helpful to explain meaning of various things where information was lacking or buried deep in documentation/specifications. I would say this was the first time where i actually appreciated these new "AIs", which i don't use at all.

aurecchia 1y ago
Are you implementing an auth server or integrating with one? Regardless, the last time I dug into this topic I ended up feeling the same. The web is littered with articles that scratch the surface and only cover the basics. They often leave out the details, which IME ended up making things more difficult to understand. What was the most helpful, as you said, was to follow the RFCs and the OIDC spec directly. What might also be useful, if you are implementing an auth server, is to look at existing implementations. Duende IdentityServer (https://github.com/DuendeSoftware/products/tree/main/identity-server https://github.com/DuendeSoftware/products/tree/main/identit...) is the most widely-used one in the .NET space.
- commandlinefan 1y ago
  > Are you implementing an auth server or integrating with one? And OAuth has somehow managed to be _harder_ to integrate with an existing implementation of than just to implement from scratch.
- peterldowns 1y ago
  Ancient, but potentially also helpful due to documentation and tests, is my old django implementation: https://github.com/peterldowns/djoauth2 https://github.com/peterldowns/djoauth2 . I’m sure it doesn’t run out of the box anymore due to Django changes but maybe another good reference server.
- olavgg 1y ago

languagehacker 1y ago

This is a nice one! Reminds me of the [beer garden analogy](https://www.stevetecharc.com/blog-posts/understanding-oauth-web-server-flow-a-beer-garden-analogy https://www.stevetecharc.com/blog-posts/understanding-oauth-...) which I also thought was a good entree into OAuth.

tiffanyh 1y ago

> The example I'm going to use is YNAB. If you haven't used it, YNAB is like a paid version of Mint. I'm glad this analogy was used ... because I too feel like OAuth and Open Banking is effectively the same thing. Am I alone thinking that and/or why is it actually two different things?

TofuLover 1y ago

I don't think the part about front and back channels is quite correct. GET and POST requests are both encrypted in HTTPS -- including the URL (but not the domain, as DNS resolution happens separately). Front and back channel are more to do with trust boundaries, and what information is public vs private from the client's perspective.

cathalc 1y ago
Yeah this made zero sense to me - I have never seen someone consider POST secure because it can't "be seen". Security through obscurity and all that...
- doublerabbit 1y ago
  Is there anyway to secure a POST request at the backend, without client side encryption? The server processing the POST is still receiving the information posted regardless if the client is HTTPS or not. Say, you're attempting login, the password is still received by the server and which you do with whatever when processing. What's not stopping someone from injecting a trace on that receiving function? In other-words, How would you secure the server processing the POST request information?
  - BrandoElFollito 1y ago
    You can't. It is just a matter of reducing the risk surface. With a GET someone may add parameters, with a POST they would send the data in the post (which is often the main point of a POST). Since all typical web servers/processors only loh the call and not the body there is a lesser probability of a leak. I am writing this as someone who manages cybersecurity and is offering faced with not enough information in investigations because of that. This is also the reason that I used "typical" and "usually" above - it is pretty weird what people send and how they process what they receive.
aszen 1y ago
Main point is that the url is store in browser history and is never private.

ttb-2134 1y ago

This is one of the best OAuth explainers out there. Amazing

homakov 1y ago

IMO OAuth2 is very poorly designed. It has several structural issues: "Connect this OAuth provider" hijack your main account, redirect hijack allows to leak either auth codes through Referrer or access_token through #hash passing, "state" CSRF token is optional and usually ignored etc I have an old writeup on that and solution to it https://sakurity.com/oauth https://sakurity.com/oauth - better analyze it with LLM if interested in authorization protocols

ted_dunning 1y ago
Your comments are so highly abbreviated as to be nearly impossible to understand. I suspect that unintelligibility is leading to it being heavily downvoted. The addition of the comment about LLMs isn't really helping.
- homakov 1y ago
  I wasn’t criticizing the guide — just pointing out real OAuth2 pitfalls that still affect users. The spec itself made mistakes: • Silent account hijack via “Connect this provider.” • Redirect leaks of code (via Referrer) or access_token (via #hash). • CSRF because state was optional and often ignored. The point is: these aren’t obscure edge cases, they’re structural issues baked into the protocol.
- derangedHorse 1y ago
  His comments are also outdated. Browser binding with a separate nonce is standard practice by big identity providers, redirect uris are typically strictly validated, implicit flow without pkce is being phased out, and most browsers protect against a lot of would-be csrf attacks with strict samesite cookie headers.

chrisgd 1y ago

Love the illustrations! Great descriptions, thank you

pinoy420 1y ago

[dead]

losvedir 1y ago

This is a pretty good guide! I didn't get any AI slop vibes from it, so I'm assuming it was handwritten, which I appreciate. I think I would suggest that PKCE is not really "less secure" than a client secret. It serves somewhat of a different purpose, and is actually frequently recommended even with a client secret. Its main purpose is "flow integrity" and ensuring that the same client is involved all the way through the redirects. I think it also didn't really put the authorization code grant in context with the other possibilities. This really covered the "3 legged redirect" flow pretty well, which is what most people associate with OAuth. But the OAuth2 framework has a bunch of different grants you can use for different purposes. The Client Credentials one is pretty common, for server-to-server use cases, as well as fancier versions of it like the JWT Bearer flow. Finally, taking an advantage of general OAuth2 discussion, since I've been noodling on it myself from the point of view of creating an "app ecosystem": since the redirect_uri is such an integral part of the security of it, and recommendations are for exact matches now rather than just prefixes and wildcards and such, how do folks handle OAuth2 when the app isn't owned by a single entity, but rather something like ServiceNow or Backstage which is self-hosted? That is, you want your resource server to behave like "this was a request from a customer's ServiceNow instance", and all such requests are in some sense related. However, they're not really the same client, because you can't manage a client secret across all the installations. It's somewhat like a mobile app, which also can't manage a client secret, but that at least can share the same underlying OAuth Client because it can register a single, unique redirect URI. I have other questions about things like how to fit the client credentials grant into a multi-tenant system... if these are things you've worked on, I'd love to hear from you! My email should be on my profile here.

iamcreasy 1y ago

Very clearly written article. Please write follow ups exploring other OAuth flows.

Pet_Ant 1y ago

This could have used a crudely animated .gif to pull it all together. Or even a slide show or something.

chasil 1y ago

https://archive.ph/fm9Ax https://archive.ph/fm9Ax

tbarbugli 1y ago

> anyone can see what URLs you are visiting this is not correct with HTTPS (query params are not part of the plain text)

osdev 1y ago

Also agree with some of the comments here that majority of articles about OAuth are incredibly verbose, but really hard to actually implement without concrete examples. I personally think having Curl requests as part of the examples would solve this problem.