Samson Maborukoje

Posted on Jan 27

OAuth Is Simpler Than You Think

#security #webdev #beginners #api

The Problem

You are building an application that needs to read a user’s Google Calendar. How do you obtain access?

Option 1: Ask for their password (what not to do)

Your application requests the user’s Google credentials and stores them. This approach is insecure. Your application possesses credentials it should not have, the user cannot limit or revoke access without changing their password, and if your application is compromised, the attacker gains full access to the user’s account.

Option 2: OAuth (what to do)

The user authenticates directly with Google. Google asks:

“This application requests access to your calendar. Allow or deny?”

If the user approves, Google issues a token to your application. Your application uses that token to access the calendar. Your application never sees the password.

This is OAuth. It allows users to grant limited access to their resources without sharing their credentials.

An Analogy

Consider a hotel key card. When checking into a hotel, guests do not receive a copy of the master key. Instead, they receive a card that:

Opens only their assigned room (limited access)
Functions only during their stay (time-limited)
Can be deactivated by the front desk (revocable)
Does not grant access to staff areas (scoped)

OAuth tokens operate on the same principles. They provide limited, temporary, and revocable access. The resource owner maintains control.

The Roles

OAuth defines four roles:

Resource Owner

The entity that owns the protected resources and can grant access to them. This is often a user. When you grant an application access to your Google Drive, you are the resource owner. It can also be a system or organisation in machine-to-machine scenarios.

Client

The application requesting access. This could be a mobile application, a web service, or an automated script. The client requests permission to perform actions on behalf of the resource owner.

Authorisation Server

The system that authenticates the resource owner and issues tokens. When you see “Sign in with Google” and encounter a consent screen, you are interacting with an authorisation server. It verifies identity and obtains consent before issuing tokens.

Resource Server

The system that hosts the protected resources, such as the calendar API, file storage API, or social media API. It validates tokens and returns data if the token permits the requested access.

Sometimes the authorisation server and resource server are operated by the same organisation (Google operates both for Google Calendar). In other cases, they are separate (for example, an organisation might use Keycloak as its authorisation server while maintaining its own internal APIs as resource servers).

How It Works

The following describes what occurs when your application needs access to a user’s calendar:

Your application directs the resource owner to the authorisation server

Your application opens a browser window pointing to the authorisation server (such as Google or your organisation’s identity provider). The URL includes information identifying your application and the access being requested.
The resource owner authenticates and sees a consent screen

The authorisation server handles authentication. The resource owner provides their credentials and completes any additional verification steps. Then they see a consent screen:

“Calendar App requests access to view your calendar. Allow?”
The resource owner approves the request

They are granting permission. They could also deny the request.
The authorisation server redirects back to your application with a code

The browser redirects to your application with a short-lived authorisation code in the URL.
Your application exchanges the code for a token

Your application’s server contacts the authorisation server directly, presenting the code and requesting a token. The authorisation server verifies the request and returns an access token.
Your application uses the token to access the resource server

Your application includes the token in API requests. The resource server validates the token, confirms it permits the requested access, and returns the data.

This constitutes the entire flow. The resource owner grants permission, the client receives a token, and the client uses that token to access resources.

Tokens

The token is the essential component. It is a string of characters that represents the permission the resource owner granted.

Access tokens are what your application presents to resource servers. They are short-lived, typically expiring within an hour. If one is compromised, the potential damage is limited by this short lifespan.
Refresh tokens allow your application to obtain new access tokens without requiring repeated resource owner interaction. They have longer lifespans and should be stored securely. Your application uses them to maintain access over time.

The resource owner can revoke tokens at any time. If they access their Google account settings and remove your application’s access, your tokens cease to function. The resource owner retains control over their resources.

What OAuth Is Not

OAuth is not authentication

OAuth handles authorisation (what resources can be accessed), not authentication (verifying identity). If your application needs to identify the resource owner, not merely access their resources, you need OpenID Connect, which extends OAuth for authentication purposes. Most identity providers support both protocols.

OAuth is not a product

OAuth is a specification published by the IETF (Internet Engineering Task Force). Products such as Auth0, Okta, and Keycloak implement this specification. Google and Microsoft implement it as well. OAuth itself is the standard they follow.

This distinction matters because:

Auth0 documentation describes Auth0’s implementation, not OAuth generally
Applications can migrate between implementations because all follow the same specification
Troubleshooting requires understanding whether an issue lies in the application code, the authorisation server configuration, or the protocol understanding

OAuth defines multiple flows

The flow described above is the most common pattern. Alternative flows exist for different contexts, such as devices without browsers or backend services communicating without resource owner involvement. The underlying principle remains consistent: scoped, revocable access without credential sharing.

Common Mistakes

Treating tokens as proof of identity

An access token proves that the resource owner granted permission to access specific resources. It does not reliably indicate who they are. Access tokens are designed for authorisation, not authentication.

Why this matters:

An access token may be issued to a client on behalf of any resource owner. The token itself may not contain identity information, or that information may not be verified. Using access tokens to identify users can lead to security vulnerabilities where one user impersonates another.

Solution:

Use OpenID Connect for authentication. When you need to know who the resource owner is, request an ID token by including the openid scope. The ID token is a signed JWT that contains verified identity claims. Validate this token according to the OpenID Connect specification before trusting its contents.

Storing tokens carelessly

Tokens are sensitive credentials that grant access to protected resources. Improper storage exposes them to theft.

Why this matters:

If an attacker obtains a valid access token, they can access the resource owner’s data until that token expires. If they obtain a refresh token, they can maintain access indefinitely by generating new access tokens.

Solution:

Store tokens securely based on your application type:

Server-side applications: store tokens in encrypted server-side sessions or secure databases
Mobile applications: use platform-specific secure storage (Keychain on iOS, Keystore on Android)
Browser-based applications: avoid storing tokens in localStorage or sessionStorage. Consider the Backend-for-Frontend pattern or secure, HTTP-only cookies

Never log tokens, include them in URLs, or transmit them through insecure channels.

Requesting excessive access

Some applications request broad permissions during authorisation, asking for more access than they require.

Why this matters:

Resource owners are less likely to approve requests for extensive access. If they do approve and tokens are later compromised, the attacker gains access to everything within the granted scope. This also violates the principle of least privilege.

Solution:

Request only the scopes your application needs for its current functionality. If additional permissions are required later, initiate a new authorisation request for those specific scopes. This is known as incremental authorisation.

Assuming tokens are permanent

Access tokens expire, typically within minutes to hours. Refresh tokens may also expire or be revoked.

Why this matters:

Expired tokens cause API requests to fail. Without proper handling, users experience errors or unnecessary re-authentication.

Solution:

Implement proper token lifecycle management:

Store the expires_in value returned with the access token
Check token expiry before making API requests
Use refresh tokens to obtain new access tokens when needed
Prompt re-authorisation if refresh tokens are invalid or expired
Handle 401 Unauthorized responses gracefully

Where OAuth Is Used

“Sign in with Google/GitHub/Microsoft” (OAuth + OpenID Connect)
Applications accessing calendars, cloud storage, or social media
Enterprise systems using Keycloak, Okta, or similar platforms
APIs requiring delegated access to protected resources

Once you understand the fundamental flow, you will recognise it across many systems.

DEV Community