Authentication Fundamentals: Part II
OAuth2 and JWT: the Modern API Authentication Standards.
Hi Friends,
Welcome to the 160th issue of the Polymathic Engineer newsletter. This is the second article in our series on authentication and authorization.
In the last article, we talked about a major issue with API keys. They can be used to identify applications, but they can’t speak for users safely. You have to make a tough decision if a third-party app needs to do something for a user: either fully trust the third party or ask users to share their passwords.
Neither choice is good enough. As long as the third party has blind trust, they can pretend to be any user. If people share passwords, a third party can always get into user accounts. All user credentials are at risk if there is a single breach at the third party.
OAuth2 solves this problem. It is an authorization framework that lets users grant limited access to their data without sharing credentials. A user can say, “This app can read my email, but it can’t delete anything,” without giving away their password.
As of now, OAuth2 is the usual way to authorize APIs. It’s used by Google, Facebook, Microsoft, GitHub, and thousands of other big platforms. You need to know about OAuth2 if you are building APIs that third parties will use.
In this article, we'll cover:
OAuth2 fundamentals and the four roles
Authorization Code Grant for web applications
Authorization Code Grant + PKCE for mobile apps and SPAs
Client Credentials Grant for machine-to-machine communication
JSON Web Tokens (JWT) as the standard token format
Refresh tokens for seamless user experience
PASETO as a modern alternative to JWT
Project-based learning is the best way to develop technical skills. CodeCrafters is an excellent platform for tackling exciting projects, such as building your own Redis, Kafka, a DNS server, SQLite, or Git from scratch. Sign up, and become a better software engineer.
OAuth2 Fundamentals
The first thing to keep in mind is that OAuth2 is not an authentication system, but a framework for authorizing access. This distinction is critical. OAuth2 tells you what a user has allowed an application to do. It doesn’t directly identify the user.
Here is a typical scenario that OAuth2 addresses. Let’s say a user wants to use a third-party scheduling tool to manage their social media post submissions. The scheduling tool needs to access the users’ social media profile data. Without using OAuth2, the user would need to give their social media password to the scheduling tool.
With OAuth2, the user can grant specific permissions to the scheduling tool without sharing credentials. The speaker might say, “You can read my profile and write posts, but you can’t access my payment information.” If the user later wants to revoke access, they can do so without changing their password.
OAuth2 defines four distinct roles in the authorization process:
Resource Owner is typically an end user who owns the data. In our example, this is the user who has a profile in the social media app. The resource owner decides what access to grant to third-party applications.
Authorization Server gives out access tokens after verifying the resource owner's identity and getting their permission. Most identity providers, such as Google, Microsoft, and Auth0, are OAuth 2.0 authorization servers. Servers have two endpoints: the authorization endpoint (where users give consent) and the token endpoint (where applications get access tokens).
Client is the application requesting access to protected resources. In our example, this is the scheduling tool. There are two types of clients: confidential clients can maintain secrets (like web applications with server backends), and public clients cannot (like single-page applications and mobile apps).
The Resource Server hosts protected resources and accepts requests using access tokens. In our example, this is the social media API. The resource server validates tokens and serves data if the token is valid and has appropriate permissions.
In real-world systems, the resource server is often an API gateway that sits in front of multiple backend services. Clients call the API gateway, which works as a single entry point. The gateway validates access tokens and directs requests to the right backend services. From the client’s perspective, the API gateway is the resource server, even though multiple services are behind it.
OAuth2 Grant Mechanisms
OAuth2 provides an abstract protocol that all authorization requests follow:
The client requests authorization from the resource owner.
The resource owner is redirected to a consent screen or another mechanism that grants or denies authorization.
The client presents the authorization grant to the authorization server and requests an access token.
The authorization server validates the grant and issues an access token if everything checks out.
The client makes a request to the resource server, including the access token in the request header.
The resource server validates the access token and returns the requested resource if the token is valid.
This flow is meant to be flexible. Different grant types follow these steps differently, depending on their security requirements and use cases. The most important thing to remember is that the resource owner is in charge, the client never sees the user’s credentials, and the resource server only needs to verify that tokens are valid.
In order to choose the right OAuth2 grant, you need to know the difference between confidential and public clients. Confidential clients can securely store secrets. A web application with server-side code is confidential because the server can store a client secret that users never see. Using this secret, the server can prove its identity to the authorization server.
Public clients cannot securely store secrets. A single-page application runs entirely in the browser. Users can view all JavaScript code, including secrets. The same problem exists for mobile apps since users can decompile apps.
This difference is essential because some OAuth2 grants need a client to authenticate with a secret. Confidential clients can use these grants. Clients who are open to the public need different grants that don’t depend on secrets.
In the next section, we’ll explore the Authorization Code Grant, the most secure and widely used grant for confidential clients.
Authorization Code Grant
The Authorization Code Grant is the most complete and secure OAuth2 grant type. It is made for confidential clients who can protect a secret.
The critical thing about this type of grant is that it uses an intermediate authorization code before issuing an access token. This adds a layer of security by dividing the user-facing authorization step from the server-to-server token exchange.