Security is a non-negotiable component of REST API design. That includes auth, which is a blanket term for authentication and authorization. Below, you’ll find an overview of the role of authorization in an API, and a primer on some of the most widely used modern authentication standards.
This article focuses on human users, but a growing share of APIs are designed for machine-to-machine (M2M) communication. Developers building M2M APIs have needs and options beyond this article’s scope, but some of the options below work for both human and automated consumers.
Authentication vs. authorization
First, let’s review the difference between authentication and authorization and the supporting services.
Authentication establishes the identity of an API consumer
Authentication involves three parties:
- The user (or API consumer) provides authentication factors (credentials).
- The identity provider (IdP) uses the credentials to verify the identity of a known user.
- The service provider (the app or API) gets confirmation of user authentication from the IdP.
Dedicated IdPs are more secure and easier to maintain than any homegrown auth system, so the service never handles credentials directly.
Authorization controls what an API user can do
Authentication ends when the IdP confirms the user identity and notifies your API. By contrast, authorization happens primarily in your API code. There are two main authorization (access control) patterns:
- Role-based authorization assigns users roles such as User, Administrator, or Resource Owner. Each category has different permissions for different endpoints.
- Policy-based access control, called claims-based or resource-based authorization, grants users access to specific resources and endpoints as needed.
Role-based access is more straightforward to implement, while policy-based access allows more fine-grained control.
Every API needs access control designed for its data and users. There’s only one universal rule for authorization: All sound authorization plans start with robust, standardized authentication.
Why are both types of auth important to your API?
Without authentication, you have no way of knowing who’s using your API and no way to limit their actions. Without authorization rules, authentication informs you of who’s running amok in your API. Authentication should always be followed immediately by authorization.
While you have broad options for authorization, it’s best to choose from a handful of tried-and-tested, industry-standard authentication methods. These standard methods help you build a comprehensive auth system that works as designed.
Implement high-quality authentication standards
Using an established authentication standard and IdP helps you deliver better overall security. Choosing a standard early in your API design process can help you implement it well.
The methods below are all standard practices listed from least to most secure. Each has tradeoffs and best use cases.
API keys
API keys are unique identifier strings sent to control usage and monitor access with each HTTP request. They can be valuable for collecting metrics and tracking projects.
API keys show up on almost every list of API auth methods, but on their own, API keys are not an authentication method. You can’t use them to establish the genuine identity of a user.
However, they contribute to security, as they help prevent DDoS attacks and allow administrators to block users quickly. So, while they can’t provide real auth functionality, combining API keys with other authentication methods can make them more useful.
HTTP Basic Authentication
The simplest API authentication method is to send a username/password pair in the HTTP `Authorization: Basic` header. It’s a common practice to use Basic Authentication to add a client secret to an API key.
Any information in this header is encoded but not encrypted by default, making it insecure. Using HTTPS adds Transport Layer Security (TLS) encryption to Basic Auth, which you should do anyway.
Even with encryption, Basic Auth is an unsophisticated protocol. It’s vulnerable to brute force attacks, doesn’t support logout functionality, and has no support for multifactor authentication. It can work for public APIs serving widely available data, internal APIs, and small-scale services, but most production APIs need more.
OpenID Connect and OAuth 2.0
OpenID Connect (OIDC) and OAuth 2.0 are two widely used protocols. Let’s clarify each protocol’s role as they’re often used together.
OAuth2.0 lets API users share resources securely
Technically speaking, OAuth2.0 isn’t an authentication method; it’s an authorization framework for sharing data between APIs. When Canva asks for access to Google Drive, or you authorize your Apple Watch to share your activity data with a fitness tracker, the OAuth 2.0 framework coordinates the exchange.
OAuth doesn’t require a specific IdP or authentication method. A common choice is to use a third-party application like Google, GitHub, or even a consumer-facing app like Facebook as your IdP. It’s a flexible, well-supported framework for building your authorization rules, and it’s workable for human and machine users.
OIDC is a portable authentication standard
OpenID Connect is an authentication protocol built on top of OAuth 2.0. It uses JSON tokens and specifies details about token format and what’s required from IdPs. JSON makes the protocol lightweight and almost universally usable in HTTP and HTML environments.
You can use OIDC without creating OAuth flows, but authorization must follow authentication. If you’re using OIDC, OAuth is an obvious choice for authorization. If you use OIDC, you’re using the OAuth 2.0 framework regardless of custom OAuth flows, since the functions that support third-party IdPs are built on OAuth.
OIDC and OAuth 2.0 work together for single sign-on
While you can use them independently, OIDC and OAuth are designed to work together. In combination, they support single sign-on (SSO) in various applications and settings.
SSO is a hallmark of top-tier user or developer experience. Security Assertion Markup Language, or SAML, remains a popular choice for SSO in enterprise settings, but XML — which SAML uses — isn’t as widely usable as JSON, and setting up SAML requires specialized knowledge.
OIDC/OAuth is the SSO protocol of choice for APIs.
JSON Web Tokens
OIDC uses a security token called a JSON Web Token (JWT). If your API has complex authorization needs, such as multi-tenant architecture or claims-based access, directly implementing JWT gives you more control.
JWTs are passed with every API call and are relatively compact and fast. They’re a common way to support SSO and useful in scenarios where users send a significant volume of API requests quickly – they’re known as “session authentication.”
JWTs are signed tokens. Each one includes a unique signature created from the payload and header data. That means JWTs validate the user’s identity and the integrity of the request payload. Once an HTTP request is signed, any change to the payload invalidates the signature.
JWTs have some special security considerations, making them hard to fully exploit in public APIs. However, they’re useful in private or partner APIs where data integrity with each request is crucial. They’re also a good fit for some M2M APIs.
Mutual TLS
As mentioned, TLS is the encryption protocol that backs up HTTPS. It uses public key cryptography to encrypt traffic between server and client. Mutual TLS (mTLS) goes a step further.
In a typical HTTPS environment, the API server provides a certificate to the client, verified using a TLS handshake. In mTLS, the client and server both have TLS certificates, and each must verify the other’s credentials. mTLS is secure enough to be used in zero trust environments, where translations require authentication from every user, device, and request. It’s also a common protocol for M2M authentication.
Make a solid auth plan and stick to it
The most important element in any API security program is consistency. Once you’ve decided on the right authentication protocol for your API, the next step is to plan your authorization pattern and rules. But neither of those choices can enforce itself — create a detailed plan, so you follow through on your well-informed decisions!
