OAuth 2.x & OpenID Connect

01The idea: a valet key, not your house key

Some cars come with a valet key: it starts the engine but cannot open the trunk. OAuth gives apps valet keys. Four roles are involved. The resource owner is the user. The client is the app that wants access. The authorisation server authenticates the user and issues tokens. The resource server is the API that accepts tokens. The user logs in only at the authorisation server and approves specific scopes — 'read your calendar' — and the client gets an access token valid for those scopes and a limited time. The client never sees the password. Important distinction: OAuth 2.0 is about authorisation (what the app may do), not authentication (who the user is). Using a plain OAuth access token as proof of identity is a classic mistake; that gap is exactly what OpenID Connect fills.

• Resource owner: the user
• Client: web, mobile or server app
• Authorisation server: logs the user in, issues tokens
• Resource server: your API, validates tokens

02Authorisation code flow with PKCE, step by step

This is the recommended flow for web apps, SPAs and mobile apps. The client creates a random code_verifier and sends its SHA-256 hash (code_challenge) in the authorisation request. The user logs in and consents, and the server redirects back with a one-time authorisation code. The client exchanges the code plus the original verifier for tokens over a back channel. PKCE (Proof Key for Code Exchange, RFC 7636) means a stolen code is useless without the verifier, which never left the app. The state parameter protects against CSRF on the redirect, and with OIDC a nonce binds the ID token to this login. Redirect URIs must be registered and matched exactly. OAuth 2.1, still an IETF draft in late 2026 but already reflected in RFC 9700 (OAuth 2.0 Security Best Current Practice), requires PKCE for all clients and drops the implicit and password grants.

1# 1) Browser is redirected to the authorisation server
2GET https://auth.example.com/authorize?response_type=code
3  &client_id=web-app
4  &redirect_uri=https://app.example.com/callback
5  &scope=openid%20profile%20email%20orders:read
6  &state=af0ifjsldkj&nonce=n-0S6_WzA2Mj
7  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
8  &code_challenge_method=S256
9 
10# 2) Back channel: exchange the code for tokens
11POST https://auth.example.com/token
12Content-Type: application/x-www-form-urlencoded
13 
14grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
15&redirect_uri=https://app.example.com/callback
16&client_id=web-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

03Tokens: access, refresh and ID tokens

An access token is what the client sends to the API, usually as 'Authorization: Bearer ...'. It should be short-lived — minutes, not months — because anyone holding a bearer token can use it. It may be opaque (the API checks it with the authorisation server via introspection) or a JWT (the API verifies the signature locally). A refresh token lets the client get new access tokens without the user logging in again; it is long-lived and powerful, so store it carefully, rotate it on each use and revoke it on logout. An ID token, from OpenID Connect, is a signed JWT that tells the client who logged in: issuer (iss), subject id (sub), audience (aud), expiry (exp), nonce and optionally email or name. The ID token is for the client to read; it is not meant to be sent to your APIs as an access token.

• Access token: for the API, short-lived, scoped
• Refresh token: for the client to renew access, rotate and revoke
• ID token: for the client, proves who logged in

04OpenID Connect: 'Sign in with Google / Apple'

OpenID Connect (OIDC) is a thin identity layer on OAuth 2.0. You add the 'openid' scope, and the authorisation server returns an ID token alongside the access token. Providers publish a discovery document at /.well-known/openid-configuration listing their endpoints and the JWKS URL with signing keys. To sign a user in safely, your backend must verify the ID token: signature with the provider's current key, iss equals the provider, aud equals your client id, exp not passed, and nonce matches the one you sent. Then link the account by the provider's stable sub, not by email, because emails change and are not always verified. On mobile, native SDKs (Google Sign-In, Sign in with Apple) return an ID token or authorisation code, which the app sends to your backend for the same verification before you issue your own session or API tokens.

1use Laravel\Socialite\Facades\Socialite;
2 
3// Redirect the user to Google
4Route::get('/auth/google', fn () => Socialite::driver('google')->redirect());
5 
6// Callback: Socialite exchanges the code and fetches the profile
7Route::get('/auth/google/callback', function () {
8    $g = Socialite::driver('google')->user();
9 
10    $user = User::firstOrCreate(
11        ['google_id' => $g->getId()],          // stable provider "sub"
12        ['name' => $g->getName(), 'email' => $g->getEmail()],
13    );
14    Auth::login($user);
15    return redirect('/account');
16});

05Other grants and API keys

Not every client has a user in a browser. Client credentials: a backend service authenticates as itself (client id and secret, or better a signed assertion or mutual TLS) to call another service — machine-to-machine. Device authorisation (RFC 8628): smart TVs and CLIs show a code that the user enters on their phone. Token exchange (RFC 8693): a service swaps one token for another with narrower scope or a different audience. Refresh token grant: renew access. Deprecated: the implicit grant (tokens in the URL fragment) and the resource owner password grant (the app collects the user's password), both removed in OAuth 2.1. Simple API keys are still common for server-to-server integrations; if you use them, make them scoped, prefixed by environment (live/test), hashed in storage, rate-limited, and rotatable without downtime.

06Laravel Passport in practice

Laravel Passport is a full OAuth2 server for Laravel APIs, built on the League OAuth2 server. Current versions support the authorisation code grant (with PKCE for public clients), client credentials, device authorisation, refresh tokens and personal access tokens; the password and implicit grants are disabled unless you explicitly enable them. You define scopes with Passport::tokensCan, protect routes with the auth:api guard plus scope middleware, and set token lifetimes in a service provider — by default access tokens live a year, which is far too long for most apps, so shorten them. For first-party SPAs on the same domain, Laravel Sanctum's cookie-based sessions are often simpler than OAuth; Passport shines when you need real OAuth clients, third-party access or token-based mobile apps.

1// AppServiceProvider::boot()
2use Carbon\CarbonInterval;
3use Laravel\Passport\Passport;
4 
5Passport::tokensCan([
6    'orders:read'   => 'View your orders',
7    'orders:create' => 'Place orders',
8]);
9Passport::tokensExpireIn(CarbonInterval::minutes(30));
10Passport::refreshTokensExpireIn(CarbonInterval::days(30));
11 
12// routes/api.php
13use Laravel\Passport\Http\Middleware\CheckToken;
14 
15Route::get('/orders', [OrderController::class, 'index'])
16    ->middleware(['auth:api', CheckToken::using('orders:read')]);

07Validating JWTs correctly (and the classic attacks)

A JWT is header.payload.signature, base64url-encoded. Validation must be strict. Pin the expected algorithm in your code (for example RS256 or ES256) and reject anything else — historic vulnerabilities came from libraries trusting the header's alg, allowing 'none' or HS256-with-the-public-key confusion. Fetch signing keys from the issuer's JWKS endpoint, cache them, select by kid, and refresh on an unknown kid to support key rotation. Check iss and aud exactly, exp and nbf with a small clock-skew allowance, and for ID tokens the nonce. Do not put sensitive data in the payload — it is signed, not encrypted. RFC 8725 (JWT Best Current Practices) is the reference. Prefer asymmetric signing so resource servers only hold public keys, and only the authorisation server can mint tokens.

1import { createRemoteJWKSet, jwtVerify } from "jose";
2 
3const JWKS = createRemoteJWKSet(new URL("https://auth.example.com/.well-known/jwks.json"));
4 
5export async function verifyAccessToken(token: string) {
6  const { payload } = await jwtVerify(token, JWKS, {
7    issuer: "https://auth.example.com",
8    audience: "https://api.example.com",
9    algorithms: ["RS256"],      // never trust the header's alg
10    clockTolerance: 30,         // seconds
11  });
12  if (await denylist.has(payload.jti as string)) throw new Error("revoked");
13  return payload; // sub, scope, exp, ...
14}

08Refresh token rotation and reuse detection

Refresh tokens are the crown jewels: long-lived and able to mint access tokens. Rotation means every refresh returns a new refresh token and invalidates the old one. Reuse detection adds the key safety property: if an old, already-used refresh token is presented again, either the legitimate client or an attacker has a stolen copy — so the server revokes the whole token family and forces re-login. Implement this by storing a family id and a used flag per refresh token. Add an absolute lifetime (for example 30–90 days) and an idle timeout, so abandoned sessions die. Handle races in mobile apps where two parallel requests both try to refresh: serialise refreshes on the client, or allow a very short grace window for the previous token. Sender-constrained tokens go further, binding tokens to a client key so a stolen token cannot be replayed elsewhere.

09Sender-constrained tokens: DPoP and mTLS

Bearer tokens work like cash: whoever holds them can spend them. Sender-constrained tokens work like a card with a PIN. With DPoP (RFC 9449), the client generates a key pair, and with every request it sends a short signed proof JWT containing the HTTP method, URL, a timestamp and a hash of the access token. The authorisation server binds the token to the client's public key (the cnf claim), and the API checks that each request is signed by the same key. A token leaked through logs or a proxy becomes useless. Mutual TLS (RFC 8705) achieves the same by binding tokens to a client certificate, common in banking and open-finance profiles such as FAPI 2.0. Pushed Authorization Requests (PAR, RFC 9126) complement this by sending authorisation parameters over a back channel instead of the browser URL, preventing tampering.

1POST /orders HTTP/1.1
2Host: api.example.com
3Authorization: DPoP eyJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ...
4DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Li4ufX0...
5 
6# DPoP proof payload (signed with the client's private key):
7# { "htm": "POST", "htu": "https://api.example.com/orders",
8#   "iat": 1793000000, "jti": "e1j3V_bKic8-LAEB", "ath": "<sha256 of access token>" }

10Multi-tenant and B2B identity design

In SaaS, identity gets more complex: users belong to organisations, may belong to several, and enterprise customers want their own SSO. Put the tenant in the token deliberately — a tenant or org claim chosen at login or via an organisation switcher — and verify on every request that the resource belongs to that tenant; never take tenant ids from request bodies alone. Keep roles and permissions in your application, mapped from IdP groups if needed, rather than trusting arbitrary claims from external IdPs. Support per-tenant OIDC or SAML connections for enterprise SSO, plus SCIM for user provisioning if customers ask. Plan for impersonation: support staff should get a separate, time-boxed token with an act (actor) claim, a mandatory reason and full audit logging, never the customer's own credentials.