OAuth 2.0 & OpenID Connect: The Definitive Guide for Developers

If you've ever integrated "Log in with Google" or accessed an API on behalf of a user, you've encountered OAuth 2.0. Despite its ubiquity, it remains one of the most misunderstood topics in web development. Terms like "Implicit Flow," "Bearer Token," and "OIDC" often get thrown around, leading to confusion and, worse, security vulnerabilities.

This guide aims to be the definitive resource for understanding OAuth 2.0 and OpenID Connect (OIDC), focusing on what you actually need to know to build secure applications.

Authentication vs. Authorization

Before diving into the protocols, we must distinguish between two fundamental concepts:

Authentication (AuthN): Who are you? (e.g., verifying a user's identity).
Authorization (AuthZ): What are you allowed to do? (e.g., granting access to a resource).

OAuth 2.0 is a protocol for authorization. It allows an application to access resources hosted by another server on behalf of a user.
OpenID Connect (OIDC) is a layer built on top of OAuth 2.0 specifically for authentication. It allows clients to verify the identity of the user.

The Roles

To understand the flows, you need to know the players:

Resource Owner: The user (you).
Client: The application attempting to access the user's account (e.g., a web app).
Authorization Server: The server presenting the login screen and issuing tokens (e.g., Google, Auth0).
Resource Server: The API hosting the user's data (e.g., Google Drive API).

The Tokens

OAuth and OIDC rely heavily on tokens. Understanding the difference is crucial.

Access Token

This is the key to the castle. The client sends this token to the Resource Server to access data. It's often a JWT (JSON Web Token), but it can also be an opaque string.

Purpose: Authorization.
Audience: Resource Server.

ID Token (OIDC only)

This token contains information about the user (name, email, picture). It is strictly for the Client to identify the user.

Purpose: Authentication.
Audience: Client.
Format: Always a JWT.

Refresh Token

A long-lived token used to obtain new Access Tokens when the current one expires. This allows the user to stay logged in without re-entering credentials.

Tool Tip: Debugging JWTs can be a headache. Use the Pockit JWT Decoder to inspect the header and payload of your tokens securely without them leaving your browser.

Common Flows (Grant Types)

The "Grant Type" determines how the client gets the Access Token. Choosing the wrong one is a common security risk.

1. Authorization Code Flow (with PKCE)

Best for: Server-side apps, SPAs, and Mobile apps.
This is the gold standard. Instead of getting a token directly, the client gets a temporary "code" which it exchanges for a token. PKCE (Proof Key for Code Exchange) adds a layer of security, preventing code interception attacks.

Client redirects user to Authorization Server.
User logs in and approves access.
Authorization Server redirects back to Client with a code.
Client exchanges code + code_verifier for an Access Token.

2. Client Credentials Flow

Best for: Machine-to-Machine (M2M) communication.
Used when an app needs to access its own resources, not a user's. There is no user interaction.

Client sends client_id and client_secret to Authorization Server.
Authorization Server returns an Access Token.

3. Implicit Flow (Deprecated)

Best for: Nothing (Historically used for SPAs).
This flow returns tokens directly in the URL fragment. It is now considered insecure due to the risk of token leakage in browser history and logs. Do not use this.

Troubleshooting Common Issues

"redirect_uri_mismatch"

This is the most common error. The redirect_uri you send in the request must exactly match one of the URIs whitelisted in your OAuth provider's dashboard. Even a trailing slash makes a difference.

"invalid_grant"

This generic error usually means:

The authorization code has expired (they are very short-lived).
The code has already been used.
The redirect_uri used to get the code doesn't match the one used to exchange it.

CORS Errors

If you're calling an API with your Access Token and getting CORS errors, ensure your browser isn't blocking the request. Sometimes, the issue isn't CORS but an invalid token causing the server to return a 401, which the browser interprets poorly.

Conclusion

OAuth 2.0 and OIDC are powerful tools that form the backbone of modern identity. By understanding the distinction between AuthN and AuthZ, choosing the right flow (Auth Code with PKCE!), and knowing how to inspect your tokens, you can build secure and robust applications.

Don't roll your own crypto, and don't try to reinvent authentication. Stick to the standards, and your users (and security team) will thank you.