Using Authlib in a Multi-Instance Setup #878

Hi everybody,

First off, thanks for Authlib — we rely on it heavily.
I have tried to fit the description into the preset-questions and hope it is still understandable:

Is your feature request related to a problem? Please describe.

A - Multi-instance setup

We ran into what we think might be a documentation gap while building an OAuth client on top of authlib.integrations.starlette_client for a multi-instance backend behind a load balancer. By default, the PKCE verifier and state are stored in the server-side session, which breaks when the callback lands on a different instance than the one that started the flow. Sticky sessions felt like overkill for us.

B - Custom data

A related pain point: there's no obvious way to attach custom data to an auth flow (we needed to carry some information through), since

1. ...authorize_redirect doesn't expose the OAuth2 state for an idiomatic approach and additionally...
2. ...the cache key is created internally with therefore no way to append to the cache after ...starlette_client.OAuth has internally called .set on the cache.

Describe the solution you'd like

A - Multi-instance setup - A clearer documentation for the (somewhat standard) setup would be nice.
B - Custom data - A way of appending custom data to the cache.

Describe alternatives you've considered

A - Multi-instance setup

We found that OAuth(cache=...) accepts a pluggable async cache (get / set / delete), which was exactly what we needed — we backed it with our database which then worked out quite nicely. However, this interface doesn't seem to be documented anywhere; we reverse-engineered it from the source, including the expected method signatures and when they're called.

B - Custom data

We worked around it with ContextVars to insert to the cache somewhat artificially, but it's somewhat clunky.

Additional contex

Before investing our time in setting it up and your time in reviewing it - would you be interested in:

• A short docs PR describing the cache protocol and a minimal example of a shared/DB-backed cache for multi-instance setups?
• A discussion / more detailed description / anything alike about our custom-data-workaround and how this could be simplified or also documented?

We have a blog post describing our full solution that we're happy to share as a reference.

If we have missed something or did not understand specifics quite right we would be also grateful for feedback!