OAuth 2.0

OAuth 2.0 is an authorization framework that allows third-party applications to obtain limited access to HTTP services. At it's core it's a linear system that ensure s that two systems are validating access to resources in a secure way. It defines a process for resource owners to authorize third-party access to their server resources without sharing their credentials. OAuth 2.0 is widely used for securing APIs and enabling single sign-on (SSO) across different applications.

Key Roles

  • Resource Owner: User who authorizes access
  • Client: Application requesting access
  • Resource Server: API server hosting protected resources
  • Authorization Server: Server that authenticates resource owner and issues tokens

Authorization Code Flow

Browser → Client App → Authorization Server → Browser → Client App → Resource Server
  1. User accesses client application
  2. Client redirects to authorization server
  3. User authenticates and grants permission
  4. Authorization server returns authorization code
  5. Client exchanges code for access token
  6. Client accesses protected resources using access token

Access Token Example

Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3

Grant Types

  • Authorization Code: Standard flow for web apps
  • Implicit: Simplified flow for SPAs (deprecated)
  • Client Credentials: Machine-to-machine communication
  • Resource Owner Password: Direct credential exchange

Discovery Document (.well-known/openid-configuration)

OAuth 2.0 doesn't define a standard way for clients to discover a server's endpoints. OpenID Connect fills this gap with the Discovery Document - a JSON file at a standard URL that tells clients where the authorization_endpoint, token_endpoint, and other endpoints live.

→ Full deep-dive on the Discovery Document

Authorization Endpoint

# OIDC Authorization Endpoint The Authorization Endpoint is used to interact with the resource owner and obtain an authorization grant. It's used for the Authorization Code flow and Implicit flow. ## Endpoint URL ``` GET /authorize ``` ## Parameters | Parameter | Required | Description | |-----------|----------|-------------| | `response_type` | Yes | Determines the flow - "code" for Authorization Code flow, "token" for Implicit flow, "id_token" for Hybrid flow | | `client_id` | Yes | The client identifier registered with the provider | | `redirect_uri` | Recommended | Where to redirect the user after authorization | | `scope` | Recommended | Space-separated list of scopes (openid is required for OIDC) | | `state` | Recommended | Random value used to prevent CSRF attacks | | `nonce` | Required for Implicit/ Hybrid | Random value used to mitigate replay attacks | ## Example Request ``` GET /authorize? response_type=code& client_id=s6BhdRkqt3& redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb& scope=openid%20profile%20email& state=af0ifjsldkj& nonce=n-0S6_WzA2Mj ``` ## Response The authorization server redirects the user-agent back to the client with either: - An authorization code (in the Authorization Code flow) - Access token and/or ID token (in the Implicit flow)

Token Endpoint

# OIDC Token Endpoint The Token Endpoint is used by the client to obtain an access token, ID token, and refresh token by presenting its authorization grant or refresh token. ## Endpoint URL ``` POST /token ``` ## Parameters (Authorization Code Flow) | Parameter | Required | Description | |-----------|----------|-------------| | `grant_type` | Yes | Must be set to "authorization_code" | | `code` | Yes | The authorization code received from the authorization endpoint | | `redirect_uri` | Yes | Must match the redirect_uri used in the authorization request | | `client_id` | Yes | The client identifier | | `client_secret` | Yes | The client secret (for confidential clients) | ## Example Request ``` POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=SplxlOBeZQQYbYS6WxSbIA& redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb& client_id=s6BhdRkqt3& client_secret=7Fjfp0ZBr1KtDRbnfVdmIw ``` ## Example Response ``` HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ..." } ``` ## Refresh Token Request ``` POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded grant_type=refresh_token& refresh_token=8xLOxBtZp8& client_id=s6BhdRkqt3& client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

Pros & Cons

  • ✅ Standardized protocol
  • ✅ Delegated access without sharing passwords
  • ✅ Multiple grant types for different use cases
  • ❌ Complex implementation
  • ❌ Redirect-based flows vulnerable to interception