"""
OAuth callback server for handling authorization code flows.
This module provides a reusable callback server that can handle OAuth redirects
and display styled responses to users.
"""
from __future__ import annotations
import asyncio
from dataclasses import dataclass
from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import HTMLResponse
from starlette.routing import Route
from uvicorn import Config, Server
from fastmcp.utilities.http import find_available_port
from fastmcp.utilities.logging import get_logger
logger = get_logger(__name__)
def create_callback_html(
message: str,
is_success: bool = True,
title: str = "FastMCP OAuth",
server_url: str | None = None,
) -> str:
"""Create a styled HTML response for OAuth callbacks."""
status_emoji = "✅" if is_success else "❌"
status_color = "#10b981" if is_success else "#ef4444" # emerald-500 / red-500
# Add server info for success cases
server_info = ""
if is_success and server_url:
server_info = f"""
Connected to: {server_url}
"""
return f"""
{title}
{status_emoji}
{message}
{server_info}
You can safely close this tab now.
"""
@dataclass
class CallbackResponse:
code: str | None = None
state: str | None = None
error: str | None = None
error_description: str | None = None
@classmethod
def from_dict(cls, data: dict[str, str]) -> CallbackResponse:
return cls(**{k: v for k, v in data.items() if k in cls.__annotations__})
def to_dict(self) -> dict[str, str]:
return {k: v for k, v in self.__dict__.items() if v is not None}
def create_oauth_callback_server(
port: int,
callback_path: str = "/callback",
server_url: str | None = None,
response_future: asyncio.Future | None = None,
) -> Server:
"""
Create an OAuth callback server.
Args:
port: The port to run the server on
callback_path: The path to listen for OAuth redirects on
server_url: Optional server URL to display in success messages
response_future: Optional future to resolve when OAuth callback is received
Returns:
Configured uvicorn Server instance (not yet running)
"""
async def callback_handler(request: Request):
"""Handle OAuth callback requests with proper HTML responses."""
query_params = dict(request.query_params)
callback_response = CallbackResponse.from_dict(query_params)
if callback_response.error:
error_desc = callback_response.error_description or "Unknown error"
# Resolve future with exception if provided
if response_future and not response_future.done():
response_future.set_exception(
RuntimeError(
f"OAuth error: {callback_response.error} - {error_desc}"
)
)
return HTMLResponse(
create_callback_html(
f"FastMCP OAuth Error: {callback_response.error}
{error_desc}",
is_success=False,
),
status_code=400,
)
if not callback_response.code:
# Resolve future with exception if provided
if response_future and not response_future.done():
response_future.set_exception(
RuntimeError("OAuth callback missing authorization code")
)
return HTMLResponse(
create_callback_html(
"FastMCP OAuth Error: No authorization code received",
is_success=False,
),
status_code=400,
)
# Check for missing state parameter (indicates OAuth flow issue)
if callback_response.state is None:
# Resolve future with exception if provided
if response_future and not response_future.done():
response_future.set_exception(
RuntimeError(
"OAuth server did not return state parameter - authentication failed"
)
)
return HTMLResponse(
create_callback_html(
"FastMCP OAuth Error: Authentication failed
The OAuth server did not return the expected state parameter",
is_success=False,
),
status_code=400,
)
# Success case
if response_future and not response_future.done():
response_future.set_result(
(callback_response.code, callback_response.state)
)
return HTMLResponse(
create_callback_html("FastMCP OAuth login complete!", server_url=server_url)
)
app = Starlette(routes=[Route(callback_path, callback_handler)])
return Server(
Config(
app=app,
host="127.0.0.1",
port=port,
lifespan="off",
log_level="warning",
)
)
if __name__ == "__main__":
"""Run a test server when executed directly."""
import webbrowser
import uvicorn
port = find_available_port()
print("🎭 OAuth Callback Test Server")
print("📍 Test URLs:")
print(f" Success: http://localhost:{port}/callback?code=test123&state=xyz")
print(
f" Error: http://localhost:{port}/callback?error=access_denied&error_description=User%20denied"
)
print(f" Missing: http://localhost:{port}/callback")
print("🛑 Press Ctrl+C to stop")
print()
# Create test server without future (just for testing HTML responses)
server = create_oauth_callback_server(
port=port, server_url="https://fastmcp-test-server.example.com"
)
# Open browser to success example
webbrowser.open(f"http://localhost:{port}/callback?code=test123&state=xyz")
# Run with uvicorn directly
uvicorn.run(
server.config.app,
host="127.0.0.1",
port=port,
log_level="warning",
access_log=False,
)