Understanding APIs

With our understanding of the role APIs play and the security challenges associated with them, let’s take a deeper look at how APIs work in much more detail. By the conclusion of this chapter, you will have a full understanding of how APIs work, starting with the transport protocol and the choice of APIs available to developers. The two central tenets of API security are authentication and authorization—we will cover these in detail to understand their pivotal role. Finally, you’ll understand how keys and tokens are used in ensuring the security and integrity of APIs and the identity of API clients.

In this chapter, we’re going to cover the following main topics:

• The fundamentals of HTTP
• The different types of APIs that are currently in use
• Authentication best practices and methods
• Authorization best practices and methods
• Using tokens and keys

Understanding HTTP fundamentals

APIs are built on top of the Hypertext Transfer Protocol (HTTP), which in turn uses the Transport Control Protocol (TCP) as a transport layer providing guaranteed error-free data delivery. HTTP was originally designed for the transfer of hypertext documents (such as HTML files) but has been adapted for many other uses due to its ubiquity across systems and because it is generally accessible through firewalls and routers, avoiding the use of custom ports or protocols.

HTTP comprises a few core elements, which we will discuss in the following sections.

Uniform Resource Locator

The Uniform Resource Locator (URL) is the address of a resource (file, JSON record, image, etc.) on the internet. URLs are unique (can only reference a single resource) and are fully qualified (meaning they can be resolved to the resource location without ambiguity).

The generic form of a URL is shown here:

scheme://host[:port]/path[?query-string][#fragment-id]

The...

Exploring the types of APIs

Given our understanding of the basics of HTTP, let’s explore the most common types of API currently in widespread use. We will take a deeper look at the basics of the protocols, their typical use cases, and their strengths and weaknesses. Let’s dive in!

REST

REST is the acronym for REpresentational State Transfer and an architectural style for transferring hypermedia content over HTTP. REST does not specify a rigid standard, but rather a guideline to be followed, encapsulated by six principles:

• Uniform interface: The server should present a uniform interface to the client – namely, the interface should be identical across all client devices and platforms.
• Client-server: There are two clear roles in REST: a client requesting and receiving data, and a server responding and sending data. No other roles are defined.
• Stateless: REST is stateless, meaning that each individual request does not depend on preceding or subsequent...

Access control

The foundation of API security is access control, which comprises two elements—authentication verifies who accesses an API, and authorization determines what they may do.

Beware of mixing up authentication and authorization concepts

Although the two concepts are closely related and used in conjunction to provide secure and granular access to an API, they are distinctly different. Authentication is about establishing the identity of a user or client and whether they are who they say they are, usually by means of a set of credentials. Authorization determines what access to resources a user or client is permitted based on who they are (established via authentication).

No authentication

Public APIs intended for read-only access may not require authentication if they are intended for anonymous (unauthenticated) access. Typically, these endpoints are used for information or status, for example, a status API for an online service.

HTTP authentication

...

Using JWTs for claims and identity

In API access control, JWTs are used to transfer information between the client and server in a portable and robust manner. A JWT is cryptographically secure, allowing a client to verify the integrity of the message using public-key cryptography. The JSON format allows for easy transmission as part of the request header or body.

A JWT comprises three parts: the header, the claim, and the signature (hash-based message authentication code or simply HMAC). Each part is separated by a . character and encoded with Base64Url as shown:

Figure 2.12 – JWT example

Let’s look at these three parts in some more detail:

• The header provides basic metadata regarding the JWT, typically as shown here:

  {
    "alg": "HS256",
    "typ": "JWT"
  }

• The claims section contains server-specific data (the claims) in a key-value pair notation. Registered claims include...

Summary

At this point, you understand all the elements of how an API is constructed. We looked at the different types of APIs in common use today and then focused on the specifics of the REST API, namely the HTTP protocol. API security is built on two foundational elements of access control, namely authentication (who is using the API) and authorization (what are they allowed to do with the API). From the origins of simple username/password authentication, we arrived at the OAuth2 framework, which is the workhorse of API access control.

Most API security vulnerabilities have their origins in poorly implemented authentication and authorization controls. We covered a number of high-level recommendations for avoiding these common pitfalls. Finally, we looked at the humble JWT, which forms the basis of API authorization, acting as your digital passport.

In the next chapter, we are going to look at how things can go wrong in practice by taking a deep dive into the most common API...

Further reading

Further reading on OAuth2 is available here:

• https://developers.google.com/oauthplayground/
• https://www.oauth.com/playground/
• https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc

Further reading on JWTs is available here:

• https://arielweinberger.medium.com/json-web-token-jwt-the-only-explanation-youll-ever-need-cf53f0822f50
• https://jwt.io/

Finally, further reading on authorization is available here:

• https://learning.postman.com/docs/sending-requests/authorization/
• https://thenewstack.io/oso-tackles-unbundling-security-authorization/
• https://www.openpolicyagent.org/docs/v0.11.0/http-api-authorization/