I'm planning an API and I haven't found any information about where the access token should be placed in the response. I'm interested in the case where I'm providing the access token. What is the best practice to send the token to the clients (from the backend service)?
Should it be sent to clients in the Header or in the Body of the answer?
You should look at examples and see what others do. For example, Facebook, Twitter, Google, Amazon... and all those popular PaaS services exposing a REST API all use OAuth2 as authentication mechanism:
In OAuth2 you'll see the specification requires to send the generated token to the client in the body of a json response: https://www.rfc-editor.org/rfc/rfc6749#section-5 . But you can also see how Google and other vendors extend this mechanism so it can be sent as a callback url param, for example (Check out https://developers.google.com/identity/protocols/OAuth2UserAgent).
Once you get the authorization token you put it on the Authorization: HTTP header you send on your requests for accessing protected resources. They have to support this way of doing it, because it is how the OAuth2 standard specifies it https://www.rfc-editor.org/rfc/rfc6749#section-7
If you want to tinker a little bit more with oauth, check out https://developers.google.com/oauthplayground
(OAuth is pretty much the same thing.)
They usually also extend the Authorization header mechanism to allow the token to be provided as a GET/POST parameter in the url or the body of the response, respectively (For example, Facebook's Graph API also supports passing an access_token= parameter on your HTTP POST request body or GET URI). There is no way to manipulate or even read HTTP headers on a javascript browser application (see the modern fetch API and other proposals on Accessing the web page's HTTP Headers in JavaScript), so providing this functionality makes life easier for many app developers.
Another popular authentication scheme is SOAP authentication. It doesn't support tokens but it supports digest authentication, which is a similar thing. The interesting part of it is that it is not HTTP/Web based (although it is primarily used that way), so you can use it over other application protocols. It's a little more cumbersome, but you can find ready to use implementations for both server and client.
You can also use digest authentication over HTTP without SOAP. It is also based on Authorization: headers and every browser supports it. Check out https://en.wikipedia.org/wiki/Digest_access_authentication to see how the authorization headers are formed in different ways depending on the level of security you want to reach.
Some services, like redmine, allow you to use an API token (API key) instead of a session token. Then you can make basic http auth on your requests like https://whatever:yourapikey#example.com/protectedMethod, although passing of auth data on URLs is currently deprecated in favor of basic auth header, and plain passwords / static API keys should only be sent over secured SSL connections. In this case the client can have the server generate an api key using a web interface or a rest api (so the generated key will be passed as a JSON response). This method may not be such a good idea, though: Check http://talks.codegram.com/http-authentication-methods#/intro if you want to know why, and also this question discussing where to put them: Where should I place API keys in REST API calls?
Related
The web application framework we use has built-in support for handling Cross-site Request Forgery. This works well when data is posted with a browser to our webserver.
Currently we are developing an API in which an uploaded XML file is processed by the same application framework. Our API requires a unique token in the uploaded XML file for authentication. Since CSRF detection is enabled by default and the XML file does not contain a CSRF token we currently can not upload any data through this API.
However, we can quite easily disable CSRF detection, but is this safe?
A post here states -- quite boldly -- the following.
It is safe to remove csrf for API calls as the particular vulnerability can only be executed through a web browser.
Is this true? Can nothing similar to a CSRF attack happen through an API?
That depends on how you use the API. Say if the website using the API is vulnerable to CSRF, that means the API is also vulnerable.
Wekipedia says that
CSRF exploits the trust that a site has in a user's browser.
To support API calls the server requires that the credentials be sent along with every request (or some equivalent like digest, security handle, hash). If the credentials are stored in application memory (like mobile app) API is not vulnerable to CSRF. But if the credentials are saved in a session or cookie the API is exposed to CSRF
It depends on what you mean by "disable CSRF detection".
Some pointers:
As long as you do validate the unique authentication token without fail, then there is no way the attacker can spoof a valid request without a valid token. This is straightforward.
"unique authentication token" here refers to something that is not sent by browsers automatically. (So no using stuff like HTTP Basic / Digest, Cookie header and etc.) It must be something unique that you (the API creator) came up with. This can be as easy as an additional Foobar:the_unique_token header.
Note that it is perfectly fine to identify the client based on the Cookie (or other tokens that browsers automatically send), but you must only allow entry when the unique token is provided.
As long as the attacker can spoof a valid request as long as he is able to guess/obtain the token (the_unique_token). So the token needs to be long, random, and single-use to be secure.
I'm developing a REST API that requires authentication. Because the authentication itself occurs via an external webservice over HTTP, I reasoned that we would dispense tokens to avoid repeatedly calling the authentication service. Which brings me neatly to my first question:
Is this really any better than just requiring clients to use HTTP Basic Auth on each request and caching calls to the authentication service server-side?
The Basic Auth solution has the advantage of not requiring a full round-trip to the server before requests for content can begin. Tokens can potentially be more flexible in scope (i.e. only grant rights to particular resources or actions), but that seems more appropriate to the OAuth context than my simpler use case.
Currently tokens are acquired like this:
curl -X POST localhost/token --data "api_key=81169d80...
&verifier=2f5ae51a...
×tamp=1234567
&user=foo
&pass=bar"
The api_key, timestamp and verifier are required by all requests. The "verifier" is returned by:
sha1(timestamp + api_key + shared_secret)
My intention is to only allow calls from known parties, and to prevent calls from being reused verbatim.
Is this good enough? Underkill? Overkill?
With a token in hand, clients can acquire resources:
curl localhost/posts?api_key=81169d80...
&verifier=81169d80...
&token=9fUyas64...
×tamp=1234567
For the simplest call possible, this seems kind of horribly verbose. Considering the shared_secret will wind up being embedded in (at minimum) an iOS application, from which I would assume it can be extracted, is this even offering anything beyond a false sense of security?
Let me seperate up everything and solve approach each problem in isolation:
Authentication
For authentication, baseauth has the advantage that it is a mature solution on the protocol level. This means a lot of "might crop up later" problems are already solved for you. For example, with BaseAuth, user agents know the password is a password so they don't cache it.
Auth server load
If you dispense a token to the user instead of caching the authentication on your server, you are still doing the same thing: Caching authentication information. The only difference is that you are turning the responsibility for the caching to the user. This seems like unnecessary labor for the user with no gains, so I recommend to handle this transparently on your server as you suggested.
Transmission Security
If can use an SSL connection, that's all there is to it, the connection is secure*. To prevent accidental multiple execution, you can filter multiple urls or ask users to include a random component ("nonce") in the URL.
url = username:key#myhost.com/api/call/nonce
If that is not possible, and the transmitted information is not secret, I recommend securing the request with a hash, as you suggested in the token approach. Since the hash provides the security, you could instruct your users to provide the hash as the baseauth password. For improved robustness, I recommend using a random string instead of the timestamp as a "nonce" to prevent replay attacks (two legit requests could be made during the same second). Instead of providing seperate "shared secret" and "api key" fields, you can simply use the api key as shared secret, and then use a salt that doesn't change to prevent rainbow table attacks. The username field seems like a good place to put the nonce too, since it is part of the auth. So now you have a clean call like this:
nonce = generate_secure_password(length: 16);
one_time_key = nonce + '-' + sha1(nonce+salt+shared_key);
url = username:one_time_key#myhost.com/api/call
It is true that this is a bit laborious. This is because you aren't using a protocol level solution (like SSL). So it might be a good idea to provide some kind of SDK to users so at least they don't have to go through it themselves. If you need to do it this way, I find the security level appropriate (just-right-kill).
Secure secret storage
It depends who you are trying to thwart. If you are preventing people with access to the user's phone from using your REST service in the user's name, then it would be a good idea to find some kind of keyring API on the target OS and have the SDK (or the implementor) store the key there. If that's not possible, you can at least make it a bit harder to get the secret by encrypting it, and storing the encrypted data and the encryption key in seperate places.
If you are trying to keep other software vendors from getting your API key to prevent the development of alternate clients, only the encrypt-and-store-seperately approach almost works. This is whitebox crypto, and to date, no one has come up with a truly secure solution to problems of this class. The least you can do is still issue a single key for each user so you can ban abused keys.
(*) EDIT: SSL connections should no longer be considered secure without taking additional steps to verify them.
A pure RESTful API should use the underlying protocol standard features:
For HTTP, the RESTful API should comply with existing HTTP standard headers. Adding a new HTTP header violates the REST principles. Do not re-invent the wheel, use all the standard features in HTTP/1.1 standards - including status response codes, headers, and so on. RESTFul web services should leverage and rely upon the HTTP standards.
RESTful services MUST be STATELESS. Any tricks, such as token based authentication that attempts to remember the state of previous REST requests on the server violates the REST principles. Again, this is a MUST; that is, if you web server saves any request/response context related information on the server in attempt to establish any sort of session on the server, then your web service is NOT Stateless. And if it is NOT stateless it is NOT RESTFul.
Bottom-line: For authentication/authorization purposes you should use HTTP standard authorization header. That is, you should add the HTTP authorization / authentication header in each subsequent request that needs to be authenticated. The REST API should follow the HTTP Authentication Scheme standards.The specifics of how this header should be formatted are defined in the RFC 2616 HTTP 1.1 standards – section 14.8 Authorization of RFC 2616, and in the RFC 2617 HTTP Authentication: Basic and Digest Access Authentication.
I have developed a RESTful service for the Cisco Prime Performance Manager application. Search Google for the REST API document that I wrote for that application for more details about RESTFul API compliance here. In that implementation, I have chosen to use HTTP "Basic" Authorization scheme. - check out version 1.5 or above of that REST API document, and search for authorization in the document.
In the web a stateful protocol is based on having a temporary token that is exchanged between a browser and a server (via cookie header or URI rewriting) on every request. That token is usually created on the server end, and it is a piece of opaque data that has a certain time-to-live, and it has the sole purpose of identifying a specific web user agent. That is, the token is temporary, and becomes a STATE that the web server has to maintain on behalf of a client user agent during the duration of that conversation. Therefore, the communication using a token in this way is STATEFUL. And if the conversation between client and server is STATEFUL it is not RESTful.
The username/password (sent on the Authorization header) is usually persisted on the database with the intent of identifying a user. Sometimes the user could mean another application; however, the username/password is NEVER intended to identify a specific web client user agent. The conversation between a web agent and server based on using the username/password in the Authorization header (following the HTTP Basic Authorization) is STATELESS because the web server front-end is not creating or maintaining any STATE information whatsoever on behalf of a specific web client user agent. And based on my understanding of REST, the protocol states clearly that the conversation between clients and server should be STATELESS. Therefore, if we want to have a true RESTful service we should use username/password (Refer to RFC mentioned in my previous post) in the Authorization header for every single call, NOT a sension kind of token (e.g. Session tokens created in web servers, OAuth tokens created in authorization servers, and so on).
I understand that several called REST providers are using tokens like OAuth1 or OAuth2 accept-tokens to be be passed as "Authorization: Bearer " in HTTP headers. However, it appears to me that using those tokens for RESTful services would violate the true STATELESS meaning that REST embraces; because those tokens are temporary piece of data created/maintained on the server side to identify a specific web client user agent for the valid duration of a that web client/server conversation. Therefore, any service that is using those OAuth1/2 tokens should not be called REST if we want to stick to the TRUE meaning of a STATELESS protocol.
Rubens
The OAuth 2.0 draft v2-22 Section 3.2 says:
The client MUST use the HTTP "POST" method when making access token
requests.
However, if you look at the Facebook and Foursquare OAuth2 implementations, they ask the clients to make a simple GET request for requesting an access token. They ask the clients to place the client_id and client_secret in the URL.
I am building an OAuth 2 server and after seeing Facebook's and Foursquare's implementations, I am strongly considering also breaking the protocol to allow clients to request the access token via GET. My site's communication is using SSL, similar to Facebook and Foursquare.
So my question is this: Are there any good reasons why I shouldn't allow clients to request access tokens via the GET method over HTTPS?
The most common argument is that you should not put sensitive information in a query string (GET parameter) as Web servers typically log the HTTP request URL. POST data can be arbitrarily long, so is not usually logged. Therefore when you're dealing with something like client_secret or code (although it's one time use), it makes sense to have that passed in the POST payload.
IMHO, if you're using an OAuth 2.0 flow that doesn't require client_secret's (or you put that in the HTTP Authorization header, as recommended) - I don't see an issue with allowing GET.
I want to create a flexible API Rest server. I will allow the clients to authenticate using HTTP or an APIKEY.
My question is: what is the correct way to add the apikey to a GET request? My problem is the apikey pollutes the url.
I imagine something like this : /book/1/apikey/s4cr4t !
In my opinion you should only use the Authorization header. That's what it is there for.
Putting it in the URL is a bad idea because:
a) as you said it pollutes the URL
b) if you decide to go SSL for security then the API will still appear in log files
c) caches will end up creating multiple copies of the same representation, one for each api key.
For more information on creating your own Authorization scheme go here.
Credentials may be passed using the Authorization header:
GET http://domain.com:/book/1
Authorization: apikey="s4cr4t"
It all depends on how far you want to go but the mechanics stays the same:
Context
The goal is to identify the client with some level of security. (Note: Security is another detailed discussion). Remember that one if the “features” of REST is to be stateless: That means no session state on the server except for resources. To keep the client stateless, it needs to supply on each request enough information that the request is independent. It must give the server a way to identify the client such as a username/password, API Key or token.
You have various options to do this so here are some:
Add HTTP headers to identify the client
Here one can use the Authorization header and send it with each request. There are various authentication schemes but stick to the standard ones such as Basic Auth. Here you would probably stick to SSL. The authentication process generates a kind of token if you like.
You can also make use of a cookie. The cookie must contain no information except that it is a “pointer or key” to a stateful session resource on your server (note: session it a resource which is “rest-legal”). You can create this resource by doing a PUT (+info) with response 200 OK or POST (+info) with a response of 201 Created and Location: /sessions/123334. The session can then be validated by the server such as timeout, valid client ip address, api key etc.
With the method above, you can also define a customer header such as Api-Key: XXXX. But then you limit yourself to special client. Set-Cookie are “well known” headers so browser will handle them kind of transparently. The authentication process can then be done by following links and filling in forms (PUT + POST) to authenticate (create session resource).
Encode an identifier in the content
Here you are free to do what you want too. Just add a field/token/id to your content and let the server verify it.
A RESTful API does application flow by resolving links. See also HATEOAS and Fielding's words. This also applies when you have a separate process of logging in to the application.
Do not encode any data in the URIs. (Out of band information)
I'm building Pylons-based web application with RESTful API, which currently lacks any authentication. So I'm going to implement that and in order to avoid all the trouble and caution with storing user passwords, I'd like to use OpenID for authentication. What would be the best way to do this? Are these two things compatible? Are there existing REST APIs that use OpenID that I can take inspiration from?
I've now spent some time researching the options and would like to summarize the findings.
First, a little bit more context -- I develop and control both the service and API consumer. Consumer is Flash-based app that is served from the same host the API is now and is supposed to be used in browser. No third party clients in sight yet.
So the question can be divided in two parts,
how do I do the OpenID authentication via API
how do I maintain the "authenticated" state in subsequent requests
For first part, OpenID authentication almost always includes interactive steps. During the authentication process there will most likely be a step where user is in OpenID provider's web page, signing in and pressing some "I agree" button. So API cannot and shouldn't handle this transparently (no "tell me your OpenID provider and password and I'll do the rest"). Best it can do is pass forth and back HTTP links that client has to open and follow instructions.
Maintaining "authenticated" state
REST APIs should be stateless, each request should include all the information needed to handle it, right? It wouldn't make any sense to authenticate against OpenID provider for each request, so some kind of session is neccessary. Some of the options for communicating session key (or "access token" or username/password) are:
HTTPS + BASIC authentication ("Authorization: Basic ..." header in each request)
Signing requests Amazon-style ("Authorization: AWS ... " header in each request)
OAuth: acquire Access Token, include that and a bunch of other parameters in each request
Cookie that stores session key ("Cookie: ... " header in each request)
Signed cookie that stores session information in the cookie itself
There's just one API consumer right now, so I chose to go for simplest thing that could possibly work -- cookies. They are super-easy to use in Pylons, with help of Beaker. They also "just work" in the Flash app -- since it runs inside browser, browser will include relevant cookies in the requests that Flash app makes -- the app doesn't need to be changed at all with respect to that. Here's one StackOverflow question that also advocates using cookies: RESTful authentication for web applications
Beaker also has nice feature of cookie-only sessions where all session data is contained in the cookie itself. I guess this is about as stateless as it gets. There is no session store on server. Cookies are signed and optionally encrypted to avoid tampering with them in client side. The drawback is that cookie gets a bit bigger, since it now needs to store more than just session key. By removing some stuff I didn't really need in the session (leftovers from OpenID authentication) I got the cookie size down to about 200 bytes.
OAuth is a better fit for API usage. Here's an example of OAuth in use in Python: oauth-python-twitter. Leah Culver's python-oauth library is the canonical implementation of OAuth in Python, but python-oauth2 is a recent contender that is getting some buzz. As for inspiration, django-piston has support for using OAuth to do auth when creating RESTful APIs for Django, though the documentation isn't as nice as I'd like for that particular topic.
If you build API, you could check OAuth protocol. It's complementary to OpenID.