Java Engineering Notes

Appearance

OAuth 2.0 Explained | System Architecture and Grant Types ​

The Valet Key Analogy ​

Imagine driving your car to an upscale restaurant in a bustling city. The restaurant offers valet parking. When you pull up to the front entrance, you do not hand the valet parking attendant your master keychain containing your house key, your safe deposit box key, your office key, and your master car key. That would be absurdly dangerous.

Instead, modern automobiles provide a valet key. The valet key starts the engine and drives the car at low speeds, but it physically locks out the glove compartment, prevents opening the trunk, and expires when you take back your car. You delegate limited, scoped access to a third party without ever surrendering your master credentials.

In modern software, OAuth 2.0 is that valet key. Before OAuth 2.0, if an application like a photo printing service wanted to print photos stored in your Google Drive, it asked you for your Google username and password! You were forced to surrender your master credentials to an untrusted third party. OAuth 2.0 (RFC 6749) solved this by creating a delegated authorization framework where third party applications receive a scoped, temporary Access Token without ever seeing your password.

This lecture covers the motivation behind OAuth 2.0, the four core roles, the industry standard Authorization Code Grant flow with PKCE, and token exchange mechanics.

The Four Roles in OAuth 2.0 ​

OAuth 2.0 standardizes interactions across four distinct architectural roles:

[ Resource Owner (User) ]
           |
           v
   [ Client App ]  (e.g. Spotify, Yelp, Third-Party Mobile App)
           |
           +--------------------------+
           |                          |
           v                          v
[ Authorization Server ]    [ Resource Server ]
(Google / GitHub Auth)      (Google Drive API / User Profile API)
  1. Resource Owner (The User): The person who owns the protected data (e.g. your photos in Google Drive, your profile on GitHub).
  2. Client Application: The third party software attempting to access the user's data on their behalf (e.g. an ecommerce website offering "Sign in with Google").
  3. Authorization Server: The trusted identity provider (Google, GitHub, Auth0, Keycloak). It authenticates the resource owner, gathers their consent, and issues access tokens.
  4. Resource Server: The backend API hosting the user's protected assets (e.g. Google Drive API, User Profile API). It accepts access tokens and serves protected data.

The Authorization Code Grant Flow (The Gold Standard) ​

The Authorization Code Grant is the most secure and widely adopted flow for web applications and mobile apps.

User (Browser)          Client App (Your Backend)     Authorization Server (Google)
     |                             |                               |
     | --- 1. Click "Login" -----> |                               |
     | <-- 2. Redirect to Auth --- |                               |
     |                                                             |
     | --- 3. GET /oauth/authorize (client_id, redirect_uri) ----> |
     | <-- 4. Shows Consent Screen ("Allow access to profile?") --- |
     | --- 5. User clicks "Approve" -----------------------------> |
     | <-- 6. Redirect to redirect_uri with ?code=AUTH_CODE_123 -- |
     |                                                             |
     | --- 7. Passes AUTH_CODE_123 to Client Backend ------------> |
     |                             |                               |
     |                             | --- 8. POST /oauth/token ---> |
     |                             |   (code, client_id, secret)   |
     |                             | <-- 9. Returns ACCESS_TOKEN - |
     |                             |                               |
     |                             | === 10. Call Resource API ==> |
     |                             |   (Header: Bearer TOKEN)      |

Step by Step Walkthrough: ​

  1. Initiation: The user visits your application and clicks "Login with Google".
  2. Redirect to Authorization Server: Your application redirects the user's browser to Google's authorization URL with query parameters:
    • client_id: Identifies your registered application.
    • redirect_uri: The trusted URL where Google should return the user after approval.
    • scope: The specific permissions requested (e.g. openid profile email).
    • state: A random cryptographic nonce used to prevent CSRF attacks.
  3. User Authentication & Consent: The user logs into Google (if not already logged in) and reviews the consent screen.
  4. Authorization Code Issued: Google redirects the browser back to your redirect_uri with a temporary, short lived Authorization Code (valid for thirty seconds): https://myapp.com/login/oauth2/code/google?code=4/0AX4XfWh...&state=xyz
  5. Backchannel Token Exchange: Your backend server makes a direct, secure server to server POST call to Google's token endpoint, exchanging the code, client_id, and client_secret for an Access Token and optional Refresh Token.
  6. Data Access: Your application attaches the Access Token in the Authorization: Bearer <token> header to fetch user profile details from the Resource Server.

Why Two Steps? (Code vs Direct Token) ​

Why does Google return a temporary authorization code to the browser first, instead of returning the access token directly?

Because the browser is an untrusted, public front channel. Anything passed in the browser URL bar or browser history can be intercepted by browser extensions, network proxies, or shoulder surfers.

By returning only a temporary code:

  • The actual access token is transferred exclusively over the secure back channel (direct TLS socket between your backend server and Google).
  • Even if an attacker steals the temporary authorization code from browser history, they cannot exchange it for a token without your application's private client_secret.

Enhancing Security with PKCE ​

For mobile apps and single page applications (React, Angular) where there is no secure backend to hide a client_secret, RFC 7636 introduced PKCE (Proof Key for Code Exchange).

In PKCE:

  1. The client generates a random secret called a code_verifier.
  2. It hashes the verifier with SHA256 to create a code_challenge.
  3. It sends the code_challenge in the initial authorization request.
  4. When exchanging the authorization code, it sends the original code_verifier.
  5. The authorization server hashes the verifier and confirms it matches the original challenge.

PKCE mathematically guarantees that only the specific client instance that initiated the login can exchange the code, neutralizing authorization code interception attacks.

Interview Questions & Pitfalls ​

Q1: What is the primary difference between Authentication and Authorization in OAuth 2.0?

OAuth 2.0 is fundamentally an authorization framework designed for delegated access (letting an application access data on your behalf). It does not standardize user identity or authentication formats. To provide standardized user authentication, the industry built OpenID Connect (OIDC) as an identity layer on top of OAuth 2.0, adding an id_token (JWT format) containing user profile details.

Q2: What are the four main roles defined in the OAuth 2.0 specification?

The four roles are the Resource Owner (the end user), the Client (the third party application requesting access), the Authorization Server (the identity provider authenticating the user and issuing tokens), and the Resource Server (the API hosting the protected data).

Q3: What is the purpose of the state parameter in an OAuth 2.0 authorization request?

The state parameter is an opaque, random cryptographic token generated by the client application and verified upon return. It binds the authorization request to the user's active session, preventing Cross Site Request Forgery (CSRF) attacks where an attacker tricks a victim into linking the attacker's account.

Q4: Why is the Authorization Code Grant preferred over the legacy Implicit Grant?

The Implicit Grant returned the access token directly in the URL hash fragment to the browser, exposing it to browser history, referrer headers, and malicious scripts. The Authorization Code Grant keeps token transmission on the secure back channel between the application server and the identity provider, protecting tokens from browser interception.

Q5: What is PKCE, and why is it necessary for single page applications and mobile apps?

PKCE (Proof Key for Code Exchange) protects public clients that cannot securely store a client_secret. The client generates a dynamic cryptographic verifier and challenge for each request, ensuring that even if an attacker intercepts the authorization code, they cannot exchange it for an access token without the verifier secret.