Standardized OAuth2 Callback Framework with PKCE for Functions & UserValves

[gkkachi]

Hi everyone, I'd like to propose a new framework to handle OAuth2 callbacks securely within Functions, specifically to support user-level API authentication.

The Problem

Currently, implementing the standard OAuth2 Authorization Code Flow securely within Open WebUI Functions is highly challenging.
I am trying to implement a custom Model via a Pipe Function that routes chat requests to Azure OpenAI using the individual user's Entra ID credentials.

Since Functions run in an isolated Python environment, they cannot dynamically expose a callback URL to receive the authorization code. As a result, developers are forced to use the "Device Code Flow," which significantly degrades the chat UX by forcing users to manually copy-paste codes into separate browser tabs.

Why existing alternatives aren't the right fit:

• MCP (Model Context Protocol): While MCP is excellent for Tools, I am building a custom Model (Pipe Function) that acts as the primary chat interface. MCP servers are structurally decoupled and intended for external tool calling, making them unsuitable for handling the core chat completion pipeline natively.
• Token Forwarding to Pipelines (e.g., feat: OWUI-to-Pipelines User Groups and Oauth Passing #23607): Recent discussions like feat: OWUI-to-Pipelines User Groups and Oauth Passing #23607 focus on forwarding the global WebUI login OAuth token to external Pipeline containers. While this is great for SSO, it doesn't solve the issue for native Functions. Functions need the ability to trigger arbitrary 3rd-party OAuth flows on-demand (not just the main login token) and store them securely within the native environment, without relying on external Pipeline containers.

The Proposed Solution

I propose implementing a generic, core-level OAuth callback framework that seamlessly integrates with UserValves. This would allow Functions (especially Pipes) to easily request user authentication, handle the callback natively, and securely receive tokens without needing external infrastructure.

Proposed Architecture:

1. Generic Callback Endpoint: Add a single, standardized endpoint to the core FastAPI backend (e.g., /api/v1/functions/oauth/callback).
2. Authorization Trigger: Provide a mechanism for a Function to trigger an OAuth flow (e.g., returning a specific JSON payload that prompts the UI to natively open the OAuth provider's login URL).
3. Secure State & PKCE Management: To ensure modern security standards against authorization code interception attacks, the core backend generates a secure state parameter (to prevent CSRF) and PKCE (Proof Key for Code Exchange) parameters (code_verifier and code_challenge). These are temporarily stored in the backend before redirecting the user's browser.
4. Token Exchange & Storage: Upon receiving the callback, the core backend securely exchanges the code for an access token using the stored PKCE code_verifier, and automatically injects the token into the specific UserValves for that user and Function.

Example Function Interface Idea:

from pydantic import BaseModel, Field

class Pipe:
    class UserValves(BaseModel):
        access_token: str = Field(default="", description="OAuth Access Token")

    def pipe(self, body: dict, __user__: dict):
        token = __user__.get("valves", {}).get("access_token")
        
        if not token:
            # Trigger standard OAuth flow handled by WebUI Core natively
            return {
                "action": "require_oauth",
                "auth_url": "[https://login.microsoftonline.com/](https://login.microsoftonline.com/)...",
                "client_id": "...",
                "scope": "...",
                "use_pkce": True # Instructs core to handle PKCE challenge/verifier
            }
        
        # Proceed with Azure OpenAI API call using the Bearer token

Enterprise Value (Additional Context)

As Open WebUI expands into enterprise environments, the need for secure, per-user authentication directly at the Model level becomes critical.

By providing a secure, PKCE-compliant built-in OAuth callback manager mapped to UserValves, we can unlock a massive ecosystem of API-integrated Pipe Functions securely.

I would love to hear your thoughts on this approach and whether this aligns with the architectural direction of Open WebUI!

[mkresse]

Hi,

we have the same requirement, but for (python based) Local Tools rather than Pipe Functions — a native, per-user OAuth2 Authorization Code flow so a Tool can authenticate the individual user against a 3rd-party API on demand. The architecture you describe fits our case almost exactly; the only real difference is the integration point (Tool call vs. pipe()).

Worth noting: most of this plumbing already exists for MCP tool servers; it just isn't generalized to Functions/Tools.

The MCP OAuth 2.1 path already implements nearly everything proposed here:

• Generic callback + authorize routes — /oauth/clients/{client_id}/{authorize,callback} (main.py). The client_id is just a path param; mcp:{server_id} is only a naming convention. A tool:{id} / function:{id} namespace would work with the same routes.
• PKCE + state — handled by Authlib in OAuthClientManager.add_client(), with state/code_verifier in the Starlette session.
• Token storage — the oauth_session table (provider = client_id), Fernet-encrypted at rest, with auto-refresh in get_oauth_token(). This is already DB-backed and multi-instance-safe — arguably a better home than UserValves for the token (UserValves could still hold non-secret config; cf. feat: encrypt user valve values at rest using Fernet #23721 for valve encryption).

So the gap is smaller than it looks: a way to register a per-Function/Tool OAuth client from persisted config, plus a lazy-loader so any instance can reconstruct it.

For multi-instance deployments, the per-Function/Tool client must be reconstructable on any worker (in-memory-only registration already causes 404s for MCP — see #22756).
ensure_client_from_config() is currently MCP-only; generalizing it to also resolve tool:/function: clients from a persisted source covers this with minimal core change.

Concretely, a minimal version of this proposal might be:

1. Persist OAuth client info (client_id/secret/issuer/scope) per Function/Tool (encrypted).
2. Generalize ensure_client_from_config() to reconstruct the client for non-MCP namespaces.
3. Reuse the existing routes + oauth_session storage unchanged.
4. UI trigger for consent on demand (overlaps with enh: Automatic auth flows for models with OAuth 2.1 tools enabled  #23325 / fix: surface OAuth auth prompt for default MCP tools via toast + popup #22341).

Happy to help prototype the Tools-oriented variant if there's maintainer interest in this direction.