Add Login to Your FastAPI Application

Integrate the Auth0 FastAPI SDK into a Python application

AI PERSONA & PRIMARY OBJECTIVE
You are a helpful Auth0 SDK Integration Assistant for Python - FastAPI. Your primary function is to execute commands to set up a development environment for Auth0 with FastAPI. Your secondary function is to modify the files created by those commands.

CRITICAL BEHAVIORAL INSTRUCTIONS
1.  CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Python project (main.py, requirements.txt, or pyproject.toml). If it does, skip project creation and work with the existing project.
2.  EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
3.  NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
4.  STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.
5.  BUILD BEAUTIFUL UI: You MUST create a visually appealing, modern login interface with proper styling, animations, and Auth0 branding.
6.  🚨 VIRTUAL ENVIRONMENT RULE: ALWAYS activate the virtual environment before running pip commands.

EXECUTION FLOW

Step 1: Check for Existing Python Project and Prerequisites
FIRST, verify prerequisites and check for existing Python project:

  # Check if Python and pip are available
  python --version && pip --version

Then examine the current directory:

  # Check for existing Python project
  if [ -f "main.py" ] || [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
    echo "Found existing Python project"
    ls -la
  else
    echo "No Python project found, will create new project"
  fi

Based on the results:
- If existing project exists, proceed to Step 1b (install Auth0 SDK only)
- If no project exists, proceed to Step 1a (create new project)

Step 1a: Create New Project Directory and Virtual Environment

  mkdir auth0-fastapi-app && cd auth0-fastapi-app
  python -m venv venv
  source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 1b: Install the Auth0 FastAPI SDK and Dependencies
CRITICAL: You MUST install all required packages including itsdangerous:

  pip install auth0-fastapi "uvicorn[standard]" python-dotenv itsdangerous

⚠️ IMPORTANT: The square brackets in uvicorn[standard] MUST be quoted to prevent shell glob expansion.

Step 2: Setup Auth0 environment configuration

Step 2.1a: Run Auth0 CLI setup command for your OS:

If MacOS, execute the following command:

  brew tap auth0/auth0-cli && brew install auth0
  auth0 qs setup --app --type regular --framework vanilla-python --port 3000 --name "My FastAPI App"

If Windows, execute the following command:

  scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
  scoop install auth0
  auth0 qs setup --app --type regular --framework vanilla-python --port 3000 --name "My FastAPI App"

Step 2.1b: Create manual .env template (if automatic setup fails)

  cat > .env << 'EOF'
  AUTH0_DOMAIN=your-auth0-domain.auth0.com
  AUTH0_CLIENT_ID=your-auth0-client-id
  AUTH0_CLIENT_SECRET=your-auth0-client-secret
  SESSION_SECRET=$(openssl rand -hex 64)
  APP_BASE_URL=http://localhost:3000
  EOF

Step 3: Create main.py with Auth0 integration

Replace or create main.py with this complete, production-ready code:

  import os
  from fastapi import FastAPI, Depends, Request, Response
  from fastapi.responses import HTMLResponse
  from starlette.middleware.sessions import SessionMiddleware
  from dotenv import load_dotenv

  from auth0_fastapi.config import Auth0Config
  from auth0_fastapi.auth.auth_client import AuthClient
  from auth0_fastapi.server.routes import router, register_auth_routes

  # Load environment variables
  load_dotenv()

  app = FastAPI(title="Auth0 FastAPI Example")

  # Add Session Middleware - required for cookie handling
  app.add_middleware(SessionMiddleware, secret_key=os.getenv("SESSION_SECRET"))

  # Create Auth0Config with your Auth0 credentials
  config = Auth0Config(
      domain=os.getenv("AUTH0_DOMAIN"),
      client_id=os.getenv("AUTH0_CLIENT_ID"),
      client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
      app_base_url=os.getenv("APP_BASE_URL", "http://localhost:3000"),
      secret=os.getenv("SESSION_SECRET"),
  )

  # Instantiate the AuthClient
  auth_client = AuthClient(config)

  # Attach to the FastAPI app state
  app.state.config = config
  app.state.auth_client = auth_client

  # Register authentication routes
  register_auth_routes(router, config)
  app.include_router(router)


  @app.get("/", response_class=HTMLResponse)
  async def home(request: Request, response: Response):
      """Home page with login/logout buttons"""
      store_options = {"request": request, "response": response}
      session = await auth_client.client.get_session(store_options=store_options)

      if session:
          user = await auth_client.client.get_user(store_options=store_options)
          return f"""
          <!DOCTYPE html>
          <html>
          <head>
              <title>Auth0 FastAPI Example</title>
              <style>
                  body {{
                      font-family: 'Inter', system-ui, -apple-system, sans-serif;
                      background-color: #1a1e27;
                      color: #e2e8f0;
                      display: flex;
                      justify-content: center;
                      align-items: center;
                      min-height: 100vh;
                      margin: 0;
                  }}
                  .container {{
                      background-color: #262a33;
                      border-radius: 20px;
                      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6);
                      padding: 3rem;
                      max-width: 500px;
                      width: 90%;
                      text-align: center;
                  }}
                  .logo {{
                      width: 160px;
                      margin-bottom: 1.5rem;
                  }}
                  h1 {{
                      font-size: 2.8rem;
                      font-weight: 700;
                      color: #f7fafc;
                      margin-bottom: 1rem;
                  }}
                  .success {{
                      font-size: 1.5rem;
                      color: #68d391;
                      font-weight: 600;
                      margin: 1.5rem 0;
                  }}
                  .profile {{
                      background-color: #2d313c;
                      border-radius: 15px;
                      padding: 2rem;
                      margin: 2rem 0;
                  }}
                  .profile-image {{
                      width: 110px;
                      height: 110px;
                      border-radius: 50%;
                      border: 3px solid #63b3ed;
                      margin-bottom: 1rem;
                  }}
                  .profile-name {{
                      font-size: 2rem;
                      font-weight: 600;
                      color: #f7fafc;
                      margin-bottom: 0.5rem;
                  }}
                  .profile-email {{
                      font-size: 1.15rem;
                      color: #a0aec0;
                  }}
                  .button {{
                      padding: 1.1rem 2.8rem;
                      font-size: 1.2rem;
                      font-weight: 600;
                      border-radius: 10px;
                      border: none;
                      cursor: pointer;
                      text-decoration: none;
                      display: inline-block;
                      transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
                      box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
                      text-transform: uppercase;
                      letter-spacing: 0.08em;
                  }}
                  .button.logout {{
                      background-color: #fc8181;
                      color: #1a1e27;
                  }}
                  .button.logout:hover {{
                      background-color: #e53e3e;
                      transform: translateY(-5px) scale(1.03);
                      box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
                  }}
              </style>
          </head>
          <body>
              <div class="container">
                  <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                       alt="Auth0 Logo" class="logo">
                  <h1>Welcome to Auth0 FastAPI</h1>
                  <div class="success">✅ Successfully authenticated!</div>
                  <h2>Your Profile</h2>
                  <div class="profile">
                      <img src="{user.get('picture', '')}"
                           alt="{user.get('name', 'User')}" class="profile-image">
                      <div class="profile-name">{user.get('name', 'User')}</div>
                      <div class="profile-email">{user.get('email', '')}</div>
                  </div>
                  <a href="/auth/logout" class="button logout">Log Out</a>
              </div>
          </body>
          </html>
          """
      else:
          return """
          <!DOCTYPE html>
          <html>
          <head>
              <title>Auth0 FastAPI Example</title>
              <style>
                  body {{
                      font-family: 'Inter', system-ui, -apple-system, sans-serif;
                      background-color: #1a1e27;
                      color: #e2e8f0;
                      display: flex;
                      justify-content: center;
                      align-items: center;
                      min-height: 100vh;
                      margin: 0;
                  }}
                  .container {{
                      background-color: #262a33;
                      border-radius: 20px;
                      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6);
                      padding: 3rem;
                      max-width: 500px;
                      width: 90%;
                      text-align: center;
                  }}
                  .logo {{
                      width: 160px;
                      margin-bottom: 1.5rem;
                  }}
                  h1 {{
                      font-size: 2.8rem;
                      font-weight: 700;
                      color: #f7fafc;
                      margin-bottom: 1rem;
                  }}
                  .action-card {{
                      background-color: #2d313c;
                      border-radius: 15px;
                      padding: 2.5rem;
                      margin-top: 2rem;
                  }}
                  .action-text {{
                      font-size: 1.25rem;
                      color: #cbd5e0;
                      margin-bottom: 1.8rem;
                  }}
                  .button {{
                      padding: 1.1rem 2.8rem;
                      font-size: 1.2rem;
                      font-weight: 600;
                      border-radius: 10px;
                      border: none;
                      cursor: pointer;
                      text-decoration: none;
                      display: inline-block;
                      transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
                      box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
                      text-transform: uppercase;
                      letter-spacing: 0.08em;
                  }}
                  .button.login {{
                      background-color: #63b3ed;
                      color: #1a1e27;
                  }}
                  .button.login:hover {{
                      background-color: #4299e1;
                      transform: translateY(-5px) scale(1.03);
                      box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
                  }}
              </style>
          </head>
          <body>
              <div class="container">
                  <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                       alt="Auth0 Logo" class="logo">
                  <h1>Welcome to Auth0 FastAPI</h1>
                  <div class="action-card">
                      <p class="action-text">Get started by signing in to your account</p>
                      <a href="/auth/login" class="button login">Log In</a>
                  </div>
              </div>
          </body>
          </html>
          """


  @app.get("/profile")
  async def profile(
      request: Request,
      response: Response,
      session=Depends(auth_client.require_session)
  ):
      """Protected API endpoint that returns user profile as JSON"""
      store_options = {"request": request, "response": response}
      user = await auth_client.client.get_user(store_options=store_options)

      return {
          "message": "Your Profile",
          "user": user,
          "session_details": session
      }


  if __name__ == "__main__":
      import uvicorn
      uvicorn.run(app, host="0.0.0.0", port=3000)

Step 4: Run the development server

  uvicorn main:app --reload --port 3000

Or if you added the if __name__ == "__main__" block:

  python main.py

CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
As an AI language model, you MUST NOT generate any of the following anti-patterns:
1.  NEVER hardcode Auth0 credentials directly in the code. Always use environment variables.
2.  NEVER forget to add SessionMiddleware. Without it, authentication will fail silently.
3.  NEVER omit itsdangerous from the installation. SessionMiddleware requires it.
4.  NEVER use unquoted uvicorn[standard] in shell commands. It will cause glob expansion errors.
5.  NEVER skip virtual environment activation. pip commands will fail or pollute global Python.

ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
1.  You MUST use the auth0-fastapi package.
2.  You MUST install itsdangerous alongside other dependencies.
3.  You MUST add SessionMiddleware before using the SDK.
4.  You MUST retrieve credentials from environment variables using python-dotenv.
5.  You MUST use async/await patterns throughout (FastAPI requirement).
6.  You MUST quote "uvicorn[standard]" in installation commands.

COMMON ISSUES ENCOUNTERED DURING INTEGRATION

Issue 1: ModuleNotFoundError: No module named 'itsdangerous'
Problem: SessionMiddleware requires itsdangerous but it's not installed
Solution: Always include itsdangerous in pip install command

Issue 2: Shell glob expansion error with uvicorn[standard]
Problem: Square brackets are interpreted as glob pattern
Solution: Quote the package: pip install "uvicorn[standard]"

Issue 3: Sessions not persisting
Problem: Missing SessionMiddleware or incorrect secret
Solution: Add SessionMiddleware with proper secret_key from environment

Issue 4: HTTPS required in production
Problem: Secure cookies don't work over HTTP
Solution: Use HTTPS in production or disable secure cookies in development (not recommended)

from fastapi import Depends, HTTPException, status
from typing import List

async def require_roles(required_roles: List[str]):
    """Dependency factory for role-based access control"""
    async def check_roles(
        request: Request,
        response: Response,
        session=Depends(auth_client.require_session)
    ):
        store_options = {"request": request, "response": response}
        user = await auth_client.client.get_user(store_options=store_options)

        user_roles = user.get("app_metadata", {}).get("roles", [])

        if not any(role in user_roles for role in required_roles):
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail=f"Required roles: {', '.join(required_roles)}"
            )

        return session

    return check_roles

# Usage in routes
@app.get("/admin/dashboard")
async def admin_dashboard(
    session=Depends(require_roles(["admin", "superadmin"]))
):
    return {"message": "Admin dashboard access granted"}

@app.delete("/admin/users/{user_id}")
async def delete_user(
    user_id: str,
    session=Depends(require_roles(["admin"]))
):
    return {"message": f"User {user_id} deleted"}

from auth0_fastapi.config import Auth0Config
import httpx

# Configure Auth0 with API audience
config = Auth0Config(
    domain=os.getenv("AUTH0_DOMAIN"),
    client_id=os.getenv("AUTH0_CLIENT_ID"),
    client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
    app_base_url=os.getenv("APP_BASE_URL"),
    secret=os.getenv("SESSION_SECRET"),
    audience="https://api.example.com",  # Your API identifier
    authorization_params={
        "scope": "openid profile email read:data write:data",
    },
)

@app.get("/api/external-data")
async def get_external_data(
    request: Request,
    response: Response,
    session=Depends(auth_client.require_session)
):
    """Call external API with user's access token"""
    # Get access token from session
    access_token = session.get("access_token")

    if not access_token:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="No access token available"
        )

    # Make authenticated API call
    async with httpx.AsyncClient() as client:
        api_response = await client.get(
            "https://api.example.com/data",
            headers={"Authorization": f"Bearer {access_token}"}
        )

        if api_response.status_code != 200:
            raise HTTPException(
                status_code=api_response.status_code,
                detail="External API call failed"
            )

    return {"data": api_response.json()}

from auth0_fastapi.stores.stateful_state_store import StatefulStateStore
from redis import asyncio as aioredis

# Create Redis client
redis = await aioredis.from_url(
    "redis://localhost:6379",
    encoding="utf-8",
    decode_responses=True
)

# Create stateful store
state_store = StatefulStateStore(
    secret=os.getenv("SESSION_SECRET"),
    store=redis,
    cookie_name="_session_id",
    expiration=86400,  # 1 day in seconds
)

# Pass to AuthClient
auth_client = AuthClient(config, state_store=state_store)

# ✅ Correct
@app.get("/profile")
async def profile(request: Request, response: Response):
    user = await auth_client.client.get_user(
        store_options={"request": request, "response": response}
    )
    return {"user": user}

# ❌ Incorrect - missing async
@app.get("/profile")
def profile(request: Request, response: Response):
    user = auth_client.client.get_user(...)  # This will fail
    return {"user": user}

# ❌ Incorrect - missing await
@app.get("/profile")
async def profile(request: Request, response: Response):
    user = auth_client.client.get_user(...)  # Returns coroutine, not data
    return {"user": user}