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)
Related
I wrote some API. It requires an API token.
I only access this API through backend.
Should I receive the API token through headers only, or is it ok to receive it from query string parameters?
Are there differences security-wise?
Edit: forgot to mention, of course I use SSL
All the Authorization is in Headers only headers are more secure
In query parameter these are expose for the public
for eg. if you send in Like a query it will be public to all
Don't do this Ever
curl -X GET http://localhost:5051/v1/user/verifytoken?token=bearer-xdrRxfdfdfdf
You may need a refresher on the differences between cookies and tokens to assist you in finding your answer.
The purpose of cookies is to bring state to what is inherently a stateless protocol which is http, the http protocol has no concept of state and it's only by introducing these cookies or tiny bits of data on requests that identify us to the server.
Cookies are included on all http requests by default, they manifest themselves as a property on the header of any request. A server can choose to place information on a users cookie that identifies them uniquely to that particular server.
So if they were logging into a website I were making I could stick some information into that cookie that says this is user13794 and on any follow up request they would have a cookie 13794 that says this is the same user coming back, it's another request from the same person.
Cookies are automatically included on all requests and very importantly, are unique to each domain, such as Google.com versus eBay.com. A cookie you have that is tied to google.com is not and cannot be shared by default with ebay.com, that is how we get some level of security on all of our requests. So if I logged on to google.com and then went to hacker.com, the hacker.com website could not lift my cookie from Google and hijack my session.
SO cookies cannot be sent to different domains, that is something that exists for security purposes so you cannot easily hijack peoples sessions.
Opposed to cookies are the ideas of tokens, this was introduced as a convention, to use tokens in place of cookies where cookies stop being useful.
There is nothing done automatically for us with tokens, we have to manually include a header with our token which might be a string of letters and numbers and we might include it on a specific header so we have to manually wire up our tokens at all times.
The benefits of tokens is that we can send them to any domain that we wish, so if I am on google.com and I want to make an authenticated request to an entirely different domain, I can do so by using a token.
I would make my request to that other domain, include my particular token and boom! I am authenticated on that other domain.
So that's my long winded way of saying, like with cookies, tokens are manually wired up through headers only, not query parameters.
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?
I've setup security in my RESTFUL WCF services using Custom Basic Authentification (thus desactivating the iis Basic Authentification and not using Windows Accounts Login at all; my service is hosted by iis) using the following link.
blog link
I understand the consumers have to implement a client to pass credentials in the request header.
It is 64bits based encoded and we can see credentials passing in firebug network tab while debugging (it is always the same string encoded <=> same credential .......)
So, in addition, to enforce security I will add SSL to encrypt the url :
https://myrestfulserviceurl.com/Method
Now the consumers ask me why we don't just put the login and password in the url request i.e
https: // myrestfulserviceurl.com/Method?login=XXX&password=YYY
(also combined with SSL)
Thus the change requires to add login and password as parameters in my Operation Contract and call a method for authentification in my method "Method".. etc etc
My question is :
What is the difference (both scenarii will use ssl) between Custom Basic Authentification (credentials in request header) & simply passing credentials in url in param ?
I mean : I'm just asking myself why I do bother to implement Basic Authentification. Passing credentials in url or in header look similar : it's passing stuff in the request. But talking in term of security, it looks the same ?
Basic Authentification looks not more secure excepted the 64bits based encoding.
Correct me if i'm wrong.
I am just looking a reason why implementing Custom Basic Authentification.
Any idea/advise?
Thanks
The main difference that comes to mind is to do with how visible the data is and how long it is likely to be retained.
For instance, assuming SSL is terminated at your application server, values in the get parameters are likely to be automatically logged to your file system (in request logs for instance). Having usernames and passwords in there is not ideal as it makes it much easier for them to be leaked.
If SSL is terminated at a loadbalancer or some similar proxy, then the usernames and passwords could be saved in request logs on servers you may not be thinking about and probably have less control over.
By contrast, the Authentication header is much less likely to be logged to places you're not expecting.
I thought about doind this myself and decided against it because i wanted the Restful URL's to focus only on the operations and keep security out of it, for example I might want to re-use the same code on a different application.
Also Im not sure but i think there could be a security implication concerning replay attacks, if someone obtained the link then they could execute it in any http client. If you used the authroisation attribute in the http header you could avoid this by putting an expiration on it. Also i think its better to hide this information from the html page body.
The dude who wrote this http://lbadri.wordpress.com/2012/07/30/anatomy-of-a-simple-web-token-swt/, which is taken from his book "Pro ASP.NET web Security". Gives a pretty decent example of creating a token which you could then use in the http header "Authorisation", like: Authorization: Basic d2FsaWRAGssSGZ21haWwuY29tOn236dhbGlk
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
I am currently working on a REST library for .net, and I would like to hear some opinions about an open point I have: REST and authentication.
Here is an example of an RESTful interface used with the library:
[RestRoot("/user")]
public interface IUserInterface
{
[RestPut("/")]
void Add(User user);
[RestGet("/")]
int[] List();
[RestGet("/get/{id}")]
User Get(int id);
[RestDelete("/delete/{id}")]
void Delete(int id);
}
The server code then just implements the interface and the clients can obtain the same interface through a factory. Or if the client is not using the library a standard HTTP request also works.
I know that there are the major ways of either using HTTP Basic Auth or sending a token to requests requiring authenticated users.
The first method (HTTP Basic Auth), has the following issues (partly web browser specific):
The password is transmitted with every request - even with SSL this has some kind of "bad feeling".
Since the password is transmitted with a request header, it would be easy for an local attacker to look at the transmitted headers to gain the password.
The password is available in the browsers memory.
No standard way to expire user "sessions".
Login with a browser interrupts the look and feel of a page.
The issues for the second method are more focused on implementation and library use:
Each request URI which needs authentication must have a parameter for the token, which is just very repetitive.
There is a lot more code to write if each method implementation needs to check if a token is valid.
The interface will become less specific e.g. [RestGet("/get/{id}")] vs. [RestGet("/get/{id}/{token}")].
Where to put the token: at the end of the URI? after the root? somewhere else?
My idea was to pass the token as parameter to the URL like http:/server/user/get/1234?token=token_id.
Another possibility would be to send the parameter as an HTTP header, but this would complicate usage with plain HTTP clients I guess.
The token would get passed back to the client as a custom HTTP header ("X-Session-Id") on each request.
This then could be completely abstracted from the interface, and any implementation needing authentication could just ask which user the token (if given) belongs to.
Do you think this would violate REST too much or do you have any better ideas?
I tend to believe that authentication details belong in the header, not the URI. If you rely on a token being placed on the URI, then every URI in your application will need to be encoded to include the token. It would also negatively impact caching. Resources with a token that is constantly changing will no longer be able to be cached. Resource related information belongs in the URI, not application related data such as credentials.
It seems you must be targeting web browsers as a client? If so you could investigate using HTTP Digest access authentication or issuing clients their own SSL certificates to uniquely identify and authenticate them. Also, I don't think that session cookies are necessarily a bad thing. Especially when having to deal with a browser. As long as you isolate the cookie handling code and make the rest of the application not rely on it you would be fine. The key is only store the user's identity in the session, nothing else. Do not abuse server side session state.
If you are targeting clients other than the browser then there are a number of approaches you can take. I've had luck with using Amazon's S3 Authentication mechanism.
This is all very subjective of course. Purity and following REST to the letter can sometimes be impractical. As long as you minimize and isolate such behavior, the core of your application can still be RESTful. I highly recommend RESTful Web Services as a great source of REST information and approaches.
I agree with workmad3, if session life time needs to be maintained you should create a session resource. Post on that resource with user credentials (either basic authentication or credentials in the body content) will return unique session id. Delete on /session/{id} will log out the user.
If you want to control the session expiry time. When creating new session (post on session resource) the server will set a cookie on the response (using standard set-cookie header).
The cookie will contain expiry time. The cookie string should be encrypted on the server, so only the server can open that cookie.
Every consequent request to the server will send the session cookie in the cookie header. (it will be done automatically for you if your client is a browser). The server needs to "renew" the cookie for every request, i.e. create new cookie with new expiry time (extend session's timeout).
Remember to clear the cookie when the user calls delete on the session resource.
If you want your application to be more secured you can store the client IP in the cookie itself, so when a request arrives the server can validate that it was sent from the "original" client. But remember that this solution can be problematic when proxies are involved, because the server might "see" all the requests as coming from the same client.
The rest authentication I've seen treats the sessions as a REST resource for creation, destruction etc. and then the session ID is passed to and fro. The ones I've seen tend to use the session cookie for this as it's the only way to secure it really. If you pass the session id in the URL, you don't have any way of really authenticating it came from the correct client.
Authentication is a tricky problem with REST though, as it requires some form of state to be kept outside the URL which infringes upon REST principles of the URL being all that is required to represent state.