# OAuth 2.0 Implementation Patterns

> Practical patterns for implementing OAuth 2.0 flows in backend services.

- Published: 2026-02-02
- Updated: 2026-08-02
- Category: security
- Tags: security, oauth, api
- Page: https://brandonwie.dev/posts/oauth2-implementation-patterns

A Slack OAuth connector I built ran quietly for months. The surprise came from a different integration entirely: Google started appending an undocumented `iss` parameter to OAuth callbacks, strict DTO validation rejected the unknown field, and the callback began returning a cryptic 400. No changelog, no deprecation notice, no mention in the discovery document. Welcome to OAuth 2.0 in production.

This post covers the practical patterns I've learned implementing OAuth flows against real providers: the authorization code flow, CSRF protection with state parameters, secure token storage, and how to handle the inevitable surprises when providers evolve their protocol without telling you.

---

## The Problem

Integrating third-party services (like Slack) requires secure delegated authorization. Without a well-structured OAuth 2.0 implementation, you risk token leaks, CSRF attacks on callbacks, and broken auth flows that are hard to debug — especially when the provider's error responses are opaque.

---

## Difficulties Encountered

- **State parameter CSRF attacks are silent**: Forgetting the state parameter
  does not cause any visible error — the flow works fine. The vulnerability only
  becomes apparent under attack, making it easy to ship insecure code that
  passes all functional tests.
- **Token exchange errors are vague**: When `oauth.v2.access` returns
  `{"ok": false, "error": "invalid_grant"}`, it could mean the code expired
  (10-minute window), the redirect URI does not match exactly, or the code was
  already used. No further detail is provided, requiring trial-and-error
  debugging.
- **Redirect URI must match exactly**: A trailing slash mismatch between what is
  registered in the provider and what is sent in the request causes a confusing
  "redirect_uri_mismatch" error that does not tell you which URI it expected.
- **In-memory state storage breaks with multiple replicas**: The naive
  `dict`-based state store works in development but silently fails in production
  with multiple server replicas, since the callback may hit a different instance
  than the one that generated the state.
- **Google silently adds RFC 9207 `iss` parameter without documentation**:
  Google began appending `iss=https://accounts.google.com` to OAuth callback
  URIs per RFC 9207 (Authorization Server Issuer Identification) without
  updating their official documentation, their
  `.well-known/openid-configuration` discovery document, or publishing any
  announcement. The `iss` claim is documented only for ID token validation, not
  the callback URL itself. This appears to be a phased rollout — some users
  receive it, others do not — making it a non-deterministic bug from the
  developer's perspective.
- **`forbidNonWhitelisted` ValidationPipe rejects unknown OAuth callback
  params**: NestJS's `forbidNonWhitelisted: true` enforces a closed-world
  assumption (reject anything not explicitly declared on the DTO). OAuth 2.0 was
  designed with forward-compatibility — clients MUST ignore unrecognized
  response parameters (RFC 6749). When combining strict DTO validation with
  OAuth, you accept the maintenance cost of updating DTOs whenever upstream
  providers evolve their protocol. The `authuser`, `hd`, and `prompt` fields in
  Google's callback are prior examples of the same undocumented-addition
  pattern.

With those lessons learned, let's walk through the implementation patterns that handle these challenges correctly.

---

## Authorization Code Flow

The most common flow for server-side applications. The client never sees the access token directly — it receives a short-lived authorization code that the server exchanges for the token in a back-channel request:

```text
┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  User   │     │ Client  │     │  Auth   │     │ Resource│
│         │     │ (Your   │     │ Server  │     │ Server  │
│         │     │  App)   │     │ (Slack) │     │ (Slack) │
└────┬────┘     └────┬────┘     └────┬────┘     └────┬────┘
     │ 1. Click      │               │               │
     │   "Connect"   │               │               │
     │──────────────>│               │               │
     │               │ 2. Redirect   │               │
     │               │   to OAuth    │               │
     │<──────────────│   URL         │               │
     │               │               │               │
     │ 3. User       │               │               │
     │   authorizes  │               │               │
     │───────────────────────────────>               │
     │               │               │               │
     │               │ 4. Redirect   │               │
     │               │   with code   │               │
     │<──────────────────────────────│               │
     │               │               │               │
     │ 5. Callback   │               │               │
     │   with code   │               │               │
     │──────────────>│               │               │
     │               │ 6. Exchange   │               │
     │               │   code for    │               │
     │               │   token       │               │
     │               │──────────────>│               │
     │               │               │               │
     │               │ 7. Access     │               │
     │               │   token       │               │
     │               │<──────────────│               │
     │               │               │               │
     │               │ 8. API calls  │               │
     │               │   with token  │               │
     │               │───────────────────────────────>
```

## CSRF Protection with State Parameter

The state parameter is your primary defense against CSRF attacks on the OAuth callback. Without it, an attacker could trick a user into connecting the attacker's account instead of their own. The dangerous part: the flow works perfectly fine without the state parameter — you won't notice the vulnerability until you're exploited.

```python
import secrets

# Store for state validation (use Redis in production with multiple replicas)
_oauth_states: dict[str, str] = {}

async def authorize():
    # Generate cryptographically secure state
    state = secrets.token_urlsafe(32)
    _oauth_states[state] = "slack"

    params = {
        "client_id": settings.SLACK_CLIENT_ID,
        "scope": settings.SLACK_SCOPES,
        "redirect_uri": settings.SLACK_REDIRECT_URI,
        "state": state,  # CSRF protection
    }
    return {"authorize_url": f"https://slack.com/oauth/v2/authorize?{urlencode(params)}"}

async def callback(code: str, state: str):
    # Validate state FIRST
    if state not in _oauth_states:
        raise HTTPException(400, "Invalid state token")

    del _oauth_states[state]  # One-time use
    # ... exchange code for token
```

## Token Exchange

Once the callback arrives with a valid state, the next step is exchanging the authorization code for an access token. This happens server-to-server — the code is short-lived (typically 10 minutes) and single-use:

```python
async def exchange_code_for_token(code: str) -> dict:
    token_url = "https://slack.com/api/oauth.v2.access"

    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.post(
            token_url,
            data={
                "client_id": settings.SLACK_CLIENT_ID,
                "client_secret": settings.SLACK_CLIENT_SECRET,
                "code": code,
                "redirect_uri": settings.SLACK_REDIRECT_URI,
            },
        )
        result = response.json()

    if not result.get("ok"):
        raise OAuthError(result.get("error", "unknown"))

    return {
        "access_token": result["access_token"],
        "team_id": result["team"]["id"],
        "scope": result["scope"],
    }
```

## Secure Token Storage

Access tokens are credentials — treat them with the same care as passwords. Store them in a secrets manager like HashiCorp Vault, not in your application database where a SQL injection could expose them:

```python
# Store in Vault
def store_oauth_token(source_type: str, token_data: dict) -> bool:
    client = VaultClient(vault_addr, k8s_role)
    return client.write_secret(f"connectors/{source_type}", token_data)

# Retrieve per-request
def get_oauth_token(source_type: str) -> dict:
    client = VaultClient(vault_addr, k8s_role)
    return client.read_secret(f"connectors/{source_type}")
```

## Error Handling

OAuth providers return cryptic error codes that need to be mapped to user-friendly HTTP responses. The most frustrating is `invalid_grant`, which could mean three different things with no way to distinguish them programmatically:

| OAuth Error    | HTTP Status | User Message                        |
| -------------- | ----------- | ----------------------------------- |
| invalid_client | 500         | Configuration error                 |
| invalid_grant  | 400         | Authorization expired, please retry |
| access_denied  | 403         | Access was denied                   |
| invalid_scope  | 400         | Invalid permissions requested       |
| server_error   | 503         | Provider temporarily unavailable    |

## Configuration Separation

| Setting       | Storage          | Sensitivity |
| ------------- | ---------------- | ----------- |
| Client ID     | ConfigMap/env    | Low         |
| Client Secret | K8s Secret/Vault | HIGH        |
| Redirect URI  | ConfigMap/env    | Low         |
| Scopes        | ConfigMap/env    | Low         |
| Access Tokens | Vault only       | HIGH        |

## Best Practices

1. **Never log tokens** - Mask in logs, never print full values
2. **Use HTTPS** - OAuth requires TLS for redirect URIs
3. **Validate state** - Check state before processing callback
4. **Minimal scopes** - Request only what you need
5. **Token rotation** - Implement refresh flow if provider supports it
6. **Secure storage** - Use Vault or equivalent, not database
7. **Audit trail** - Log OAuth events (connect, disconnect, errors)
8. **Keep callback DTOs extensible** - Providers add parameters without notice
   (RFC 9207 `iss`, `authuser`, `hd`, `prompt`). If using strict DTO validation
   (`forbidNonWhitelisted`), accept the maintenance cost of updating the DTO
   when providers evolve their protocol

---

## RFC 9207 — Authorization Server Issuer Identification

RFC 9207 (published March 2022) addresses **mix-up attacks** in multi-IdP OAuth
scenarios. An attacker can trick a client into sending an authorization code to
the wrong authorization server. The `iss` parameter lets the client verify which
server issued the response.

### How It Works

The authorization server appends `iss` to the callback redirect alongside `code`
and `state`:

```text
https://your-app.com/callback?code=abc123&state=xyz&iss=https%3A%2F%2Faccounts.google.com
```

### Discovery Document Advertising

Per the RFC, servers advertise support via their
`.well-known/openid-configuration`:

```json
{
  "authorization_response_iss_parameter_supported": true
}
```

As of 2026-02-23, Google does **not** include this field in their discovery
document, despite sending the `iss` parameter to some users — suggesting a
phased rollout.

### Closed-World vs Open-World Validation

This creates a fundamental tension between two valid security philosophies:

| Philosophy                                       | Approach              | Trade-off                                               |
| ------------------------------------------------ | --------------------- | ------------------------------------------------------- |
| **Open-world** (RFC 6749)                        | Ignore unknown params | Forward-compatible, but may miss malicious injection    |
| **Closed-world** (NestJS `forbidNonWhitelisted`) | Reject unknown params | Secure-by-default, but breaks when providers add params |

When combining strict DTO validation with OAuth, you accept the maintenance cost
of updating DTOs whenever upstream providers evolve. The `authuser`, `hd`,
`prompt`, and now `iss` fields in Google's callback are all examples of
parameters added without spec changes or announcements.

### Google's Phased Rollout Pattern

Google-scale systems use traffic-splitting (by account hash, region, or
Workspace org) to gradually roll out changes. This means:

- The same endpoint behaves differently for different users simultaneously
- Developers may not reproduce the issue on their own accounts
- The bug is non-deterministic from the developer's perspective
- Monitoring and error logs (e.g., Sentry) are the first signal, not QA

### Follow-up: Issuer Validation

Per RFC 9207, clients that support the `iss` parameter SHOULD validate that it
matches the expected issuer. For Google:

```typescript
if (dto.iss && dto.iss !== "https://accounts.google.com") {
  throw new UnauthorizedException("Unexpected OAuth issuer");
}
```

This adds defense-in-depth against mix-up attacks, but it is worth shipping
separately from the minimal fix of letting `iss` through validation — one is
validation passthrough, the other is new behavioral logic.

---

## When to Use

- **Server-side applications** integrating with third-party APIs (Slack, Google,
  GitHub) where you need delegated user authorization
- **Multi-tenant SaaS** where each customer connects their own accounts and you
  store tokens per-tenant
- **Backend connector services** that act on behalf of users (fetching data,
  sending notifications) without storing user passwords

---

## When NOT to Use

- **Internal service-to-service communication**: Use API keys, mTLS, or service
  mesh identity instead. OAuth 2.0 is designed for delegated user authorization,
  not machine-to-machine within a trusted network.
- **Simple API key scenarios**: If you control both client and server and do not
  need user delegation, OAuth adds unnecessary complexity over a plain API key
  with rate limiting.
- **Client-side only apps without a backend**: The Authorization Code flow
  requires a server to securely exchange the code. For pure SPAs, consider the
  Authorization Code flow with PKCE or a BFF (Backend for Frontend) pattern
  instead of implementing token exchange in the browser.
- **Webhooks or event-driven integrations**: If the third party pushes data to
  you (rather than you pulling it), you typically verify webhook signatures
  rather than using OAuth tokens.

---

## Practical Takeaways

OAuth 2.0 is a mature protocol with well-understood patterns, but production implementations still surprise you because providers evolve their behavior independently — often without notice. Here's what to carry with you:

1. **Always use the state parameter.** It's CSRF protection, and skipping it causes no visible error — the flow works fine without it. You won't know you're vulnerable until you're exploited. Generate a cryptographically random state, validate it before processing the callback, and use Redis (not in-memory dicts) in production with multiple replicas.

2. **Keep your callback DTOs extensible.** Providers add parameters (Google's `iss`, `authuser`, `hd`, `prompt`) without spec changes or announcements. If you use strict validation like NestJS's `forbidNonWhitelisted`, accept the maintenance cost of updating your DTO when monitoring catches new fields.

3. **Store tokens in a secrets manager, not your database.** Access tokens are credentials. Treat them with the same care as passwords — Vault, AWS Secrets Manager, or equivalent. Never log them, even partially.

4. **Redirect URI matching is exact.** A trailing slash difference between your provider registration and your request causes a confusing `redirect_uri_mismatch` error. Copy-paste the URI; don't retype it.

The authorization code flow with state parameter protection, shown in this post, covers the vast majority of server-side OAuth integrations. Start there, add PKCE if your provider supports it, and implement refresh token rotation for long-lived access.
