REST API Login Pattern
I am creating a REST api, closely following apigee suggestions, using nouns not verbs, api version baked into the url, two api paths per collection, GET POST PUT DELETE usage, etc.
I am working on the login system, but unsure of the proper REST way to login users. I am not working on security at this point, just the login pattern or flow. (Later we will be adding 2 step oAuth, with an HMAC, etc)
Possible Options
- A POST to something like
https://api...com/v1/login.json - A PUT to something like
https://api...com/v1/users.json - Something I have not though of...
What is the proper REST style for logging in users?
Answer
Principled Design of the Modern Web Architecture by Roy T. Fielding and Richard N. Taylor, i.e. sequence of works from all REST terminology came from, contains definition of client-server interaction:
All REST interactions are stateless. That is, each request contains all of the information necessary for a connector to understand the request, independent of any requests that may have preceded it.
This restriction accomplishes four functions, 1st and 3rd are important in this particular case:
- 1st: it removes any need for the connectors to retain application state between requests, thus reducing consumption of physical resources and improving scalability;
- 3rd: it allows an intermediary to view and understand a request in isolation, which may be necessary when services are dynamically rearranged;
And now lets go back to your security case. Every single request should contains all required information, and authorization/authentication is not an exception. How to achieve this? Literally send all required information over wires with every request.
One of examples how to archeive this is hash-based message authentication code or HMAC. In practice this means adding a hash code of current message to every request. Hash code calculated by cryptographic hash function in combination with a secret cryptographic key. Cryptographic hash function is either predefined or part of code-on-demand REST conception (for example JavaScript). Secret cryptographic key should be provided by server to client as resource, and client uses it to calculate hash code for every request.
There are a lot of examples of HMAC implementations, but I'd like you to pay attention to the following three:
- Authenticating REST Requests for Amazon Simple Storage Service (Amazon S3)
- Answer by Mauriceless on quiestion: "How to implement HMAC Authentication in a RESTful WCF API"
- crypto-js: JavaScript implementations of standard and secure cryptographic algorithms
How it works in practice
If client knows the secret key, then it's ready to operate with resources. Otherwise he will be temporarily redirected (status code 307 Temporary Redirect) to authorize and to get secret key, and then redirected back to the original resource. In this case there is no need to know beforehand (i.e. hardcode somewhere) what the URL to authorize the client is, and it possible to adjust this schema with time.
Hope this will helps you to find the proper solution!