Taking a new look at security in RESTful API design
REST appears to be sure-handedly winning the API war with SOAP, so it's time to start learning about REST security. We explore this protocol's latest security developments.
The catfight between SOAP and RESTful Web services has pretty much been settled in favor of REST, with the recent trend of cloud providers, such as Amazon and Google, moving their APIs from SOAP to REST. According to ProgrammableWeb, which has been tracking SOAP and REST APIs available to the public since 2005, REST now represents over 70% of public APIs.
The movement away from on-premises enterprise apps and toward cloud computing and microservices is almost certain to make REST the future dial tone for systems interaction. So, it's important that developers and architects stay tuned in to what's new in RESTful API design, especially when it comes to security. The recently revised OWASP REST Security Cheat Sheet recommends 19 best practices for securing RESTful apps, but in this post, I'll focus on two key security challenges REST API developers must face: authentication and authorization.
Token, token, who's got the token?
Because more and more cloud data is moving through APIs, rather than the browser, developers need consistent and secure methods to access and manipulate cloud-hosted services. For SOAP-based APIs, standards like WS-Trust and WS-Security have been used to define how clients of the APIs are authenticated. The OAuth 2.0 standard published in 2012 provides the same functionality in the RESTful API world as WS-Trust and WS-Security provide for SOAP APIs. Specifically, it provides a standardized mechanism to allow API clients to manipulate authentication tokens through the four main HTTP methods -- GET, PUT, POST and DELETE.
Because more and more cloud data is moving through APIs, rather than the browser, developers need consistent and secure methods to access and manipulate cloud-hosted services.
When threading security into your RESTful API design, developers need to take into account who's using what API, when and for what purpose. The distinction between authentication and authorization is important in understanding why API connection attempts are either accepted or denied. Authentication is verification of credentials or proving correct identity. Authorization is verification that the connection attempt is valid and certain actions are allowed. Authorization occurs after successful authentication: An API might authenticate an end user, but not authorize that end user to make certain requests.
REST developers have a few different options for using authentication in Web-based RESTful API design. One option is to use public and private keys in the form of Hash-based message authentication code (HMAC) that is sent back and forth with each request from client to server.
A second way is to use OAuth 2.0, an open standard for delegating authorization for accessing resources, commonly used as a way for Internet users to log in to third-party websites using their Microsoft, Google, Facebook and Twitter accounts, among others, without exposing their passwords. Designed specifically to work with HTTP(S), OAuth essentially allows access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner. The third party then uses the access token to access the protected resources hosted by the resource server. This kind of authentication is useful in social media services, such as Twitter, Facebook or Google, among others, where the service owns some private data like contacts lists or photos that can be shared with other applications without putting the user credentials at risk.
Two-legged or three-legged OAuth
The number of legs used to describe an OAuth request refers to the number of parties involved. Three-legged OAuth refers to the fact that there are three entities -- a user, a client or application and a server or service -- involved, and both the user and the app are identified by their credentials. Two-legged OAuth refers to a request where an OAuth signature method is being used to identify just the application -- that is, to identify just the client and not the user. This is often done using Secure Sockets Layer and HMAC authentication code. This kind of authentication is typically used in cloud computing data applications, like Amazon Web Services, that use a key to identify the owner of the data and what AWS offerings are being provided. The recent Hawk specification on GitHub is an attempt to standardize an HMAC authentication format for securing RESTful Web APIs.
If your REST API needs to authenticate end users, the three-legged flow of OAuth 2.0 is recommended as a best practice when building native apps. The latest evolution of the OAuth protocol, OAuth 2.0, includes an OpenID Connect identity or authentication layer on top of an OAuth 2.0 authorization framework. OAuth 2.0 introduces the notion of long-lived refresh tokens, which allow for more complex authorization implementations. A common refresh token scenario allows website A to make a request for a new access token on behalf of the user to website B without the user having to reauthorize with a username and password once the original access token expires.
The OpenID protocol revives the long-lost notion of refresh tokens
OpenID Connect uses straightforward REST/JSON message flows with a design goal of "making simple things simple and complicated things possible." Google is one of several social media providers that offers libraries, products and tools that developers can use to implement the OAuth 2.0 family of specifications. The Google OAuth 2.0 system supports server-to-server interactions like those between a Web application and a Google service, such as the Google+ social network. The OAuth 2.0 system allows developers to use access tokens to call Google APIs either by using client libraries in Java, Python or other languages, or by directly interacting with the OAuth 2.0 system using HTTP. This flexibility comes with the following warning, however:
"The mechanics of server-to-server authentication interactions require applications to create and cryptographically sign JSON Web Tokens, and it's easy to make serious errors that can have a severe effect on the security of your application. For this reason, we strongly encourage you to use libraries, such as the Google APIs client libraries that abstract the cryptography away from your application code."
Google also provides an OAuth 2.0 Playground, where developers can experiment with OAuth 2.0 and the APIs that support it. Here's a step-by-step walkthrough, Using OAuth For Your JavaEE Login, which details how to use Google's OAuth2 provider for authentication and authorization.
Another resource for securing REST APIs is Spring Security OAuth, which provides support for adding OAuth 1a (two-legged OAuth) and OAuth2 security to applications built with the Spring framework.
