OAuth Failure Recovery: Why I Choose Safe Retries for Authorization and Callback Steps

WilhelmKnight8435 — Sat, 29 Aug 2026 00:10:18 +0000

Short answer: Retry the transport operation, never the OAuth meaning: keep one durable authorization attempt, accept its callback once, and make every downstream effect replayable from recorded state. For a B2B SaaS account-deletion flow, I would block new sessions before attempting remote cleanup, because deleting data while a surviving session can still act is the more dangerous ordering.

That is the architecture decision. It treats a timeout as missing knowledge, not proof of failure. A callback may have committed even when the browser received no response; a token exchange may have reached the other side even when the connection closed; an account deletion may be retried by a worker after its first lease expires. The recovery design must therefore answer a narrow question at each boundary: do we know the operation did not happen, do we know it happened, or is the result still unknown?

What must remain true during OAuth failure recovery?

The first invariant is that an authorization attempt has one identity independent of any HTTP request. Store an opaque flow identifier, the expected callback state, the account or tenant context, a creation time, an expiry, and a small state machine such as pending, exchanging, succeeded, or failed. Don't let a browser refresh create a second logical attempt merely because it creates a second request.

The second invariant is single consumption. An authorization code and its state belong to one attempt; the callback handler must atomically claim that attempt before triggering side effects. A duplicate callback should read the previously recorded outcome and return the same application-level destination. It must not provision the user again, issue another internal session, or append a second audit event that claims a second login. Exactly once is the goal, but HTTP cannot promise it by itself, so I use an exactly-once mindset at the business boundary: an atomic database transition establishes who owns the work, unique constraints reject duplicate effects, and an outbox carries committed work to asynchronous consumers. Delivery can still be at least once. Effects cannot. For auditability, record transitions rather than raw secrets. The useful trail says that flow af_7d31 moved from pending to exchanging, that callback attempt 3 observed a transport timeout, and that a later reconciliation read the stored outcome. Authorization codes, tokens, and session cookies do not belong in logs. This also keeps a GDPR deletion record useful after the personal fields it once referred to have been erased: retain the minimum compliance evidence your policy permits, under a pseudonymous operation identifier, and separate it from authentication material.

One boundary deserves special treatment. Account deletion and session revocation are not a single remote call. In the local transaction, mark the account as deletion-pending, advance or invalidate its session generation, reject future token refreshes, and enqueue cleanup. Only then should workers revoke remote grants and erase dependent data. The exact retention period and legal basis vary by jurisdiction and contract; I'm not sure a universal duration exists, so counsel and the data inventory must settle that part rather than the retry loop.

Stop access first.

How should OAuth failure recovery retry authorization and callback steps?

Classify failures by evidence, not by the layer that printed an error. A connection timeout is ambiguous. A validation rejection is terminal for that attempt. A browser abandonment is neither success nor protocol failure; it is an expired attempt that can be closed without inventing an error. This distinction prevents the common mistake of putting the entire authorization flow inside a generic exponential-retry wrapper.

Step or observation	Safe action	Why
Authorization redirect was not delivered to the browser	Re-render a link for the same unexpired attempt, or explicitly start a new attempt after expiring it	A redirect is user navigation, not a background command to repeat blindly
Callback arrives twice with the same state	Return the stored outcome after an atomic claim	Duplicate delivery must not duplicate provisioning, sessions, or audit effects
Callback validation fails	End that attempt and require a fresh authorization start	Retrying unchanged invalid input cannot establish trust
Token exchange loses its response	Mark the result unknown and reconcile through the attempt state; start fresh only after the attempt is terminal	The absence of a response does not prove that the peer did no work
Local commit succeeds but the response is lost	Serve the committed result on retry	The database, not the prior HTTP response, is the source of truth
Account cleanup worker loses its lease	Resume named cleanup stages and skip stages already recorded complete	Recovery proceeds from durable checkpoints rather than repeating the whole deletion

Backoff still matters, but only after classification. Cap attempts, add jitter, and stop on a deadline tied to the authorization attempt's expiry. Those controls protect dependencies from a retry wave; they do not create idempotency. For an unknown token-exchange outcome, the safest generic recovery is to avoid guessing that the same protocol credential can be consumed again. Persist the ambiguity, prevent parallel exchanges, and move the user into a fresh flow when the original attempt can no longer produce a trustworthy local result.

There is a useful asymmetry here — callback delivery can be replayed because the application controls its receiver, while authorization is an interaction with a person. A worker may retry a callback-side database transaction under a stable operation key. It should never manufacture repeated browser consent interactions in the background.

Where are the failure and compliance boundaries?

I draw four boundaries in the decision record: browser to callback, callback to authorization peer, callback to local transaction, and local outbox to workers. Each gets its own timeout, ownership rule, durable status, and observable counter. Combining them into one oauth_failed metric loses the evidence needed for recovery.

The browser boundary is untrusted input. Validate the callback against the stored attempt before changing state, return generic authentication errors to the user, and keep diagnostic detail in protected telemetry. OWASP's authentication guidance emphasizes generic responses because response differences can disclose account information; the same restraint belongs in callback error pages. A support identifier can connect the generic page to an audit event without displaying a token or internal exception.

The local transaction is the commit boundary. It should write the successful flow result, the internal session reference, the audit transition, and an outbox row together, or write none of them. If creating a session lives in a separate store, use a unique key derived from the authorization attempt and make session creation return the existing record for that key. A lock by itself isn't enough: process death releases locks, while a uniqueness rule survives it.

Deletion crosses a different compliance boundary. The request should produce a durable deletion operation whose stages are visible to operators: access blocked, sessions revoked, remote grants addressed, dependent records erased, and permitted audit evidence minimized. Do not log a cheerful deleted event after only the first stage. Reconciliation should compare the operation ledger with each owned data store and alert on an overdue stage. For payment or ledger records that cannot follow the same erasure schedule, isolate the legally retained record from active identity data and document the governing policy; an OAuth callback handler cannot decide that question.

Operationally, I would alert on attempts stuck in exchanging, repeated callbacks for distinct attempt identifiers, deletion operations past their deadline, and outbox age. Counts need tenant-safe dimensions and bounded cardinality. Logs need operation IDs. Traces need the same IDs, but no credentials. This is deliberately boring observability, which is what incident reconstruction needs.

What does the critical callback path look like in Go?

The following sketch keeps protocol calls behind an interface and makes the database claim explicit. It is not tied to a provider. The important part is the shape: claim once, record ambiguity, and publish effects only through committed state.

package callback

import (
    "context"
    "errors"
    "time"
)

var (
    ErrInvalidCallback = errors.New("invalid callback")
    ErrOutcomeUnknown  = errors.New("exchange outcome unknown")
)

type Attempt struct {
    ID        string
    State     string
    Status    string
    ExpiresAt time.Time
    ResultURL string
}

type Store interface {
    LoadByState(ctx context.Context, state string) (Attempt, error)
    ClaimPending(ctx context.Context, attemptID string) (bool, error)
    MarkUnknown(ctx context.Context, attemptID string) error
    CommitSuccess(ctx context.Context, attemptID string, subject string) error
}

type Exchanger interface {
    Exchange(ctx context.Context, code string) (subject string, err error)
}

type Handler struct {
    Store    Store
    Exchange Exchanger
    Now      func() time.Time
}

func (h Handler) Complete(ctx context.Context, state, code string) (string, error) {
    attempt, err := h.Store.LoadByState(ctx, state)
    if err != nil || attempt.State != state || !h.Now().Before(attempt.ExpiresAt) {
        return "", ErrInvalidCallback
    }
    if attempt.Status == "succeeded" {
        return attempt.ResultURL, nil
    }

    claimed, err := h.Store.ClaimPending(ctx, attempt.ID)
    if err != nil {
        return "", err
    }
    if !claimed {
        return "", ErrOutcomeUnknown
    }

    subject, err := h.Exchange.Exchange(ctx, code)
    if err != nil {
        // The store records uncertainty; policy decides whether a fresh flow is needed.
        _ = h.Store.MarkUnknown(ctx, attempt.ID)
        return "", ErrOutcomeUnknown
    }
    if err := h.Store.CommitSuccess(ctx, attempt.ID, subject); err != nil {
        return "", err
    }

    committed, err := h.Store.LoadByState(ctx, state)
    if err != nil {
        return "", err
    }
    return committed.ResultURL, nil
}

CommitSuccess is where the real rigor lives. Its transaction needs uniqueness on the attempt's success record and must insert the outbox event beside that record. If two handlers race, one commits and the other reads the same result. If the process stops after commit but before responding, the refreshed callback also reads that result. No special recovery endpoint is required.

The example deliberately does not retry Exchange in a loop. Some failures can be identified as definitely pre-send in a concrete transport, but a portable architecture should not infer that from a generic error. Your mileage may vary with a peer's documented idempotency contract; encode such knowledge in the adapter and test it, rather than allowing the callback handler to assume it.

Why reject a stateless retry loop, and when is it suitable?

The rejected option is a stateless callback that exchanges the code, provisions the account, creates a session, and returns a redirect on every invocation. It is attractive because it has little schema and works on the happy path. Its failure boundary is unacceptable for account deletion and migration: once the response is lost, the application cannot distinguish an uncommitted attempt from a committed one, and retrying may duplicate effects while refusing to retry may strand the user.

The durable attempt ledger has costs. It adds a state machine, uniqueness constraints, expiry cleanup, reconciliation, and on-call runbooks. It is not suitable when the callback has no durable effect, the application carries no sensitive session state, and a failed attempt can be abandoned without harming a user; in that narrow case, a fresh authorization flow with short-lived in-memory correlation may be enough. A stateless loop is also reasonable in a disposable local prototype.

For a B2B SaaS service that must delete an account and revoke every session, stick with the durable design. Migration off a managed provider makes this more important, not less: the application-owned operation key, audit vocabulary, and session-generation rule remain stable while adapters change. The final decision is conditional and plain: use safe replay around your own commit boundary, start a new authorization attempt after an ambiguous protocol outcome, and never declare deletion complete until reconciliation proves every owned stage reached its terminal state.

References

https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html