A common analogy for APIs is that they are LEGO blocks, or more specifically, APIs are the little studs and slots that allow you to attach LEGO pieces to each other and build something bigger than any individual piece. The LEGO pieces in this analogy would be individual services or applications that perform specific tasks of a larger service or application.
Another surprisingly accurate aspect of this analogy is that - similar to a LEGO model, where most of the studs are hidden inside the model - modern approaches to designing web-based applications have many more internal APIs than what they expose to the outside world. The sheer number of APIs presents a challenge when it comes to ensuring that they operate correctly, efficiently, and above all, securely.
The widely-accepted standard for building a web-based API emerged in the early 2000s and is called REST, Representational State Transfer, often seen as “RESTful”. Instead of being a prescriptive standard, it is more of an architectural style that emphasizes now well-proven aspects of good API design such as stateless communication, resource-oriented URLs, and using defined HTTP methods to perform operations on those resources.
REST, however, does not concern itself with security. This makes it crucial for anyone building a REST API to pay attention to securing their API from potential threats. APIs are routinely used to transfer information that should be kept secret or enable operations that have real-world effects. Not paying attention to API security could lead to sensitive data being leaked and business resources being misused or abused, incurring financial, reputational and other harm to customers and the business.
Securing a REST API can be done in many ways, such as authenticating users, authorizing access to functions and resources, encrypting the connection between the API server and end consumer, and monitoring and logging the operation of the API. To apply the correct mix of protections you need an understanding of the potential threats, sometimes called the threat model, to your API.
Recognizing Threats to REST APIs
The Open Worldwide Application Security Project (OWASP) has a separate top 10 list for API related security risks and just announced the most recent update for 2023
The easiest of these to understand is broken authentication sitting at number 2. This encompasses all cases where access is possible without having proper credentials. For example, many services (Facebook, Instagram) present you with very different views depending on whether you are signed in or not. Similarly, APIs can work differently depending on whether your requests are authenticated or not.
It is good to understand that broken authentication is not the same as broken authorization. You may need to sign in (authenticate) to a social media service to browse through posts, but you need specific permissions (authorization) to edit or publish a post. Authorization is a much richer and more complex problem than authentication, which is why it is in the number one spot on OWASP’s list. A total of three out of the top five spots are directly related to failures in authorization.
Authorization can be simple - “Only I am allowed to edit my profile”, but in real-world business cases it can be almost extremely complex - “Users in this specific group are allowed to edit this part of the document for exactly 78 hours after it has been approved and tagged with this specific tag by a user in this other group”. Because of this semantic and contextual nature, authorization can only really happen at the application layer, and apart from the very simplistic cases, it is not as easy to externalize as for example, authentication is to third-party identity providers.
Fortunately, there are standard industry best practices for dealing with all of the other issues on the OWASP list.
Best Practices for Securing REST APIs
Management-Level Security Practices
The very first and most important item is visibility. This may sound trivial, but ”ghost” APIs can be serious problems. Imagine, for example, an API deployed in a staging or testing environment that has access to production resources but uses a mock or dummy authentication service. Even in the best case scenario, where the API itself operates correctly, it may not be logged or monitored properly leading to regulatory or financial risks.
After visibility comes “inventory”. This means the systematic documentation and lifecycle management of the APIs. An API is rarely created perfectly from the start, and without proper processes and tools to deploy, change and deprecate your APIs you can easily end up in a situation where you lose visibility.
Next is posture management. One of the benefits of having an API inventory is that it allows you to define and manage security policies which can then be monitored and enforced. In practice, you can make a good start on both inventory and posture management by simply writing out an OpenAPI specification for your API. Secondly, you can monitor your APIs for the risk factors in the OWASP Top 10.
Application-Level Security Practices
Having an OpenAPI spec of your API also helps with many of the other security best practices, since it allows you to use automated and standardized tools that can take advantage of the OpenAPI spec. For example, it is easy to define commonly used authentication methods such as OAuth, Basic authentication or key based authentication (using e.g. JSON Web Tokens) in your OpenAPI spec. You can mix and match and define these on a per route and method basis and with a properly set up OpenAPI spec you can then use drop in tools to ensure every request is properly authenticated according to your policies.
Once you have set up authentication, you should ensure that any secrets (tokens, passwords, encryption keys) are sufficiently strong, not stored in plaintext, and rotated frequently. Also, regardless of how you authenticate requests, the authentication context should be attached to the request in a standardized way. This makes it easier to write application logic that deals with authorization.
OpenAPI will also allow you to easily implement and automate good practices such as input validation and coercion, output validation, input/output encoding, and error handling. There are, however, some things that the OpenAPI spec will not help you with, and you should take care to ensure that there are controls in place for rate limiting and pagination to prevent the excessive return of data in any one call or programmatic set of calls. This will limit the blast radius of a potential breach.
Monitoring and logging are also not part of the OpenAPI spec but are an integral part of the secure operation of an API. Specifically logging and runtime protection related to authorization must be implemented in the application layer. It can’t logically be done based on the request alone (for example, at the network layer, or during authentication), and once the response is sent it is too late for preventative measures.
Operations-Level Security Practices
Other practical considerations when building/deploying your API are: using secure connections (HTTPS) to protect any data in transit, deploying firewalls at the network edge, using load balancers and API gateways to abstract away the server layer.
All of these are universally available at any of the larger Cloud Service Providers. Similarly more advanced protection such as intrusion detection, anomaly detection and DDoS protection are easy to turn on and are free or inexpensive.
Security Practices Across All Levels
To help you decide which of the above things to spend your time and effort on, you need regular Threat Modeling and Vulnerability Assessments. A threat model helps you understand the context and severity of potential issues. For example, the threat model for a quick student toy project is very different from the threat model of an online bank. In one case, you can skip most of the items discussed above, and in the other you may need to invest in security reviews at every stage of the API’s development.
Vulnerability assessments can include steps such as static code analysis and similar security testing tools, or activities like reviewing the architecture of the infrastructure around the API with the appropriate key stakeholders, who can identify points of risk or failure connected to the API. It can also include a review of the business logic of the API and the logical data flows to eliminate potential design flaws.
The technology trends from the last several years indicate that we have not yet reached “Peak API”. Current application design patterns and the ever expanding need to provide more and better services online, mean that the ability to build and operate APIs safely and securely is critical for any business.