Beyond Bearer Tokens: Architecting Secure OAuth Lifecycles & CSRF Protection

Engineers often treat OAuth 2.0 as a solved problem. Redirect the user, grab a code, swap it for a token, save it. Done. But protocol correctness doesn't equal system security.

The uncomfortable reality? Most teams nail the happy path in a day, then spend six months fighting token expiry bugs, CSRF edge cases, and silent auth failures. Failing to verify the OAuth state parameter leaves applications wide open to Cross-Site Request Forgery (CSRF) and account takeover.

If you build B2B SaaS integrations, handling enterprise authentication means treating OAuth token lifecycles as a distributed systems problem. At Truto, we maintain connections to a wide range of SaaS platforms. Doing this securely means hardening every step of the handshake, storage, and refresh lifecycle.

Here is how we architected our OAuth infrastructure. No marketing fluff—just a practical reference for building auth at scale.

Initiating the Flow: Secure Link Tokens

The vulnerability surface starts before the user even sees a login screen. Exposing raw tenant IDs or environment identifiers in plain-text query parameters invites tampering and enumeration attacks.

Instead of passing raw context, we generate a Link Token. This is a time-bound UUID that securely initiates an OAuth connection for a specific environment or tenant.

• Hashed Storage: We never store raw tokens. We HMAC-hash them using a dedicated signing key and store the digest in a distributed key-value (KV) store. While attackers with access to the KV store would only see the hash, this defense-in-depth measure mitigates exposure risks but must be paired with strict access controls.
• Strict Expiration: Link tokens have a hard 7-day Time-To-Live (TTL).
• Scope Resolution: Scopes are resolved dynamically from the link token, falling back to the unified model, and finally the integration config. URL parameters for scopes are ignored by the system, which helps prevent scope escalation via URL tampering.
• Time-Bound and Deleted on Success: Link tokens remain valid until they succeed or their TTL expires. Once the OAuth callback completes successfully, the token is deleted. Replaying a successful connection URL gets you nothing.

Hardening the Handshake: CSRF, State, and PKCE

This is where most OAuth implementations fail. Developers know about the state parameter, but often treat it as a formality rather than a security artifact.

The State Parameter: More Than a Random String

When a user clicks "Connect," the system must prepare a secure state before redirecting them. Weak state implementations lead directly to account takeovers. Our state generation is paranoid by design:

1. Generate a cryptographic nonce: We create a random UUID to serve as the state.
2. Short-lived KV storage: The state is HMAC-hashed with a dedicated OAUTH_STATE_SIGNING_KEY and stored in our KV store with a strict 5-minute TTL. Callbacks that arrive after five minutes are rejected outright.
3. Secure Cookie Binding: We set a session cookie (truto_oauth_session_state) containing the state value. This cookie is locked down with HttpOnly, Secure, and SameSite=Lax directives, tied strictly to the server's domain.

The callback handler validates the state by checking either the query parameter or the cookie. Then, it looks up the HMAC-hashed version in KV. If the entry is missing, expired, or tampered with, the flow fails.

PKCE: Closing the Code Interception Gap

PKCE (Proof Key for Code Exchange) prevents authorization code interception. At Truto, PKCE is optional per integration config to support legacy providers, but when enabled, we use the S256 method.

Here is the architectural breakdown:

1. Generate a code_verifier from two concatenated UUIDs for high entropy.
2. Compute the code_challenge by SHA-256 hashing the verifier and base64url-encoding the result.
3. Store the code_verifier securely inside the hashed state object in KV, never exposed to the browser.
4. Send the challenge in the authorization redirect using code_challenge and code_challenge_method=S256.

// Conceptual: PKCE challenge generation
const codeVerifier = `${crypto.randomUUID()}${crypto.randomUUID()}`;
const challengeBuffer = await crypto.subtle.digest(
  'SHA-256',
  new TextEncoder().encode(codeVerifier)
);
const codeChallenge = base64UrlEncode(challengeBuffer);
 
// Stored in the OAuth state for retrieval on callback
oauthState.pkceCodeVerifier = codeVerifier;
 
// Sent in the authorization redirect
authorizeParams.code_challenge = codeChallenge;
authorizeParams.code_challenge_method = 'S256';

The Callback Path and Context Injection

When the provider redirects the user back to our callback endpoint, the system validates the handshake and securely persists the credentials.

Cross-Instance Routing & Static IP Proxying

In a multi-instance deployment, the OAuth callback might hit a different server than the one that started the flow. Our state entry includes a callbackServerUrl. If the callback hits the wrong instance, we transparently redirect it to the correct one. For enterprise providers that require whitelisted IPs, we route the token exchange request through a static IP proxy using custom headers.

Context Injection

After validation, we exchange the authorization code for tokens. Since our architecture handles API requests generically, we merge the resulting payload into an encrypted context object attached to the account.

This context is the single source of truth. During a downstream API call, our engine resolves placeholders like {{oauth.token.access_token}} at runtime, injecting credentials directly into the outgoing HTTP headers.

Security at Rest: AES-GCM Encryption

Tokens are highly privileged credentials. Storing them in plaintext is a massive liability. Protecting data at rest means applying application-level encryption to all sensitive context fields before they ever touch the database disk.

• Authenticated Encryption: We use AES-GCM (Advanced Encryption Standard with Galois/Counter Mode). This provides both confidentiality and integrity—if an attacker modifies the encrypted blob, decryption fails rather than returning corrupted data.
• Per-Encryption IVs: We generate a cryptographically secure, random 12-byte Initialization Vector (IV) for every single database write. The encrypted payload is stored in secure *_secret columns (like context_secret) formatted as {iv_base64}::{encrypted_data_base64}. Reusing IVs in AES-GCM destroys its security, so a unique IV per write is non-negotiable.
• Targeted Redaction: Before any API response is returned to a client, a strict redaction utility strips out sensitive paths (access_token, refresh_token, client_secret).

The Token Lifecycle: Mutexes and Proactive Refreshes

Tokens expire. Handling a refresh sounds easy—until three background sync jobs and two user-facing API requests hit the same expired token at the exact same millisecond. Fire five concurrent refresh requests to a provider like Salesforce, and they will likely invalidate the token entirely, suspecting a replay attack.

We solved this with a two-pronged approach to reliable token refreshes:

1. Proactive Refresh Alarms

We proactively schedule refreshes to reduce the chance of hitting a 401 Unauthorized response. Whenever a token updates, we schedule a distributed alarm to fire 60 to 180 seconds before it expires. This randomization spreads the load across our infrastructure. When the alarm fires, a background worker proactively negotiates a new token.

2. Distributed Mutex Locks

For on-demand API calls that happen to catch an expired token, we route the refresh through a distributed mutex lock using a Durable Object (currently enabled only for our sandbox environment).

This object is keyed to the specific integrated account. The first request to hit the mutex acquires the lock, sets a 30-second timeout alarm, and initiates the HTTP call. If concurrent requests arrive, they see the active lock and simply await the existing promise in memory.

// Conceptual: Mutex-protected token refresh
async acquire<T>(...args: any[]): Promise<T> {
  // If a refresh is already running, wait for it
  if (this.operationInProgress) {
    return await this.operationInProgress as T;
  }
 
  // Set a 30-second safety timeout
  await this.storage.setAlarm(Date.now() + 30_000);
 
  this.operationInProgress = (async () => {
    try {
      return await this.performRefresh(...args);
    } finally {
      await this.storage.deleteAlarm();
      this.operationInProgress = null;
    }
  })();
 
  return await this.operationInProgress as T;
}

The Reauth State Machine

When a refresh fails, your retry strategy needs to be smart about error types:

• Retryable errors (HTTP 500+, network failures): A new refresh alarm is scheduled for later.
• Non-retryable errors (HTTP 401, 403): The alarm is deleted entirely. No amount of retrying fixes hard authorization failures. The account is marked as needs_reauth, and a webhook fires so your application can prompt the user to reconnect.

Security as Data, Not Code

Implementing strict CSRF protection, AES-GCM encryption, and distributed mutexes from scratch for one integration is painful. Doing it for a large ecosystem of SaaS platforms is a maintenance nightmare. This is exactly why teams are abandoning point-to-point connectors.

Our architectural philosophy is simple: handle security declaratively. The complex mechanics of PKCE, state validation, and token concurrency live entirely within our generic execution pipeline. Adding a new integration becomes a matter of configuration, not writing bespoke authentication handlers.

Treat token lifecycle management as a fundamental infrastructure primitive, not an afterthought. That way, developers stop fighting OAuth edge cases and get back to building the actual product.