API FastAPI

Découvrez comment ajouter l’authentification JWT d’Auth0 à un backend FastAPI en Python, en validant les jetons d’accès et en protégeant les points de terminaison selon l’audience et la scope.

Consigne pour l’IA

Vous utilisez l’IA pour intégrer Auth0 ? Ajoutez cette invite à Cursor, Windsurf, Copilot, Claude Code ou votre IDE préféré propulsé par l’IA pour accélérer le développement.

Integrate the Auth0 FastAPI SDK into a Python API

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

CRITICAL BEHAVIORAL INSTRUCTIONS
1. CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Python project (requirements.txt, pyproject.toml, or .py files). 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. SECURITY FIRST: NEVER hardcode Auth0 Domain or Audience values. ALWAYS use environment variables via python-dotenv.
6. 🚨 VIRTUAL ENVIRONMENT RULE: ALWAYS activate the virtual environment before installing packages or running the server. Never skip venv activation.

EXECUTION FLOW

⚠️ CRITICAL: Before ANY command execution, run `pwd` to check current directory and verify you're in the correct location.

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

  # Check if Python 3.9+ and pip are available
  python3 --version && pip --version

Then examine the current directory:

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

Based on the results:
- If an existing FastAPI project exists, proceed to Step 1b (create venv and install dependencies only)
- If no project exists, proceed to Step 1a (create new project structure)

Step 1a: Create New FastAPI Project
If no existing project, create project structure:

  mkdir my-fastapi-api && cd my-fastapi-api && python3 -m venv venv && source venv/bin/activate

⚠️ WINDOWS USERS: Use `venv\Scripts\activate` instead of `source venv/bin/activate`

Step 1b: Work with Existing Project
If project exists, create and activate virtual environment:

  python3 -m venv venv && source venv/bin/activate

Step 2: Install Dependencies
Create requirements.txt with the following content:

  cat > requirements.txt << 'EOF'
  fastapi>=0.115.0
  uvicorn[standard]>=0.34.0
  auth0-fastapi-api>=1.0.0b5
  python-dotenv>=1.0.0
  EOF

Then install dependencies (MUST be in activated venv):

  pip install -r requirements.txt

Step 3: Setup Auth0 API

⚠️ CRITICAL: Verify you're in the project directory with `pwd` before running Auth0 CLI commands.

Step 3a: Execute Auth0 CLI Setup

If MacOS, execute:

  AUTH0_API_NAME="My FastAPI API" && AUTH0_API_IDENTIFIER="https://my-fastapi-api" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --signing-alg RS256 --no-input && echo "AUTH0_DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name')\nAUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" > .env

If Windows, execute:

  $ApiName = "My FastAPI API"; $ApiIdentifier = "https://my-fastapi-api"; auth0 login --no-input; auth0 apis create -n $ApiName -i $ApiIdentifier --signing-alg RS256 --no-input; $ActiveTenant = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; "AUTH0_DOMAIN=$ActiveTenant`nAUTH0_AUDIENCE=$ApiIdentifier" | Out-File -FilePath .env -Encoding utf8

Step 3b: Verify .env file was created correctly

  cat .env

Expected output:
  AUTH0_DOMAIN=your-domain.auth0.com
  AUTH0_AUDIENCE=https://my-fastapi-api

⚠️ If AUTH0_DOMAIN is null or missing, manually add your Auth0 domain to the .env file.

Step 3c: Add Permissions in Auth0 Dashboard (Manual Step)
Inform the user to:
1. Navigate to Applications > APIs in Auth0 Dashboard
2. Select "My FastAPI API"
3. Go to Permissions tab
4. Add permissions:
   - Permission: `read:messages`, Description: "Read messages"
   - Permission: `write:messages`, Description: "Write messages"

Step 4: Create FastAPI Application with Auth0
Create app.py with the following content:

  cat > app.py << 'EOF'
  from fastapi import FastAPI, Depends
  from fastapi_plugin.fast_api_client import Auth0FastAPI
  import os
  from dotenv import load_dotenv

  # Load environment variables
  load_dotenv()

  app = FastAPI()

  # Initialize Auth0
  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE")
  )

  # Public route - no authentication required
  @app.get("/api/public")
  async def public():
      return {
          "message": "Hello from a public endpoint! You don't need to be authenticated to see this."
      }

  # Protected route - requires authentication
  @app.get("/api/private")
  async def private(claims: dict = Depends(auth0.require_auth())):
      return {
          "message": "Hello from a private endpoint! You need to be authenticated to see this.",
          "user_id": claims.get("sub")
      }

  # Scoped route - requires specific permission
  @app.get("/api/private-scoped")
  async def private_scoped(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
      return {
          "message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
          "user_id": claims.get("sub")
      }
  EOF

Step 5: Run the FastAPI Application

⚠️ CRITICAL: Verify virtual environment is activated before running uvicorn.

  # Vérifier que le venv est activé (vous devriez voir (venv) dans votre invite de commandes)
  which python

  # Démarrer le serveur
  uvicorn app:app --reload

Expected output: Server starts on http://127.0.0.1:8000

Step 6: Test the API

6a: Test public endpoint (no authentication required):

  curl http://localhost:8000/api/public

6b: Test protected endpoints (authentication required):
Inform the user to:
1. Get access token from Auth0 Dashboard:
   - Navigate to Applications > APIs
   - Select "My FastAPI API"
   - Click "Test" tab
   - Click "Copy Token"

2. Test private endpoint:

  curl -X GET http://localhost:8000/api/private -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

3. Test scoped endpoint:

  curl -X GET http://localhost:8000/api/private-scoped -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

ANTI-PATTERNS - NEVER DO THESE

1. ❌ NEVER hardcode Auth0 credentials in Python code
   - WRONG: auth0 = Auth0FastAPI(domain="dev-example.us.auth0.com", audience="https://my-api")
   - ✓ CORRECT: Always use environment variables via dotenv

2. ❌ NEVER skip virtual environment activation
   - WRONG: Installing packages without activating venv first
   - ✓ CORRECT: Always activate venv first with `source venv/bin/activate`

3. ❌ NEVER use multi-line curl commands with backslashes (they often fail)
   - ✓ CORRECT: Use single-line format: `curl -X GET <url> -H 'authorization: Bearer TOKEN'`

4. ❌ NEVER proceed if .env file has null values
   - WRONG: AUTH0_DOMAIN=null in .env file
   - ✓ CORRECT: Verify .env contains valid Auth0 domain before proceeding

ABSOLUTE REQUIREMENTS

1. ✓ Virtual environment MUST be activated before pip install
2. ✓ .env file MUST contain valid AUTH0_DOMAIN (not null)
3. ✓ .env file MUST be added to .gitignore to prevent credential exposure
4. ✓ Auth0FastAPI MUST use os.environ.get() for credentials
5. ✓ All endpoints requiring authentication MUST use Depends(auth0.require_auth())

COMMON ISSUES & SOLUTIONS

1. **ModuleNotFoundError: No module named 'fastapi_plugin'**
   - Cause : Mauvais environnement virtuel activé ou environnement virtuel non activé
   - Solution : Désactiver tous les environnements virtuels, puis activer le bon dans le répertoire du projet

2. **AUTH0_DOMAIN est null dans .env**
   - Cause : La commande CLI Auth0 n'extrait pas correctement le domaine
   - Solution : Ajouter manuellement le domaine au fichier .env depuis le tableau de bord Auth0

3. **401 Non autorisé - Émetteur invalide**
   - Cause : AUTH0_DOMAIN inclut le protocole https://
   - Solution : Le domaine doit être simplement `dev-example.us.auth0.com` sans protocole

4. **401 Non autorisé - Audience invalide**
   - Cause : AUTH0_AUDIENCE ne correspond pas à l'identifiant de l'API
   - Solution : Vérifier que AUTH0_AUDIENCE correspond exactement à l'identifiant dans le tableau de bord Auth0

5. **403 Interdit - Scope insuffisant**
   - Cause : Le token d'accès n'inclut pas le scope requis
   - Solution : Vérifier que les permissions existent dans le tableau de bord Auth0 et que le token les inclut

LISTE DE VALIDATION

Avant de considérer l'intégration comme complète, vérifier :
- [ ] L'environnement virtuel est activé (vérifier avec `which python`)
- [ ] Le fichier .env existe et contient un AUTH0_DOMAIN valide (pas null)
- [ ] .env est ajouté à .gitignore
- [ ] app.py importe et initialise Auth0FastAPI correctement
- [ ] Le point de terminaison public renvoie 200 OK sans authentification
- [ ] Le point de terminaison privé renvoie 401 sans token
- [ ] Le point de terminaison privé renvoie 200 avec un token valide
- [ ] Le point de terminaison avec scope renvoie 403 sans le scope requis
- [ ] Le point de terminaison avec scope renvoie 200 avec un token contenant le scope read:messages

Ce Quickstart nécessite :

• Python 3.9 ou une version ultérieure
• le gestionnaire de paquets pip
• jq - Requis pour la configuration d’Auth0 CLI
• une connaissance de FastAPI

Si ce n’est pas déjà fait, inscrivez-vous pour obtenir un compte Auth0 gratuit afin de suivre ce guide.

Ce guide montre comment intégrer Auth0 à une API FastAPI pour ajouter l’authentification et protéger vos endpoints.

1. Créer un nouveau projet FastAPI

   Créez un nouveau répertoire pour votre projet FastAPI et mettez en place un environnement virtuel.

   mkdir my-fastapi-api
   cd my-fastapi-api
   python3 -m venv venv
   source venv/bin/activate  # Windows : venv\Scripts\activate
   
2. Installer les dépendances

   Créez un fichier requirements.txt contenant les dépendances suivantes :

   requirements.txt

   fastapi>=0.115.0
   uvicorn[standard]>=0.34.0
   auth0-fastapi-api>=1.0.0b5
   python-dotenv>=1.0.0
   

   Installez les dépendances :

   pip install -r requirements.txt
   
3. Configurez votre API Auth0

   Vous devrez créer une API Auth0 pour représenter votre application FastAPI.

   Dashboard

   1. Accédez à Applications > APIs dans le Auth0 Dashboard
   2. Cliquez sur Create API
   3. Saisissez un Name pour votre API (p. ex., “My FastAPI API”)
   4. Définissez l’Identifier sur l’identifiant de votre API (p. ex., https://my-fastapi-api)
   5. Laissez le Signing Algorithm à RS256
   6. Cliquez sur Create

   CLI

   Si vous avez installé l’Auth0 CLI, vous pouvez créer une API et configurer votre environnement à partir de votre terminal :

   Mac

   AUTH0_API_NAME="My FastAPI API" && AUTH0_API_IDENTIFIER="https://my-fastapi-api" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --signing-alg RS256 --no-input && echo "AUTH0_DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name')\nAUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" > .env
   

   Cette opération créera votre API et générera automatiquement un fichier .env avec votre configuration Auth0.

   L’Identifier est un identifiant unique pour votre API. Nous vous recommandons d’utiliser une URL, mais elle n’a pas à être accessible publiquement — Auth0 n’y enverra aucune requête. Cette valeur ne peut pas être modifiée par la suite.

   Prenez en note les valeurs Domain et Identifier (Audience). Vous en aurez besoin à l’étape suivante.

4. Définir les permissions d’API

   Les permissions (aussi appelées scopes) vous permettent de définir comment il est possible d’accéder à votre API. Vous pouvez créer des permissions pour votre API dans l’Auth0 Dashboard.

   1. Dans l’Auth0 Dashboard, accédez à l’onglet Permissions de votre API
   2. Ajoutez les permissions suivantes :
      • read:messages avec la description “Lire les messages”
      • write:messages avec la description “Écrire les messages”

   Ces permissions serviront à contrôler l’accès à des points de terminaison précis de votre API.

5. Configurer le client Auth0

   Créez un fichier .env à la racine de votre projet pour y stocker votre configuration Auth0 :

   .env

   AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
   AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
   

   Remplacez YOUR_AUTH0_DOMAIN par votre domaine Auth0 (p. ex. dev-abc123.us.auth0.com) et YOUR_API_IDENTIFIER par l’identifiant que vous avez défini lors de la création de votre API.

   Ne validez jamais votre fichier .env dans le contrôle de version. Ajoutez-le à votre fichier .gitignore afin de protéger vos informations d’identification.

   Créez maintenant un fichier app.py et initialisez votre application FastAPI avec Auth0 :

   app.py

   from fastapi import FastAPI, Depends
   from fastapi_plugin.fast_api_client import Auth0FastAPI
   import os
   from dotenv import load_dotenv
   
   # Charger les variables d'environnement
   load_dotenv()
   
   app = FastAPI()
   
   # Initialiser Auth0
   auth0 = Auth0FastAPI(
       domain=os.environ.get("AUTH0_DOMAIN"),
       audience=os.environ.get("AUTH0_AUDIENCE")
   )
   
6. Créer des routes protégées

   Ajoutez les routes suivantes à votre fichier app.py. Ces routes illustrent différents niveaux de contrôle d’accès :

   app.py

   from fastapi import FastAPI, Depends
   from fastapi_plugin.fast_api_client import Auth0FastAPI
   import os
   from dotenv import load_dotenv
   
   load_dotenv()
   
   app = FastAPI()
   
   auth0 = Auth0FastAPI(
       domain=os.environ.get("AUTH0_DOMAIN"),
       audience=os.environ.get("AUTH0_AUDIENCE")
   )
   
   # Route publique - aucune authentification requise
   @app.get("/api/public")
   async def public():
       return {
           "message": "Hello from a public endpoint! You don't need to be authenticated to see this."
       }
   
   # Route protégée - authentification requise
   @app.get("/api/private")
   async def private(claims: dict = Depends(auth0.require_auth())):
       return {
           "message": "Hello from a private endpoint! You need to be authenticated to see this.",
           "user_id": claims.get("sub")
       }
   
   # Route avec portée - permission spécifique requise
   @app.get("/api/private-scoped")
   async def private_scoped(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
       return {
           "message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
           "user_id": claims.get("sub")
       }
   

   La méthode require_auth() valide le jeton d’accès envoyé dans l’en-tête Authorization. Lorsqu’elle est appelée avec le paramètre scopes, elle vérifie également que le jeton contient la permission spécifiée.

7. Exécutez votre API

   Démarrez votre application FastAPI :

   uvicorn app:app --reload
   

   Votre API est maintenant accessible à l’adresse http://localhost:8000.

   Ouvrez http://localhost:8000/api/public dans votre navigateur. Vous devriez voir le message public sans devoir vous authentifier.

---

​

Testez votre API

Pour tester les points de terminaison protégés, vous devrez obtenir un jeton d’accès auprès d’Auth0.

​

Obtenir un jeton d’accès

La façon la plus simple d’obtenir un jeton d’accès pour effectuer des tests est de passer par l’Auth0 Dashboard :

1. Accédez à Applications > APIs dans l’Auth0 Dashboard
2. Sélectionnez votre API
3. Cliquez sur l’onglet Test
4. Cliquez sur Copy Token dans la section Asking Auth0 for tokens from my application

​

Interrogez votre API

Utilisez le jeton d’accès pour effectuer une requête à votre point de terminaison protégé :

curl -X GET http://localhost:8000/api/private -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

Vous devriez recevoir une réponse contenant le message privé et votre ID d’utilisateur.

Pour tester ce point de terminaison à portée limitée, assurez-vous que votre jeton inclut la portée read:messages :

curl -X GET http://localhost:8000/api/private-scoped -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

Si votre token ne comporte pas le scope requis, vous recevrez une réponse 403 Forbidden.

---

​

Utilisation avancée

Valider les claims personnalisés

Vous pouvez accéder aux claims personnalisés ajoutés au jeton d’accès au moyen d’Auth0 Actions.

Accédez aux claims personnalisés dans votre handler de route :

@app.get("/api/profile")
async def profile(claims: dict = Depends(auth0.require_auth())):
    return {
        "user_id": claims.get("sub"),
        "email": claims.get("email"),
        "permissions": claims.get("permissions", []),
        "custom_claim": claims.get("https://myapp.example.com/custom_claim")
    }

Pour ajouter des claims personnalisés à vos jetons d’accès, créez une Auth0 Action :

1. Accédez à Actions > Library dans l’Auth0 Dashboard
2. Cliquez sur Create Action
3. Sélectionnez Build from scratch
4. Donnez un nom à votre action et sélectionnez le Trigger Login / Post Login
5. Ajoutez vos claims personnalisés :

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://myapp.example.com';

  if (event.authorization) {
    // Ajouter un claim personnalisé au jeton d'accès
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.user.app_metadata.roles || []);
  }
};

6. Cliquez sur Deploy et ajoutez l’action à votre Login flow

Les claims personnalisés doivent utiliser un format avec espace de noms (p. ex. https://myapp.example.com/claim_name) afin d’éviter les conflits avec les claims standard.

Protéger des endpoints sans utiliser de claims

Si vous devez protéger un endpoint sans avoir besoin d’accéder aux claims, vous pouvez utiliser le paramètre dependencies :

@app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
async def protected():
    return {"message": "This endpoint is protected"}

Cela valide le jeton d’accès, sans injecter les claims dans votre fonction.

Soutien pour DPoP

DPoP (Demonstrating Proof-of-Possession) est actuellement en Early Access. Communiquez avec Auth0 soutien pour l’activer pour votre tenant.

DPoP offre une sécurité renforcée en liant cryptographiquement les jetons d’accès au client qui les a demandés. Cela aide à prévenir le vol de jetons et les replay attacks.

Le SDK active le soutien pour DPoP par défaut. Vous pouvez configurer le comportement de DPoP :

auth0 = Auth0FastAPI(
    domain=os.environ.get("AUTH0_DOMAIN"),
    audience=os.environ.get("AUTH0_AUDIENCE"),
    dpop_enabled=True,      # Activer DPoP (par défaut : True)
    dpop_required=False     # Exiger DPoP (par défaut : False)
)

Mode mixte (par défaut) accepte à la fois les jetons Bearer et DPoP :

auth0 = Auth0FastAPI(
    domain=os.environ.get("AUTH0_DOMAIN"),
    audience=os.environ.get("AUTH0_AUDIENCE"),
    dpop_enabled=True,
    dpop_required=False
)

Mode DPoP בלבד rejette les jetons Bearer :

auth0 = Auth0FastAPI(
    domain=os.environ.get("AUTH0_DOMAIN"),
    audience=os.environ.get("AUTH0_AUDIENCE"),
    dpop_required=True
)

Lorsque vous utilisez DPoP, les clients doivent inclure à la fois les en-têtes Authorization: DPoP <token> et DPoP: <proof>. Le SDK valide automatiquement la preuve DPoP et l’associe au jeton d’accès.

Configurer pour un proxy inverse

N’activez trust_proxy que lorsque votre application se trouve derrière un proxy inverse de confiance. Ne l’activez jamais pour des applications exposées directement à Internet.

Si votre application s’exécute derrière un proxy inverse (nginx, AWS ALB, etc.), vous devez activer la confiance envers le proxy pour que la validation DPoP fonctionne correctement :

from fastapi import FastAPI

app = FastAPI()

# Activer la confiance envers le proxy
app.state.trust_proxy = True

auth0 = Auth0FastAPI(
    domain=os.environ.get("AUTH0_DOMAIN"),
    audience=os.environ.get("AUTH0_AUDIENCE")
)

Configurez votre proxy inverse pour transmettre les en-têtes nécessaires :

location /api {
    proxy_pass http://localhost:8000;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Prefix /api;
}

C’est essentiel pour la validation DPoP, car le SDK doit faire correspondre exactement l’URL utilisée par le client. Sans confiance envers le proxy, votre application voit des URL internes, tandis que les preuves DPoP font référence à des URL externes, ce qui entraîne des échecs de validation.

Gestion des erreurs

Le SDK soulève une exception HTTPException en cas d’erreurs d’authentification. FastAPI les gère automatiquement et renvoie au client les réponses HTTP appropriées.

Vous pouvez mettre en place une gestion personnalisée des erreurs au besoin :

from fastapi import Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException

@app.exception_handler(HTTPException)
async def custom_http_exception_handler(request: Request, exc: HTTPException):
    if exc.status_code in [401, 403]:
        return JSONResponse(
            status_code=exc.status_code,
            content={
                "error": "authentication_failed",
                "message": "You must be authenticated to access this resource",
                "details": exc.detail
            }
        )
    return JSONResponse(
        status_code=exc.status_code,
        content={"detail": exc.detail}
    )

Les erreurs d’authentification comprennent :

• 401 Unauthorized : jeton d’accès manquant, invalide ou expiré
• 403 Forbidden : jeton valide, mais permissions insuffisantes (scopes)

---

​

Problèmes courants

401 Unauthorized - Invalid audience

Problème : la validation du jeton échoue avec l’erreur “Invalid audience”.

Solution : vérifiez que AUTH0_AUDIENCE dans votre fichier .env correspond exactement à l’Identifier que vous avez configuré pour votre API dans l’Auth0 Dashboard.

1. Ouvrez l’Auth0 Dashboard et accédez à Applications > APIs
2. Sélectionnez votre API
3. Vérifiez la valeur Identifier dans l’onglet Settings
4. Mettez à jour votre fichier .env :
   AUTH0_AUDIENCE=https://your-exact-api-identifier
   
5. Redémarrez votre application

401 Unauthorized - Invalid issuer

Problème : la validation du jeton échoue avec l’erreur “Invalid issuer”.

Solution : vérifiez que votre AUTH0_DOMAIN est correct et n’inclut pas le protocole https://.

Votre domaine doit ressembler à dev-abc123.us.auth0.com, et non à https://dev-abc123.us.auth0.com.

Mettez à jour votre fichier .env :

AUTH0_DOMAIN=dev-abc123.us.auth0.com

403 Forbidden - Insufficient scope

Problème : le point de terminaison protégé retourne un code 403 même avec un jeton d’accès valide.

Solution : le jeton d’accès n’inclut pas le scope requis.

1. Vérifiez quels scopes votre point de terminaison requiert
2. Lorsque vous demandez un jeton, assurez-vous d’inclure les scopes requis
3. Vérifiez que le scope existe dans l’onglet Permissions de votre API dans l’Auth0 Dashboard
4. Décodez votre jeton sur jwt.io pour vérifier qu’il contient le claim scope avec les valeurs requises

ModuleNotFoundError: No module named 'fastapi_plugin'

Problème : Python ne trouve pas l’Auth0 FastAPI SDK.

Solution : assurez-vous que le SDK est installé dans votre environnement virtuel actif.

# Activez votre environnement virtuel
source venv/bin/activate  # Windows: venv\Scripts\activate

# Installez le SDK
pip install auth0-fastapi-api

# Vérifiez l’installation
pip show auth0-fastapi-api

Impossible de se connecter à Auth0 (échec de récupération des JWKS)

Problème : l’application ne peut pas récupérer les clés de signature depuis Auth0.

Solution : vérifiez votre connectivité réseau et la configuration du domaine.

1. Vérifiez que votre domaine est accessible :

   curl https://YOUR_DOMAIN/.well-known/openid-configuration
   

2. Vérifiez que votre pare-feu autorise les connexions HTTPS sortantes (port 443) vers *.auth0.com

3. Si vous êtes derrière un proxy d’entreprise, configurez les variables d’environnement HTTP_PROXY et HTTPS_PROXY

La validation DPoP échoue

Problème : l’authentification DPoP retourne des erreurs liées à l’URL ou à la validation de la proof.

Solution :

1. Si vous êtes derrière un proxy inverse, activez la confiance du proxy :

   app.state.trust_proxy = True
   

2. Vérifiez que votre proxy transmet ces en-têtes :

   • X-Forwarded-Proto
   • X-Forwarded-Host
   • X-Forwarded-Prefix

3. Assurez-vous que DPoP est activé pour votre tenant (contactez le soutien Auth0)

4. Vérifiez que le claim htu de la DPoP proof correspond exactement à l’URL de votre requête

---

​

Prochaines étapes

Documentation du SDK

Découvrez le SDK Auth0 FastAPI sur GitHub pour des options de configuration avancées et des exemples

Scopes et permissions

Apprenez à définir et à utiliser des scopes pour un contrôle d’accès précis

Auth0 Actions

Personnalisez votre flux d’authentification et ajoutez des claims personnalisés aux jetons

Documentation FastAPI

Découvrez les fonctionnalités de FastAPI, les modèles asynchrones et les pratiques exemplaires

Autorisation d’API

Implémentez le contrôle d’accès basé sur les rôles (RBAC) pour votre API

Déployer en production

Pratiques exemplaires pour déployer des applications FastAPI avec Auth0