Thoughts on authentication

[rudolphfroger]

I'm missing a paragraph on how authentication should be done. The paragraph on "Provide executable examples" mentions using a token with the comment "acquire from dashboard".

Thanks!

[nsoufr]

+1 —
Sent from Mailbox

On Wed, Jun 18, 2014 at 3:41 AM, Rudolph Froger [email protected]
wrote:

I'm missing a paragraph on how authentication should be done. The paragraph on "Provide executable examples" mentions using a token with the comment "acquire from dashboard".

Thanks!

Reply to this email directly or view it on GitHub:
#25

[geemus]

Oops, obviously this is too tightly coupled to the Heroku case. I'll try to expand on it in the near future for you. Thanks for pointing this out as something that needs attention.

[rstacruz]

👍 as well. I really like the curl -is https://[email protected]/ example given, and I think a paragraph to explain that would be great.

[geemus]

In our case we have a couple ways it can be done. One is out-of-band (either from the website or via tools) and the other is via the API itself. In the API case we have a special login endpoint that you can call using your username and password (and you get a token back in return). Hopefully that clarifies at least a bit. The dashboard specific part here is certainly overly specific, but I'm not sure how best to generalize. Maybe if we just changed it from TOKEN to CREDENTIALS and noted that the means of acquiring this and format varies. I certainly think there is some advantage to a token in addition to user/pass though, so perhaps that at least is worth calling out. What do you all think?

[rstacruz]

Sounds good — those are the cases I've encountered as well.

As for passing tokens, I've seen a few ways people tend to do it so far, and I'm not sure what's the best approach. It'd be nice to have guidelines on them.

• Pass it as a GET parameter, e.g., http://api.service.com/users?token=$TOKEN
• Pass it as a custom HTTP header, e.g., X-Auth-Token: $TOKEN
• Cookies?
• HTTP basic auth?

[geemus]

I lean somewhat towards basic auth for ease of use, as pretty much everything supports it. Plus you can technically pass it either with the host as above or in the headers if you really prefer. It also seems likely to do a good job of supporting both programatic and browser-based access (where other things may not do so as well). What do you think?

[rstacruz]

I'm all for basic auth — it's just what feels right. I don't know how to properly implement it though. Is it simply passing the token in the Authorization header, eg, Authorization: deadc0ffeebeef?

[geemus]

@rstacruz sure. It depends. There are a couple ways you can use it (at least with most libraries/frameworks). The first is simply embedding it in the url, so stuff like https://USER:[email protected]. A lot of clients and servers will just "do the right thing" with that. Under the covers, it can also be communicated more explicitly using the authorization header, though slightly different than your example, as Authorization: Basic BASE64(USER:PASS). Note that in both cases it has user/pass separated by a colon. If you just have a token, you can simply omit one. ie in the Heroku case we allow you to omit the username (so it becomes just :PASS). Does that make it clearer?

[rudolphfroger]

Basic authentication is certainly the easiest but has the disadvantage of transferring the API key with every request. One might also consider other approaches like authenticate with the API key once per 'session' and then use a returned session id for subsequent requests (similar to how authentication for 'normal' users with web browsers works).

Another approach might be to use TOTP/HOTP/OCRA based authentication (the three OATH standards) so the API key is never included in the API requests.

TLS client certificate authentication could also be an option. This has the advantage that many HTTP client libraries already have support for client certificates.

When implementing something like session IDs or one of the OATH standards, one might want to supply a small 'curl' wrapper script to make it easier for developers to play with the API. Providing small implementation examples in various programming languages also helps the inexperienced developer.

[geemus]

@rudolphfroger those are definitely interesting options. I guess I haven't seen a lot of reason to prefer those somewhat more complicated options over basic auth. The exception is for cases like OTP where you want to provide a time-limited token. I think you can still pass that token around via basic though, for simplicity. Are there cases I'm not thinking about where more session based usage would be important? Beyond the insecurity of passing the token around each time, are there other concerns?

[rudolphfroger]

Security is my main concern with regards to authentication of API's. API's are made to easily retrieve large amounts of data and/or execute many powerful actions, most of the time much easier than via the web interface.