Add docs for auth and rate limiting (#11773)

* docs

* changes

* add demo

* add changeset

* Update demo/rate_limit/run.py

* notebook

* add changeset

* Update gradio/components/login_button.py

Co-authored-by: Ali Abdalla <[email protected]>

---------

Co-authored-by: gradio-pr-bot <[email protected]>
Co-authored-by: Ali Abdalla <[email protected]>

Author: 3 people

.changeset/proud-boxes-tie.md

@@ -0,0 +1,5 @@
+---
+"gradio": patch
+---
+
+feat:Add docs for auth and rate limiting

demo/rate_limit/run.ipynb

@@ -0,0 +1 @@
+{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: rate_limit"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["import gradio as gr\n", "from datetime import datetime, timedelta\n", "from collections import defaultdict\n", "import threading\n", "\n", "rate_limit_data = defaultdict(list)\n", "lock = threading.Lock()\n", "\n", "UNAUTH_RATE_LIMIT = 3\n", "AUTH_RATE_LIMIT = 30\n", "RATE_LIMIT_WINDOW = 60\n", "\n", "def clean_old_entries(user_id):\n", "    \"\"\"Remove entries older than the rate limit window\"\"\"\n", "    current_time = datetime.now()\n", "    cutoff_time = current_time - timedelta(seconds=RATE_LIMIT_WINDOW)\n", "    rate_limit_data[user_id] = [\n", "        timestamp for timestamp in rate_limit_data[user_id]\n", "        if timestamp > cutoff_time\n", "    ]\n", "\n", "def get_user_identifier(profile: gr.OAuthProfile | None, request: gr.Request) -> tuple[str, bool]:\n", "    \"\"\"Get user identifier and whether they're authenticated\"\"\"\n", "    if profile is not None:\n", "        return profile.username, True\n", "    else:\n", "        if request:\n", "            return f\"ip_{request.client.host}\", False\n", "        return \"ip_unknown\", False\n", "\n", "def check_rate_limit(user_id: str, is_authenticated: bool) -> tuple[bool, int, int]:\n", "    \"\"\"\n", "    Check if user has exceeded rate limit\n", "    Returns: (can_proceed, clicks_used, max_clicks)\n", "    \"\"\"\n", "    with lock:\n", "        clean_old_entries(user_id)\n", "        \n", "        max_clicks = AUTH_RATE_LIMIT if is_authenticated else UNAUTH_RATE_LIMIT\n", "        clicks_used = len(rate_limit_data[user_id])\n", "        \n", "        can_proceed = clicks_used < max_clicks\n", "        \n", "        return can_proceed, clicks_used, max_clicks\n", "\n", "def add_click(user_id: str):\n", "    \"\"\"Add a click timestamp for the user\"\"\"\n", "    with lock:\n", "        rate_limit_data[user_id].append(datetime.now())\n", "\n", "def update_status(profile: gr.OAuthProfile | None, request: gr.Request) -> str:\n", "    \"\"\"Update the status message showing current rate limit info\"\"\"\n", "    user_id, is_authenticated = get_user_identifier(profile, request)\n", "    _, clicks_used, max_clicks = check_rate_limit(user_id, is_authenticated)\n", "    \n", "    if is_authenticated:\n", "        return f\"\u2705 You are logged in as '{profile.username}'. You have clicked {clicks_used} times this minute. You have {max_clicks} total clicks per minute.\"  # type: ignore\n", "    else:\n", "        return f\"\u26a0\ufe0f You are not logged in. You have clicked {clicks_used} times this minute. You have {max_clicks} total clicks per minute.\"\n", "\n", "def run_action(profile: gr.OAuthProfile | None, request: gr.Request) -> tuple[str, str]:\n", "    \"\"\"Handle the run button click with rate limiting\"\"\"\n", "    user_id, is_authenticated = get_user_identifier(profile, request)\n", "    can_proceed, clicks_used, max_clicks = check_rate_limit(user_id, is_authenticated)\n", "    \n", "    if not can_proceed:\n", "        result = f\"\u274c Rate limit exceeded! You've used all {max_clicks} clicks for this minute. Please wait before trying again.\"\n", "        status = update_status(profile, request)\n", "        return result, status\n", "    \n", "    add_click(user_id)\n", "    \n", "    _, new_clicks_used, _ = check_rate_limit(user_id, is_authenticated)\n", "    \n", "    result = f\"\u2705 Action executed successfully! (Click #{new_clicks_used})\"\n", "    status = update_status(profile, request)\n", "    \n", "    return result, status\n", "\n", "with gr.Blocks(title=\"Rate Limiting Demo\") as demo:\n", "    gr.Markdown(\"# Rate Limiting Demo App\")\n", "    gr.Markdown(\"This app demonstrates rate limiting based on authentication status.\")\n", "    \n", "    gr.LoginButton()\n", "    \n", "    status_text = gr.Markdown(\"Loading status...\")\n", "    \n", "    with gr.Row():\n", "        run_btn = gr.Button(\"\ud83d\ude80 Run Action\", variant=\"primary\", scale=1)\n", "    \n", "    result_text = gr.Markdown(\"\")\n", "    \n", "    demo.load(update_status, inputs=None, outputs=status_text)\n", "    \n", "    run_btn.click(\n", "        run_action,\n", "        inputs=None,\n", "        outputs=[result_text, status_text]\n", "    )\n", "    \n", "    gr.Markdown(\"---\")\n", "    gr.Markdown(\"\"\"\n", "    ### Rate Limits:\n", "    - **Not logged in:** 3 clicks per minute (based on IP address)\n", "    - **Logged in:** 30 clicks per minute (based on HF username)\n", "    \n", "    ### How it works:\n", "    - Click the **Login** button to authenticate with Hugging Face\n", "    - Click the **Run Action** button to test the rate limiting\n", "    - The system tracks your clicks over a rolling 1-minute window\n", "    \"\"\")\n", "\n", "if __name__ == \"__main__\":\n", "    demo.launch()\n"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

demo/rate_limit/run.py

@@ -0,0 +1,114 @@
+import gradio as gr
+from datetime import datetime, timedelta
+from collections import defaultdict
+import threading
+
+rate_limit_data = defaultdict(list)
+lock = threading.Lock()
+
+UNAUTH_RATE_LIMIT = 3
+AUTH_RATE_LIMIT = 30
+RATE_LIMIT_WINDOW = 60
+
+def clean_old_entries(user_id):
+    """Remove entries older than the rate limit window"""
+    current_time = datetime.now()
+    cutoff_time = current_time - timedelta(seconds=RATE_LIMIT_WINDOW)
+    rate_limit_data[user_id] = [
+        timestamp for timestamp in rate_limit_data[user_id]
+        if timestamp > cutoff_time
+    ]
+
+def get_user_identifier(profile: gr.OAuthProfile | None, request: gr.Request) -> tuple[str, bool]:
+    """Get user identifier and whether they're authenticated"""
+    if profile is not None:
+        return profile.username, True
+    else:
+        if request:
+            return f"ip_{request.client.host}", False
+        return "ip_unknown", False
+
+def check_rate_limit(user_id: str, is_authenticated: bool) -> tuple[bool, int, int]:
+    """
+    Check if user has exceeded rate limit
+    Returns: (can_proceed, clicks_used, max_clicks)
+    """
+    with lock:
+        clean_old_entries(user_id)
+        
+        max_clicks = AUTH_RATE_LIMIT if is_authenticated else UNAUTH_RATE_LIMIT
+        clicks_used = len(rate_limit_data[user_id])
+        
+        can_proceed = clicks_used < max_clicks
+        
+        return can_proceed, clicks_used, max_clicks
+
+def add_click(user_id: str):
+    """Add a click timestamp for the user"""
+    with lock:
+        rate_limit_data[user_id].append(datetime.now())
+
+def update_status(profile: gr.OAuthProfile | None, request: gr.Request) -> str:
+    """Update the status message showing current rate limit info"""
+    user_id, is_authenticated = get_user_identifier(profile, request)
+    _, clicks_used, max_clicks = check_rate_limit(user_id, is_authenticated)
+    
+    if is_authenticated:
+        return f"✅ You are logged in as '{profile.username}'. You have clicked {clicks_used} times this minute. You have {max_clicks} total clicks per minute."  # type: ignore
+    else:
+        return f"⚠️ You are not logged in. You have clicked {clicks_used} times this minute. You have {max_clicks} total clicks per minute."
+
+def run_action(profile: gr.OAuthProfile | None, request: gr.Request) -> tuple[str, str]:
+    """Handle the run button click with rate limiting"""
+    user_id, is_authenticated = get_user_identifier(profile, request)
+    can_proceed, clicks_used, max_clicks = check_rate_limit(user_id, is_authenticated)
+    
+    if not can_proceed:
+        result = f"❌ Rate limit exceeded! You've used all {max_clicks} clicks for this minute. Please wait before trying again."
+        status = update_status(profile, request)
+        return result, status
+    
+    add_click(user_id)
+    
+    _, new_clicks_used, _ = check_rate_limit(user_id, is_authenticated)
+    
+    result = f"✅ Action executed successfully! (Click #{new_clicks_used})"
+    status = update_status(profile, request)
+    
+    return result, status
+
+with gr.Blocks(title="Rate Limiting Demo") as demo:
+    gr.Markdown("# Rate Limiting Demo App")
+    gr.Markdown("This app demonstrates rate limiting based on authentication status.")
+    
+    gr.LoginButton()
+    
+    status_text = gr.Markdown("Loading status...")
+    
+    with gr.Row():
+        run_btn = gr.Button("🚀 Run Action", variant="primary", scale=1)
+    
+    result_text = gr.Markdown("")
+    
+    demo.load(update_status, inputs=None, outputs=status_text)
+    
+    run_btn.click(
+        run_action,
+        inputs=None,
+        outputs=[result_text, status_text]
+    )
+    
+    gr.Markdown("---")
+    gr.Markdown("""
+    ### Rate Limits:
+    - **Not logged in:** 3 clicks per minute (based on IP address)
+    - **Logged in:** 30 clicks per minute (based on HF username)
+    
+    ### How it works:
+    - Click the **Login** button to authenticate with Hugging Face
+    - Click the **Run Action** button to test the rate limiting
+    - The system tracks your clicks over a rolling 1-minute window
+    """)
+
+if __name__ == "__main__":
+    demo.launch()

gradio/components/login_button.py

@@ -22,10 +22,18 @@
 @document()
 class LoginButton(Button):
     """
-    Creates a button that redirects the user to Sign with Hugging Face using OAuth. If
-    created inside of a Blocks context, it will add an event to check if the user is logged in
-    and update the button text accordingly. If created outside of a Blocks context, call the
-    `LoginButton.activate()` method to add the event.
+    Creates a "Sign In" button that redirects the user to sign in with Hugging Face OAuth.
+    Once the user is signed in, the button will act as a logout button, and you can
+    retrieve a signed-in user's profile by adding a parameter of type `gr.OAuthProfile`
+    to any Gradio function. This will only work if this Gradio app is running in a
+    Hugging Face Space. Permissions for the OAuth app can be configured in the Spaces
+    README file, as described here: <a href="https://huggingface.co/docs/hub/en/spaces-oauth" target="_blank">Spaces OAuth Docs</a>.
+    For local development, instead of OAuth, the local Hugging Face account that is
+    logged in (via `hf auth login`) will be available through the `gr.OAuthProfile`
+    object.
+
+    Demos: login_with_huggingface
+    Guides: sharing-your-app
     """
 
     is_template = True

guides/04_additional-features/07_sharing-your-app.md

@@ -10,8 +10,10 @@ In this Guide, we dive more deeply into the various aspects of sharing a Gradio
 6. [Accessing network requests](#accessing-the-network-request-directly)
 7. [Mounting within FastAPI](#mounting-within-another-fast-api-app)
 8. [Authentication](#authentication)
-9. [Analytics](#analytics)
-10. [Progressive Web Apps (PWAs)](#progressive-web-app-pwa)
+9. [MCP Servers](#mcp-servers)
+10. [Rate Limits](#rate-limits)
+11. [Analytics](#analytics)
+12. [Progressive Web Apps (PWAs)](#progressive-web-app-pwa)
 
 ## Sharing Demos
 
@@ -421,6 +423,13 @@ if __name__ == '__main__':
 
 There are actually two separate Gradio apps in this example! One that simply displays a log in button (this demo is accessible to any user), while the other main demo is only accessible to users that are logged in. You can try this example out on [this Space](https://huggingface.co/spaces/gradio/oauth-example).
 
+## MCP Servers
+
+Gradio apps can function as MCP (Model Context Protocol) servers, allowing LLMs to use your app's functions as tools. By simply setting `mcp_server=True` in the `.launch()` method, Gradio automatically converts your app's functions into MCP tools that can be called by MCP clients like Claude Desktop, Cursor, or Cline. The server exposes tools based on your function names, docstrings, and type hints, and can handle file uploads, authentication headers, and progress updates. You can also create MCP-only functions using `gr.api` and expose resources and prompts using decorators. For a comprehensive guide on building MCP servers with Gradio, see [Building an MCP Server with Gradio](https://www.gradio.app/guides/building-mcp-server-with-gradio).
+
+## Rate Limits
+
+When publishing your app publicly, and making it available via API or via MCP server, you might want to set rate limits to prevent users from abusing your app. You can identify users using their IP address (using the `gr.Request` object [as discussed above](#accessing-the-network-request-directly)) or, if they are logged in via Hugging Face OAuth, using their username. To see a complete example of how to set rate limits, please see [this Gradio app](https://github.com/gradio-app/gradio/blob/main/demo/rate_limit/run.py).
 
 ## Analytics