DEV Community

Cover image for OAuth2 Explained Simply — For Developers Who Hate Overcomplicated Docs
Denil
Denil

Posted on

3 1 1 1 1

OAuth2 Explained Simply — For Developers Who Hate Overcomplicated Docs

#webdev #oauth #authentication #security

🧠 Introduction — OAuth2, Demystified

You've probably clicked "Login with Google" or "Sign in with GitHub" more times than you can count. But have you ever stopped and wondered:

What actually happens under the hood when I do that?

That slick one-click login experience is powered by OAuth2, a protocol designed to let applications access user data without asking for passwords. It’s one of the most critical yet misunderstood pieces of modern web security.

Whether you’re building a web app, a mobile app, or an API-driven service, there's a good chance you'll need to integrate OAuth2 at some point. But here’s the catch:

Most OAuth2 documentation reads like a textbook written by robots for robots.

In this article, I’ll walk you through OAuth2 in plain English—what it is, why it exists, and how it works—step by step.

By the end, you'll:

  • Understand the core flow of OAuth2 (without memorizing jargon)
  • Know what each piece of the protocol does and why

🔐 What is OAuth2 (and Why Should You Care?)

OAuth2 is a protocol that lets apps access user data on another service—securely and with permission—without ever seeing the user’s password.

Think of it like this:

OAuth2 is like handing a valet a special key that only starts your car—but doesn’t open your glove box, trunk, or access your phone via Bluetooth.

The valet (a third-party app) can drive your car (perform limited tasks) without ever having full control over your belongings (like your personal data).

🤔 Why Not Just Share the Password?

Before OAuth2, some apps literally asked users for their credentials to access third-party services (like email or cloud storage). Sketchy, right?

OAuth2 solves this problem by letting users authorize access through a secure process handled by the service they trust (like Google or GitHub). The user logs in there, not in your app, and your app receives a special token that allows access to certain parts of their data.

🧩 Core Use Cases of OAuth2

You’ve probably already interacted with OAuth2 if you’ve done any of these:

  • Signed into a website using Google, GitHub, Facebook, or Twitter
  • Connected your GitHub repo to a CI/CD service like Netlify or CircleCI
  • Granted a mobile app access to your Google Calendar or Contacts
  • Authorized Postman to use your Spotify account data for testing

Behind the scenes, OAuth2 makes all of that possible—without ever giving away your actual login credentials.

👨‍💻 Why It Matters to Developers

If you’re building an app that needs to:

  • Let users log in with a third-party account
  • Access APIs like GitHub, Google Calendar, Dropbox, Spotify, etc.
  • Allow integrations with services on behalf of the user

...then OAuth2 is your new best friend.

And while it can be complex, understanding the fundamentals will help you:

  • Avoid confusing errors (like that dreaded CORS or invalid_redirect_uri stuff)
  • Secure your app against token misuse and CSRF attacks
  • Build user trust with a seamless and safe login experience

Next, let’s break down the roles involved in an OAuth2 flow—like who’s handing the valet key and who’s driving the car. 🧑‍🔧

🧱 The Key Players in OAuth2 (Who's Who in the Zoo)

OAuth2 can feel like a lot, but once you understand who’s playing what role, it all starts to click.

Let’s break down the four main characters in this security drama—using simple language and real-world metaphors.

👤 1. Resource Owner — The User

This is the person who owns the data and grants permission.

Think of them as the car owner who decides whether or not to give someone the valet key.

They’re the ones who log into Google or GitHub and approve your app's request.

📱 2. Client — Your Application

This is your app that wants access to the user’s data.

Your app is the valet asking for permission to drive the car—but it needs to go through the proper process to prove it's trustworthy.

The client never sees the user’s credentials (like their password). Instead, it gets a token after the user grants permission.

🔐 3. Authorization Server — The Gatekeeper

This is the service that authenticates the user and issues tokens.

Think of it like the front desk at a hotel that verifies the user’s identity and gives out digital keycards with limited access.

Examples:

  • Google’s OAuth2 server
  • GitHub’s OAuth app system
  • Facebook’s Login service

This is the place users are redirected to when they click “Login with GitHub”.

🗂 4. Resource Server — The Data Vault

This is the server that holds the user’s protected data—like email, profile info, repositories, playlists, etc.

It’s the garage where the car is parked, and only lets people in who have the right kind of valet key (a valid access token).

In many cases, the Authorization Server and Resource Server are the same (e.g., in Google’s system), but they don’t have to be.

🎯 Real Example: Logging in With GitHub

Role Who It Is
Resource Owner You (the user)
Client Your web app
Authorization Server GitHub’s OAuth server
Resource Server GitHub’s API (e.g., /user, /repos)

🔄 The OAuth2 Flow — Step by Step (Authorization Code Grant)

Now that we know the key players, let’s walk through how they actually interact in the most commonly used OAuth2 flow: the Authorization Code Grant.

This is the flow typically used for web apps where you want to authenticate users securely.

TL;DR: Your app asks for permission, the user approves it, and your app gets a temporary "hall pass" (access token) to call APIs on their behalf.

Let’s break it down step by step 👇

🧨 Step 1: The User Clicks “Login with GitHub”

Your app presents a button:

<a href="https://github.com/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8080/callback&scope=user">
  Login with GitHub
</a>
Enter fullscreen mode Exit fullscreen mode

When the user clicks it, they’re redirected to the Authorization Server (in this case, GitHub).

🔐 Step 2: Redirect to Authorization Server

The browser navigates to a URL like this:

https://github.com/login/oauth/authorize
  ?client_id=abc123
  &redirect_uri=http://localhost:8080/callback
  &scope=user
  &state=randomstring
Enter fullscreen mode Exit fullscreen mode

Here’s what each query parameter means:

  • client_id: Your app’s public identifier on GitHub
  • redirect_uri: Where GitHub should send the user afterward
  • scope: What your app is requesting (e.g., user, repo)
  • state: A random string to protect against CSRF attacks

👤 Step 3: User Logs In and Approves Access

GitHub shows a prompt:

“Do you want to allow Your App to access your profile?”

Once the user logs in and approves, GitHub redirects them back to your app via the redirect_uri.

🧾 Step 4: Authorization Code is Sent Back

Your app receives a GET request at the callback endpoint:

GET /callback?code=123456&state=randomstring
Enter fullscreen mode Exit fullscreen mode
  • code: A temporary authorization code you’ll now exchange for a token.
  • state: You verify this matches what you originally sent (CSRF protection).

🔄 Step 5: App Exchanges Code for Access Token

Your backend makes a POST request to GitHub’s token endpoint:

POST https://github.com/login/oauth/access_token
Content-Type: application/json

{
  "client_id": "abc123",
  "client_secret": "your-client-secret",
  "code": "123456",
  "redirect_uri": "http://localhost:8080/callback"
}
Enter fullscreen mode Exit fullscreen mode

🧩 Where do you get your client_id and client_secret?

To get these, you need to register a new OAuth application on GitHub.

Once registered, GitHub will give you:

  • A Client ID (public identifier for your app)
  • A Client Secret (keep this safe—used for secure token exchanges)

If everything checks out, GitHub responds:

{
  "access_token": "gho_abcdef123456",
  "scope": "user",
  "token_type": "bearer"
}
Enter fullscreen mode Exit fullscreen mode

You now have the token—but not user info yet.

🌐 Step 6: App Uses Access Token to Access User Data

You can now call GitHub’s API on behalf of the user:

GET https://api.github.com/user
Authorization: Bearer gho_abcdef123456
Enter fullscreen mode Exit fullscreen mode

GitHub responds with the user’s profile info:

{
  "login": "yourusername",
  "name": "Denil",
  "avatar_url": "https://...",
  ...
}
Enter fullscreen mode Exit fullscreen mode

Mission accomplished! 🎯 You’ve successfully authenticated a user using OAuth2 and can now personalize the app based on their profile.

🔧 Coming Up in Part 2:

In the next part of this series, we’ll roll up our sleeves and implement the entire OAuth2 flow in Go, using the golang.org/x/oauth2 package with GitHub as our OAuth provider.

You’ll learn how to:

  • Register an OAuth app on GitHub to get your client_id and client_secret
  • Set up a simple Go web server to handle login, callback, and token exchange
  • Use the access token to fetch real user data from the GitHub API

Stay tuned—Part 2 will turn everything we’ve learned into real, working code. 💻🔥

Top comments (0)