Skip to content
Velloreth
Cybersecurity 6 min read

OAuth 2.0 Explained: Flows and When to Use Each

OAuth 2.0 lets an app access a user's data without their password. Learn the flows, the tokens, and the mistakes that cause vulnerabilities.

By

What OAuth 2.0 actually solves

OAuth 2.0 solves a specific problem: how does an application access a user’s data on another service without the user handing over their password? Before OAuth, the common pattern was to ask for the password directly, which meant the application could do anything the user could do, and a breach of the application exposed every user’s credentials on the other service.

OAuth replaces the password with a token that has a limited scope and a limited lifetime. The user authenticates with the service directly, never with the application, and the application receives a token that grants only the access the user approved.

The key insight is that OAuth is an authorisation framework, not an authentication protocol. It answers “what is this application allowed to do”, not “who is this user”. Using it for authentication is the source of a whole class of vulnerabilities, and the fix is to use OpenID Connect, which adds an identity layer on top.

The four roles

OAuth defines four roles, and keeping them straight makes the flows much easier to follow.

The resource owner is the user. They own the data and they grant access to it.

The client is the application requesting access. It has a client ID, and for a confidential client, a client secret.

The authorisation server is the service that authenticates the user and issues tokens. It is often the same system as the resource server, but the roles are distinct.

The resource server is the API that holds the data. It accepts an access token and returns the resource.

The authorisation code flow

This is the flow to use for almost every application, and it is worth understanding in detail because the others are variations on it.

Step 1: the client redirects the user to the authorisation server. The request includes the client ID, the redirect URI, the requested scopes, a random state value, and a PKCE challenge.

https://auth.example.com/authorize
  ?response_type=code
  &client_id=my-app
  &redirect_uri=https://my-app.com/callback
  &scope=read:profile read:email
  &state=xyzABC123
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Step 2: the user authenticates and approves. The authorisation server shows the user what the application is asking for, and the user approves or denies. The user’s credentials go to the authorisation server, never to the client.

Step 3: the authorisation server redirects back with a code. The redirect goes to the registered URI and includes a short-lived code and the state value.

https://my-app.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xyzABC123

Step 4: the client exchanges the code for tokens. This is a back-channel request, server to server, so the code is never exposed to the browser.

curl -X POST https://auth.example.com/token \
  -d grant_type=authorization_code \
  -d code=SplxlOBeZQQYbYS6WxSbIA \
  -d redirect_uri=https://my-app.com/callback \
  -d client_id=my-app \
  -d code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Step 5: the client uses the access token. The token goes in the Authorization header as a bearer token.

curl https://api.example.com/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Why PKCE matters

PKCE closes a real attack. Without it, a malicious application on the same device could register the same custom redirect URI, intercept the authorisation code, and exchange it for a token. The code alone was enough.

With PKCE, the code is not enough. The client generates a random verifier, sends its SHA-256 hash with the authorisation request, and sends the verifier itself when exchanging the code. The authorisation server checks that the verifier hashes to the challenge it saw earlier. An attacker who intercepts the code does not have the verifier, so the exchange fails.

PKCE was designed for public clients, but it is now recommended for confidential clients too, because it protects against code injection even when a client secret exists.

The other flows

Client credentials is for machine-to-machine communication with no user involved. The client authenticates with its own credentials and receives a token for its own access, not a user’s.

curl -X POST https://auth.example.com/token \
  -d grant_type=client_credentials \
  -d client_id=my-service \
  -d client_secret=... \
  -d scope=read:metrics

Device code is for a device with no browser, such as a television or a CLI tool. The device shows a code, the user enters it on another device, and the device polls for the token.

Implicit returned the token directly in the redirect. It is deprecated because the token ends up in the browser history and the referrer header, and because it cannot use PKCE. Do not use it.

Password asked for the user’s password directly. It is deprecated because it defeats the purpose of OAuth. Do not use it.

The tokens

An access token is what the client presents to the API. It is usually a JWT or an opaque string, and it should be short-lived. It is a bearer token, which means anyone who holds it can use it, so it must be protected in transit and at rest.

A refresh token is what the client uses to get a new access token without involving the user. It is long-lived, it must be stored securely, and it should be rotated on each use so that a stolen token is detectable.

An ID token is an OpenID Connect addition. It is a JWT that describes the authentication event and the user, and it is what the client uses to know who logged in.

Common mistakes

Using OAuth for authentication. OAuth tells you what an application can do, not who the user is. Use OpenID Connect for login.

Not validating the redirect URI exactly. A prefix match or a wildcard lets an attacker redirect the code to their own server. The registered URI must match exactly.

Skipping the state parameter. The state value binds the callback to the request that started it. Without it, an attacker can inject their own authorisation code, which is a CSRF attack on the login.

Storing tokens in localStorage. A single XSS vulnerability then leaks every token. A confidential client should keep tokens on the server, and a public client should use a short-lived token in memory.

Long-lived access tokens. A token that lives for a month is a month of access for anyone who steals it. Keep it short and use a refresh token.

Trusting the token without validating it. A resource server must verify the signature, the issuer, the audience, and the expiry. A token that is merely decoded is not verified.

A quotable summary

OAuth 2.0 is an authorisation framework that lets an application access a user’s data without their password, by exchanging a short-lived, scoped token for the user’s approval. The authorisation code flow with PKCE is the right choice for almost every application, because it keeps the token out of the browser and binds the code to the client that requested it. The implicit and password flows are deprecated. OAuth is not authentication; if you need to know who the user is, use OpenID Connect on top.

For the token format, see jwt-explained and for the storage decision, session-vs-token-auth. For the broader context, api-authentication-methods and security-headers-guide.

Frequently asked questions

What is OAuth 2.0 in simple terms?
OAuth 2.0 is a way for a user to grant an application limited access to their account on another service, without giving that application their password. The user is redirected to the service, approves the request, and the application receives a token it can use to call the service's API on the user's behalf.
Is OAuth 2.0 the same as OpenID Connect?
No. OAuth 2.0 is an authorisation framework: it grants access to resources. OpenID Connect is a layer on top of OAuth 2.0 that adds authentication: it tells the application who the user is, through an ID token. If you need to log a user in, you want OpenID Connect, not bare OAuth 2.0.
Which OAuth 2.0 flow should I use?
For a web application with a server, use the authorisation code flow with PKCE. For a single-page application or a mobile app, use the authorisation code flow with PKCE and no client secret. For machine-to-machine communication with no user involved, use the client credentials flow. Avoid the implicit flow and the password flow.
What is PKCE and why does it matter?
PKCE (Proof Key for Code Exchange) is an extension that binds the authorisation request to the token request. The client generates a random verifier, sends its hash with the authorisation request, and sends the verifier itself when exchanging the code. An attacker who intercepts the code cannot exchange it without the verifier, which closes the interception attack on public clients.
How long should an access token live?
An access token should be short-lived, typically between five minutes and an hour. A short lifetime limits the damage if a token leaks, and the refresh token lets the client get a new one without involving the user. A refresh token should be long-lived but revocable, and it should be rotated on each use so a stolen refresh token is detectable.
What is the difference between a scope and a role?
A scope describes what an application is allowed to do on behalf of the user, such as reading their email. A role describes what the user themselves is allowed to do within an application. Scopes are part of the OAuth grant; roles are part of the application's own authorisation model.