It wasn’t too long ago that building a distributed application meant you’d implement a SOAP based web service. At that time, web based interfaces were based on some pretty heavy standards forming a stack colloquially known as “WS-*.”
But, over the last 10 years there has been a dramatic shift away from the WS-* world. Instead, developers have embraced a more organic, flexible and less prescriptive system of design. The ‘web API’ as it has become known, requires adherence to the HTTP and URI specifications only. The rest of the decisions about how the interface looks or works are up to the individual API designer.
This freedom has allowed good designers to create simple and easy-to-use APIs that adopt popular conventions. But, the lack of clear guidance for solving specific problems in a uniform way can become problematic.
One domain that is challenging for Web API designers is the security space. The old WS-* stack provided specifications designed to solve common security requirements. But, in the new world, the guidance is less clear.
Security remains an important and non-negotiable requirement for serious API implementations. At the top of the list is the need to keep data private and restrict access to those legitimate users who are doing legitimate things.
A new set of standards have emerged to solve these age old security problems for the HTTP API domain. While it has traditionally been a volatile and fragmented space, there is now a growing consensus on the specifications that are essential. This emerging convention is an early indicator of a new security stack for this generation’s API designers.
In this article we will review the security standards that have risen to the top of the heap. If you are designing a web API in 2015, these are the ones you should be staying on top of and implementing.
HTTPS (TLS)
Implementing HTTPS instead of HTTP has become a kind of minimum viable security for the web. There are a few cases where TLS is impractical, but chances are that your specific API implementation is not one of them. Interfaces that power web or mobile based clients need to use TLS. Securing the pipe and keeping data confidential in transit is critically important.
In theory it should be simple to use HTTPs. This is old technology and any production grade server, framework or library will support TLS with ease.
In reality, configuring a TLS server securely presents a real challenge. There has been a rash of highly publicized attacks on the protocol and a weak implementation is a security risk.
Over the last five years, researchers have demonstrated attacks on the certificate authority system, a popular TLS library, cryptographic algorithms and even the way the protocol itself works. All of this presents a massive attack surface for exploitation.
None of this means that you should give up on using HTTPS for your API. But, it does mean that you have to be careful how you configure and implement your TLS infrastructure.
A good resource for learning how to setup TLS securely is the Open Web Application Security Project (OWASP).
HTTP Core Security
The beauty of using the HTTP specification as a basis for API design is the wealth of functionality available. While it may not help you decide if your URI should be capitalized, the specification provides solutions to many common API design challenges.
Security is provided for as well. If you are trying to protect access to an API, HTTP provides an authentication framework and defines the Basic and Digest authentication schemes.
Basic authentication is a simple way of passing username and password credentials over HTTP. This scheme is popular on the web and its familiarity makes it an attractive option for web API designers.
One of the limitations of the Basic auth scheme is that passwords are sent in clear text over the wire on every request. This makes it easy for an eavesdropper to steal passwords from an API interaction. But, APIs that use TLS have less exposure because the data is encrypted in flight.
A bigger hurdle is the complex trust relationship involved in an open distributed application. Basic auth is designed to support two actors: a client and a server. But, many APIs exist in more complex interaction environments with varying degrees of trust between parties.
Consider the example of an API for a file storage system:
Users of the file storage system will likely want to manage their files in many different ways across a variety of platforms. To support this diversity, the file storage system might expose an API to third parties. This API platform would allow developers to build new and interesting user interfaces for the system.
The benefits to the user are great, but so are the potential risks. Can the end users trust these third party applications to manage their file resources? Does the API owner have some responsibility to ensure that user credentials are managed properly? How can access to the resources be revoked at a client application level?
This is the challenge of access delegation, and HTTP and Basic authentication are of limited help. It turns out that there are better options for securing access to web based APIs today.
OAuth and Friends
In the beginning, cloud based service providers were each solving this problem of access delegation in their own way. Eventually, a few of them got together and created the OAuth standard to provide a uniform solution.
This was a great step forward for the world of Web APIs. It meant that app developers would no longer have to learn a unique delegation method each time they encountered a new API. Unfortunately, the first version of OAuth wasn’t easy to implement on the client side. It required a non-trivial cryptographic implementation for the client, resulting in a more difficult learning curve for developers.
OAuth 2.0 solves this usability problem by utilizing bearer tokens instead of cryptographic signatures. A bearer token is a string that allows the holder (or bearer) to gain access to a protected resource. For client application developers this means that there is no longer a cryptographic implementation required, greatly simplifying the cost to gain access to the API.
But, the past two years have been a difficult time for anyone who has had to decide which type of access control to implement on their interface. OAuth 2.0 is not backwards compatible with OAuth 1.0, forcing API owners to make a big bet – implement OAuth 1.0 and risk the cost of making a breaking change in the future or implement the newer OAuth 2.0 and risk using a less popular standard.
Thankfully, the dust has now settled and OAuth 2.0 has become the defacto delegated access standard for APIs. If you are implementing a new web API this is the standard to use for access control. The tooling and library support continues to improve and the level of client side developer familiarity has grown immensely.
Unfortunately, the OAuth 2.0 specification is complex on the server-side. With four different modes of operation supported and many of the details left to the implementer, it can be frustrating standard to use in practice. Worse, mistakes made in OAuth 2.0 implementations can lead to serious vulnerabilities. As a result, API providers are increasingly using dedicated API gateway components which provide strong OAuth 2.0 enforcement.
One advantage inherent with the lack of prescription in the OAuth 2.0 specification is that it has become a framework rather than a stand-alone solution. New standards that solve more specific problems can be built on top of it while leveraging the benefits of the protocol itself.
Open ID Connect is an example of a security specification that has done exactly that. While you could use OAuth to authenticate end users, the Open ID Connect protocol provides a much more powerful and prescriptive solution. This opens the door to federated authentication on the web in a standards based manner.
In the future, we may see additional OAuth 2.0 sub-protocols that solve specific domain problems. The increasing popularity of OAuth 2.0 means that standards like Open ID Connect can be introduced with less of an implementation cost.
JW-*: The Empire Strikes Back
One of the other underpinnings of Open ID Connect is the JSON Web Token (JWT) standard. This is a security standard that is gaining momentum in enterprise solutions and may become a core component of the new API security stack.
JWT is a part of a set of IETF cryptographic standards for JSON that includes signing (JWS) and encryption (JWE). They are powerful because they standardize these common security operations in a compact, JSON friendly way that is well suited to modern web API interactions.
The set of JW-* standards is similar in spirit to the WS-* stack that were used in SOAP based service implementations. But, these JW-* standards are designed for the web, JSON and for size constrained URIs. They are also meant to be simpler and easier to use than their predecessors from the XML world.
The popularity of OAuth 2.0 has made the bearer token a common feature of secure API implementations. These standards provide much needed prescription for the tokens themselves.
The Future
We know that innovation will continue and that there is room for better solutions to the security challenges we face in API design. While it is impossible to predict exactly what will change, here are two interesting technologies that are worth keeping an eye on:
- Oz:
One of the events that stood out during the development of the OAuth 2.0 specification was the dramatic departure of one of the core standards group members. Citing his displeasure with the direction of the project, Eran Hammer left the team in 2012. In the two years since leaving, he has been working on a new delegation system called Oz. If successful, Oz and its underpinnings Iron and Hawk could become a legitimate alternative to OAuth 2.0.
- Macaroons:
Macaroons are a new type of token that can store embedded access rules. These are bearer tokens than can package fine grained access and validation policies into a single secure package. In practice, this means that a macaroon could be used as an OAuth 2.0 bearer token. The benefit being that many of the validation steps required to keep OAuth implementations secure can be serialized in the bearer token itself.
The XACML and SAML standards were developed to solve similar problems, but Macaroons are designed specifically for the web and have the backing of Google. It is early days, but it is certainly conceivable that their usage will spread.
Securing an API in 2015
If you are responsible for securing your web API, you now have an emerging security stack to implement. Use TLS to secure the point to point channel, OAuth 2.0 for delegated access control, Open ID Connect for authentication and JWT for tokens.
Even as new standards, technologies and advice emerge, one thing will remain constant: specifications are tools to help secure your interface, but it is the actual implementation that will determine your level of risk. No matter which security standards you choose to use, make sure your building your API safely.
About the Author
Ronnie Mitra is the Director of API Design in the CA Technologies API Academy. In this role, Ronnie helps companies leverage their burgeoning API potential with effective interface design. Follow Ronnie on Twitter @mitraman.
More articles in this series:
- The New Frontier of ‘Software-Defined Everything’
- Love, Marriage and Open APIs
- Event Horizon – The Future of APIs in the Internet of Things
- The Vision of Kay and Fielding: Growable Systems that Last for Decades
- Why APIs Are Critical for IoT Success
- Three Letters That Are Key to Driving Digital Transformation: A-P-I
