concept capability uri in category security

This is an excerpt from Manning's book API Security in Action MEAP V11 epub. Login to get full access to this book.

When used purely to indicate the login state of a user at an API, session cookies are a relatively benign violation of the REST principles, and they have many security attributes that are lost when using other technologies. For example, cookies are associated with a domain and so the browser ensures that they are not accidentally sent to other sites. They can also be marked as Secure, which prevents the cookie being accidentally sent over a non-HTTPS connection where it might be intercepted. I therefore think that cookies still have an important role to play for APIs that are designed to serve browser-based clients served from the same origin as the API. In chapter 6 you’ll learn about alternatives to cookies that do not require the server to maintain any per-client state, and in chapter 9 you'll learn how to use capability URIs for a more RESTful solution.

REST already has a standard format for identifying resources, the URI, so this is the natural representation of a capability for a REST API. A capability represented as a URI is known as a capability URI. Capability URIs are widespread on the web, in the form of links sent in password reset emails, GitHub Gists, and document sharing as in the Dropbox example.

The desire to share access to private resources simply by sharing a URI is not new. For a long time, browsers supported encoding a username and password into a HTTP URL in the form http://alice:secret@example.com/resource
. When such a link was clicked, the browser would send the username and password using HTTP Basic authentication (see chapter 3). Though convenient, this is widely considered to be a security disaster. For a start, sharing a username and password provides full access to your account to anybody who sees the URI. Secondly, attackers soon realized that this could be used to create convincing phishing links such as http://www.google.com:80@evil.example.com/login.html
. An unsuspecting user would see the google.com domain at the start of the link and assume it was genuine, when in fact this is just a username and they will really be sent to a fake login page on the attacker’s site. To prevent these attacks browser vendors have stopped supporting this URI syntax and most now aggressively remove login information when displaying or following such links. Although capability URIs are significantly more secure than directly sharing a password, you should still be aware of any potential for misuse if you display URIs to users.

copy

Figure 9.3 In the Waterken web-key design for capability URIs, the token is stored in the fragment of the URI, which is never sent to the server. When a browser loads such a URI it will initially load a static JavaScript page that then extracts the token from the fragment and uses it to make Ajax requests to the API. The JavaScript template can be cached by the browser, avoiding the extra roundtrip for subsequent requests.

Listing 9.8 shows how to parse and load a capability URI in this format from a JavaScript API client. It first parses the URI using the URL class and extracts the token from the hash field, which contains the fragment component. This field include the literal "#" character at the start, so use hash.substring(1) to remove this. You should then remove this component from the URI to send to the API and instead add the token back as a query parameter. This ensures that the CapabilityController will see the token in the expected place. Navigate to src/main/resources/public and create a new file named capability.js with the contents of the listing.