9 ms·

Because the documentation is bad. Oauth is really simple: Lets say you want to use google as an auth provider. You do this: "Hey google who is this guy? I'

Because the documentation is bad. Oauth is really simple: Lets say you want to use google as an auth provider. You do this: "Hey google who is this guy? I'm going to send them to google.com/oauth, send them back to example.com/oauth, and in the headers of the request include the word "Authorization: bearer" followed by a bunch of text" Google says "Oh yeah I know that guy, here I'll send them back to where you said with a token" Then later on you can take the token and say "Hey google, somebody gave me this token, who is it?" That's pretty much it. You have to trust that google isn't lying to you, but that's kindof the point of oauth. But that's never what the documentation says. It's always 10 pages long and the examples are like "here's a fully functioning python web server using flask and function decorators, oh the actual auth flow, which is really like 3 lines of code, is hidden inside of a library". To people who write documentation: PLEASE for the love of god show me how to talk to your API both using your library, but also using something like urllib2 or requests or something. Ideally the documentation is the absolute most minimal way of making the service work, and then adds more and more usefulness on top of that. I'm not going to judge you for writing bad code in an example. The example could practically be pseudocode for all I care. I just want to see generally how your API is supposed to work. edit: yes, auth0, I am looking at you.

garbagecoder 3y ago
Somebody print this comment out, frame it, and mail it to every major API author.
cjbgkagh 3y ago
Auth0 has a business incentive to have people think their core competency is more difficult than it is.
- deleted 3y ago
  [deleted]
deleted 3y ago
[deleted]
jcranmer 3y ago
In my experience with OAuth, one of the principle issues is that it's less a protocol and more a skeleton of a protocol. Actually go to the core RFCs for OAuth, and you realize that basically everything is implementation-dependent. You somehow register with the provider as a client (out of band and completely implementation-dependent). Then you ask them to log you in by sending a request to an implementation-dependent webpage, with implementation-dependent parameters (which ones are required are--you guessed it--implementation-dependent), telling them to redirect you to your page when you're done. Well, actually, that assumes you're building a website. If you're a desktop application, you'll do something else. If you're on an embedded system that can't open up a webpage, there's another option. And there's yet more flows. Which ones are supported by the provider? You guessed it, it's all implementation-dependent. Oh, and maybe you need to refresh tokens to login the future. When? If? You guessed it, implementation-dependent! It makes writing a generic OAuth client library hard because there's basically no commonality there. Really, it makes me long for Kerberos as a much saner SSO system than OAuth.
- majormajor 3y ago
  This is my experience. It's hard because it's very complex. As a non-domain-expert it's hard to separate necessary complexity from unnecessary complexity, but it feels like there's a lot of the latter, plus enough gotchas in the former ("oh, you didn't specify an encryption algorithm that we support in your request, and our logs are terribly unhelpful for realizing that") to make it a giant pain.
  - gigatexal 3y ago
    Is Webauthn a better standard?
    - lstamour 3y ago
      Not exactly. With webauthn the complexity lies in frontend - you have to explain how and why users should use this and what it is, how to manage enrolments and so on. Touch ID, Windows Hello and Passkeys might simplify this but it is still more complex to explain to less technical customers than, say, Face ID on an iPhone app to remember your login. If you want an easy all-purpose login flow, sign in by clicking a link in email is still an easy fallback. OAuth from multiple providers also has complexity - Auth0 makes it so you have to maintain separate databases for passwords if you want to support login via OAuth and login from password. You have to link accounts to login from multiple providers. Logins are simply hard work no matter how you slice it. Eventually they will be easy but… I’m not holding my breath. :)
paulddraper 3y ago
One reason is that the protocol itself is more complicated than you've described. For example, Google won't give you a long-lived access token. You need a refresh token, and then you use that to retrieve access tokens, and continue doing that as they expire. Why? I have not a flipping idea. Please, HN enlighten me how refresh/access token dichotomy improves the API.
- dflock 3y ago
  It's really trying to solve a problem they created by statlessly handing out tokens instead of keeping session state on the backend - they have no way to revoke a token once issued, so long lived tokens are a liability. Solution? More complexity! Hand out very short lived tokens, along with a slightly longer lived refresh token, which only allows you get a new bearer/access token.
  - rad_gruchalski 3y ago
    Don't they still require some state to be able t invalidate refresh tokens?
    - radlad 3y ago
      Yes, but checking refresh tokens will occur much less frequently than checking access tokens. So you can imagine, for example, access tokens being JWT, so they are cheap to check. But every so often you have to validate the refresh token against MySQL (or BigQuery or what-have-you), which is more expensive.
      - rad_gruchalski 3y ago
        That's all clear to me. But technically there exists a method to revoke an issued token. It's just that long lived tokens mean potentially lots of them == increased storage cost. It would be pretty silly not to check for revocation. How would one implement logout otherwise? Relying on just clearing session cookies? What if I obtained those cookies using something else than a browser and I can hold on to the cookie jar? Not checking for revocation == doing it wrong. The purpose of a refresh token to allow the app to short circuit the login process. Regardless of how long the token is issued for. It's perfectly okay to ignore refresh tokens altogether, if one wants to.
izacus 3y ago
That drove me up the wall in Python so much - ALL the documentation just described how to put a massive library into a cookie cutter example and never explained how it's supposed to work so I could debug the darn thing.
- znpy 3y ago
  when it comes to this kind of things there's really no way around it: you're supposed to read the RFCs: - https://www.rfc-editor.org/rfc/rfc6749.html https://www.rfc-editor.org/rfc/rfc6749.html: The OAuth 2.0 Authorization Framework - https://www.rfc-editor.org/rfc/rfc6750.html https://www.rfc-editor.org/rfc/rfc6750.html: The OAuth 2.0 Authorization Framework: Bearer Token Usage
  - asdfman123 3y ago
    As someone who is hired to sling out features as rapidly as possible, that’s not going to happen. I mean, you might say “but you should” or “it would actually help” or “in an ideal world…” but it is still, realistically, not going to happen.
    - sytringy05 3y ago
      Well hopefully someone has taken the time to, or there will be nasty surprises I certainly don't want people building security sensitive parts of an app to be slinging the features out.
    - znpy 3y ago
      > As someone who is hired to sling out features as rapidly as possible, that’s not going to happen. you do you, i guess. but that's where the source of truth about how oauth 2.0 works is. the "why" you're looking for it's in there.
    - deleted 3y ago
      [deleted]
  - izacus 3y ago
    That doesn't explain what the library is trying to do and how it implements it though.
Krisjohn 3y ago
I’m happy when someone explains something with words strung together into sentences, rather than code. Code is an example, an example is not an explanation. Then your examples can be simple, rather than trying to be a complete explanation of everything.
danesparza 3y ago
Yeah -- I think you just described OpenID (not OAuth). And to be honest, this is part of the problem. We use confusing (and sometimes conflicting) terminology to describe both authentication (identifying somebody) and authorization (making sure you have the right permissions to do something). More information: https://stackoverflow.com/a/1087071/19020 https://stackoverflow.com/a/1087071/19020
- eddiezane 3y ago
  I recently gave a talk on this and agree. While it was fun to learn, the difference between oauth and oidc isn't clear. Especially with what I've been referring to as oidc "wave 2" - machine to machine authentication without OAuth seemingly involved at all. https://youtu.be/nW3xK6sh1Ck https://youtu.be/nW3xK6sh1Ck
jiggawatts 3y ago
My personal frustration with the docs is that very similar words are used in sequence and for both generic and specific meanings. “The possessor of the bearer token is authorised to re-request a refresh token code cookie.” is only a very slight exaggeration. I also want to slap the Microsoft employees that use six different similar terms for three GUIDs that look identically random. E.g.: “Client ID (Principal ID)”. It’s maddening.
cryptonector 3y ago
Except HTTP prohibits copying headers from redirect responses to redirected requests. That's why OIDC exists, to deal with that by abusing URI q-params. I've an Internet-Draft somewhere to fix this by making it possible to indicate on a 3xx that this is for authentication (so copy Authorization: from redirect responses to redirected requests) and to allow 401s to have Location: headers that make it more like a 3xx, and 3xxs have WWW-Authenticate:, so you can negotiate between legacy HTTP auth and redirect-based authentication.
wildrhythms 3y ago
I completely agree. What I want 99% of the time is basically a Javadoc showing the methods, the inputs, and the outputs, and all of the types. And if there's a short summary and an example as supplemental material, that's great. Unfortunately, developers seem to think their contrived examples are a stand-in for actually documenting the methods. I deal with a lot of Javascript libraries like this and it drives me insane.
onetimeusename 3y ago
I have seen a lot of people get caught up on things like the client_id, client_secret, redirect URL, and scopes. This is relevant when you have a lot of tenancies for your customers and want them to log in via some OAuth provider. Do you create a new client_id for every tenant? Should you distribute a client_secret? Did you properly configure the redirect? Proving identity is the easy part though. Are scopes too broad or too narrow to accomplish the app's goals? Are there unintended consequences? Those kinds of things can slow down development.
arwhatever 3y ago
OAuth document writers love abstract, lofty nomenclature for everything. I like what you’ve done here with your explanation - I can practically envision a couple (or three!) literal sock puppets giving me this perfectly adequate overview.
phendrenad2 3y ago
This. Unfortunately, the problem is, the people making these tutorials don't know that OAuth is that simple. They just know how to use the library that the 3 lines of code are hidden within.
lowdownfork 3y ago
I recently did an OAuth integration with an API that documented its OAuth endpoints like all its other endpoints: including a mention of OAuth in the description but giving explanations and examples with curl, just like it would if there were no standard. It was way easier than anything else I've done with OAuth (except log in as a user).
mooreds 3y ago
Does this meet your needs: https://fusionauth.io/docs/v1/tech/oauth/ https://fusionauth.io/docs/v1/tech/oauth/ (Curious because I work for them.) I think the reason OAuth is so successful and prevalent is because it is so flexible. This let folks implement what they needed and not what they didn't. Overspecifying things didn't help SAML, after all. There are still holes and unimplemented/incompatible options. Authentication and authorization, especially across systems and organizations, is hard. Is there a simpler standard for third party delegated authorization?

garbagecoder 3y ago

Somebody print this comment out, frame it, and mail it to every major API author.

cjbgkagh 3y ago

Auth0 has a business incentive to have people think their core competency is more difficult than it is.

deleted 3y ago
[deleted]

deleted 3y ago

[deleted]

jcranmer 3y ago

In my experience with OAuth, one of the principle issues is that it's less a protocol and more a skeleton of a protocol. Actually go to the core RFCs for OAuth, and you realize that basically everything is implementation-dependent. You somehow register with the provider as a client (out of band and completely implementation-dependent). Then you ask them to log you in by sending a request to an implementation-dependent webpage, with implementation-dependent parameters (which ones are required are--you guessed it--implementation-dependent), telling them to redirect you to your page when you're done. Well, actually, that assumes you're building a website. If you're a desktop application, you'll do something else. If you're on an embedded system that can't open up a webpage, there's another option. And there's yet more flows. Which ones are supported by the provider? You guessed it, it's all implementation-dependent. Oh, and maybe you need to refresh tokens to login the future. When? If? You guessed it, implementation-dependent! It makes writing a generic OAuth client library hard because there's basically no commonality there. Really, it makes me long for Kerberos as a much saner SSO system than OAuth.

majormajor 3y ago
This is my experience. It's hard because it's very complex. As a non-domain-expert it's hard to separate necessary complexity from unnecessary complexity, but it feels like there's a lot of the latter, plus enough gotchas in the former ("oh, you didn't specify an encryption algorithm that we support in your request, and our logs are terribly unhelpful for realizing that") to make it a giant pain.
- gigatexal 3y ago
  Is Webauthn a better standard?
  - lstamour 3y ago
    Not exactly. With webauthn the complexity lies in frontend - you have to explain how and why users should use this and what it is, how to manage enrolments and so on. Touch ID, Windows Hello and Passkeys might simplify this but it is still more complex to explain to less technical customers than, say, Face ID on an iPhone app to remember your login. If you want an easy all-purpose login flow, sign in by clicking a link in email is still an easy fallback. OAuth from multiple providers also has complexity - Auth0 makes it so you have to maintain separate databases for passwords if you want to support login via OAuth and login from password. You have to link accounts to login from multiple providers. Logins are simply hard work no matter how you slice it. Eventually they will be easy but… I’m not holding my breath. :)

paulddraper 3y ago

One reason is that the protocol itself is more complicated than you've described. For example, Google won't give you a long-lived access token. You need a refresh token, and then you use that to retrieve access tokens, and continue doing that as they expire. Why? I have not a flipping idea. Please, HN enlighten me how refresh/access token dichotomy improves the API.

dflock 3y ago
It's really trying to solve a problem they created by statlessly handing out tokens instead of keeping session state on the backend - they have no way to revoke a token once issued, so long lived tokens are a liability. Solution? More complexity! Hand out very short lived tokens, along with a slightly longer lived refresh token, which only allows you get a new bearer/access token.
- rad_gruchalski 3y ago
  Don't they still require some state to be able t invalidate refresh tokens?
  - radlad 3y ago
    Yes, but checking refresh tokens will occur much less frequently than checking access tokens. So you can imagine, for example, access tokens being JWT, so they are cheap to check. But every so often you have to validate the refresh token against MySQL (or BigQuery or what-have-you), which is more expensive.
    - rad_gruchalski 3y ago
      That's all clear to me. But technically there exists a method to revoke an issued token. It's just that long lived tokens mean potentially lots of them == increased storage cost. It would be pretty silly not to check for revocation. How would one implement logout otherwise? Relying on just clearing session cookies? What if I obtained those cookies using something else than a browser and I can hold on to the cookie jar? Not checking for revocation == doing it wrong. The purpose of a refresh token to allow the app to short circuit the login process. Regardless of how long the token is issued for. It's perfectly okay to ignore refresh tokens altogether, if one wants to.

izacus 3y ago

That drove me up the wall in Python so much - ALL the documentation just described how to put a massive library into a cookie cutter example and never explained how it's supposed to work so I could debug the darn thing.

znpy 3y ago
when it comes to this kind of things there's really no way around it: you're supposed to read the RFCs: - https://www.rfc-editor.org/rfc/rfc6749.html https://www.rfc-editor.org/rfc/rfc6749.html: The OAuth 2.0 Authorization Framework - https://www.rfc-editor.org/rfc/rfc6750.html https://www.rfc-editor.org/rfc/rfc6750.html: The OAuth 2.0 Authorization Framework: Bearer Token Usage
- asdfman123 3y ago
  As someone who is hired to sling out features as rapidly as possible, that’s not going to happen. I mean, you might say “but you should” or “it would actually help” or “in an ideal world…” but it is still, realistically, not going to happen.
  - sytringy05 3y ago
    Well hopefully someone has taken the time to, or there will be nasty surprises I certainly don't want people building security sensitive parts of an app to be slinging the features out.
  - znpy 3y ago
    > As someone who is hired to sling out features as rapidly as possible, that’s not going to happen. you do you, i guess. but that's where the source of truth about how oauth 2.0 works is. the "why" you're looking for it's in there.
  - deleted 3y ago
    [deleted]
- izacus 3y ago
  That doesn't explain what the library is trying to do and how it implements it though.

Krisjohn 3y ago

I’m happy when someone explains something with words strung together into sentences, rather than code. Code is an example, an example is not an explanation. Then your examples can be simple, rather than trying to be a complete explanation of everything.

danesparza 3y ago

Yeah -- I think you just described OpenID (not OAuth). And to be honest, this is part of the problem. We use confusing (and sometimes conflicting) terminology to describe both authentication (identifying somebody) and authorization (making sure you have the right permissions to do something). More information: https://stackoverflow.com/a/1087071/19020 https://stackoverflow.com/a/1087071/19020

eddiezane 3y ago
I recently gave a talk on this and agree. While it was fun to learn, the difference between oauth and oidc isn't clear. Especially with what I've been referring to as oidc "wave 2" - machine to machine authentication without OAuth seemingly involved at all. https://youtu.be/nW3xK6sh1Ck https://youtu.be/nW3xK6sh1Ck

jiggawatts 3y ago

My personal frustration with the docs is that very similar words are used in sequence and for both generic and specific meanings. “The possessor of the bearer token is authorised to re-request a refresh token code cookie.” is only a very slight exaggeration. I also want to slap the Microsoft employees that use six different similar terms for three GUIDs that look identically random. E.g.: “Client ID (Principal ID)”. It’s maddening.

cryptonector 3y ago

Except HTTP prohibits copying headers from redirect responses to redirected requests. That's why OIDC exists, to deal with that by abusing URI q-params. I've an Internet-Draft somewhere to fix this by making it possible to indicate on a 3xx that this is for authentication (so copy Authorization: from redirect responses to redirected requests) and to allow 401s to have Location: headers that make it more like a 3xx, and 3xxs have WWW-Authenticate:, so you can negotiate between legacy HTTP auth and redirect-based authentication.

wildrhythms 3y ago

I completely agree. What I want 99% of the time is basically a Javadoc showing the methods, the inputs, and the outputs, and all of the types. And if there's a short summary and an example as supplemental material, that's great. Unfortunately, developers seem to think their contrived examples are a stand-in for actually documenting the methods. I deal with a lot of Javascript libraries like this and it drives me insane.

onetimeusename 3y ago

I have seen a lot of people get caught up on things like the client_id, client_secret, redirect URL, and scopes. This is relevant when you have a lot of tenancies for your customers and want them to log in via some OAuth provider. Do you create a new client_id for every tenant? Should you distribute a client_secret? Did you properly configure the redirect? Proving identity is the easy part though. Are scopes too broad or too narrow to accomplish the app's goals? Are there unintended consequences? Those kinds of things can slow down development.

arwhatever 3y ago

OAuth document writers love abstract, lofty nomenclature for everything. I like what you’ve done here with your explanation - I can practically envision a couple (or three!) literal sock puppets giving me this perfectly adequate overview.

phendrenad2 3y ago

This. Unfortunately, the problem is, the people making these tutorials don't know that OAuth is that simple. They just know how to use the library that the 3 lines of code are hidden within.

lowdownfork 3y ago

I recently did an OAuth integration with an API that documented its OAuth endpoints like all its other endpoints: including a mention of OAuth in the description but giving explanations and examples with curl, just like it would if there were no standard. It was way easier than anything else I've done with OAuth (except log in as a user).

mooreds 3y ago

Does this meet your needs: https://fusionauth.io/docs/v1/tech/oauth/ https://fusionauth.io/docs/v1/tech/oauth/ (Curious because I work for them.) I think the reason OAuth is so successful and prevalent is because it is so flexible. This let folks implement what they needed and not what they didn't. Overspecifying things didn't help SAML, after all. There are still holes and unimplemented/incompatible options. Authentication and authorization, especially across systems and organizations, is hard. Is there a simpler standard for third party delegated authorization?