API Flask

Ce guide montre comment intégrer Auth0 à n’importe quelle API Python, nouvelle ou existante, créée avec Flask.

Prérequis : Avant de commencer, assurez-vous d’avoir les éléments suivants installés :

• Python 3.9 ou une version ultérieure
• pip ou le gestionnaire de paquets Poetry
• jq - Requis pour la configuration d’Auth0 CLI
• Votre éditeur de code préféré

Compatibilité des versions de Flask : Ce Quickstart nécessite Flask 3.0 ou une version ultérieure pour la prise en charge native de l’asynchrone.

​

Pour commencer

Ce guide explique comment intégrer Auth0 à n’importe quelle API Python, nouvelle ou existante, créée avec Flask.

1. Créer un nouveau projet Flask

   Créez un nouveau dossier pour votre API Flask :

   mkdir flask-auth0-api
   cd flask-auth0-api
   

   Créez un environnement virtuel et activez-le :

   python -m venv venv
   source venv/bin/activate  # Sur Windows : venv\Scripts\activate
   
2. Installer les dépendances

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

   requirements.txt

   flask>=3.0
   auth0-api-python
   python-dotenv
   

   Installez les dépendances :

   pip install -r requirements.txt
   
3. Configuration de votre API Auth0

   Ensuite, vous devez créer une nouvelle API dans votre tenant Auth0 et configurer votre application.

   Vous pouvez le faire automatiquement en exécutant une commande CLI, ou manuellement dans le Dashboard :

   Dashboard

   1. Accédez au Auth0 Dashboard → Applications → APIs
   2. Cliquez sur Créer une API
   3. Saisissez les détails de votre API :
      • Nom : My Flask API
      • Identifiant : https://my-flask-api (ce sera votre audience)
      • Algorithme de signature : RS256
   4. Cliquez sur Créer
   5. Copiez votre Domain à partir du Dashboard (sous Applications → Applications → [Votre application] → Settings)
   6. Copiez l’Identifiant que vous venez de créer (il s’agit de votre audience)

   Votre Domain ne doit pas inclure https:// — utilisez seulement le nom de domaine (p. ex. your-tenant.auth0.com).

   L’Audience (identifiant d’API) est un identifiant unique pour votre API et peut être n’importe quel URI valide.

   CLI

   Exécutez la commande shell suivante à la racine de votre projet pour créer une API Auth0 et générer un fichier .env :

   Mac

   AUTH0_API_NAME="My Flask API" && AUTH0_API_IDENTIFIER="https://my-flask-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 --json > auth0-api-details.json && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && AUDIENCE=$(jq -r '.identifier' auth0-api-details.json) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_AUDIENCE=${AUDIENCE}" >> .env && rm auth0-api-details.json && echo ".env file created with your Auth0 API details:" && cat .env
   
4. Définir les permissions d’API

   Configurez les permissions (scopes) de votre API pour contrôler l’accès à des ressources précises :

   1. Dans le Auth0 Dashboard, accédez à Applications → APIs
   2. Sélectionnez votre API (My Flask API)
   3. Accédez à l’onglet Permissions
   4. Cliquez sur Add Permission
   5. Ajoutez la permission suivante :
      • Permission (Scope) : read:messages
      • Description : Read messages
   6. Cliquez sur Add

   Les permissions définissent les actions qui peuvent être effectuées sur votre API. Vous pouvez ajouter plusieurs permissions, comme write:messages, delete:messages, etc. Le point de terminaison /api/private-scoped de ce Quickstart nécessite la permission read:messages.

5. Configurer le client Auth0

   Si vous avez utilisé la méthode CLI à l’étape 3, votre fichier .env a été créé automatiquement. Passez directement à la création du fichier app.py ci-dessous.

   Si vous avez utilisé la méthode Dashboard, créez un fichier .env à la racine de votre projet pour y stocker votre configuration d’Auth0 :

   .env

   AUTH0_DOMAIN=your-tenant.us.auth0.com
   AUTH0_AUDIENCE=https://my-flask-api
   

   Remplacez your-tenant.us.auth0.com par votre domaine Auth0 réel et mettez à jour API_IDENTIFIER pour qu’il corresponde à l’identifiant de votre API dans le dashboard.

   Créez un fichier app.py et configurez le client API Auth0 :

   app.py

   import os
   import asyncio
   from flask import Flask, request, jsonify, g
   from functools import wraps
   from dotenv import load_dotenv
   from auth0_api_python import ApiClient, ApiClientOptions
   from auth0_api_python.errors import BaseAuthError
   
   # Charger les variables d'environnement
   load_dotenv()
   
   app = Flask(__name__)
   
   # Initialiser le client API Auth0 (singleton - créé une seule fois)
   api_client = ApiClient(ApiClientOptions(
       domain=os.getenv("AUTH0_DOMAIN"),
       audience=os.getenv("AUTH0_AUDIENCE")
   ))
   
6. Créer des routes protégées

   Ajoutez un décorateur pour protéger les routes et créez des endpoints publics et privés :

   app.py

   # Décorateur d'authentification
   def require_auth(f):
       @wraps(f)
       def decorated_function(*args, **kwargs):
           auth_header = request.headers.get("Authorization", "")
           
           if not auth_header.startswith("Bearer "):
               return jsonify({"error": "Missing or invalid authorization header"}), 401
           
           token = auth_header.split(" ")[1]
           
           try:
               claims = asyncio.run(api_client.verify_access_token(token))
               g.user_claims = claims
               return f(*args, **kwargs)
           except BaseAuthError as e:
               return (
                   jsonify({"error": str(e)}),
                   e.get_status_code(),
                   e.get_headers()
               )
       
       return decorated_function
   
   
   # Endpoint public - aucune authentification requise
   @app.route("/api/public", methods=["GET"])
   def public():
       return jsonify({"message": "This endpoint is public"})
   
   
   # Endpoint protégé - authentification requise
   @app.route("/api/private", methods=["GET"])
   @require_auth
   def private():
       return jsonify({
           "message": "This endpoint requires authentication",
           "user": g.user_claims.get("sub")
       })
   
   
   # Endpoint protégé avec validation des permissions
   @app.route("/api/private-scoped", methods=["GET"])
   @require_auth
   def private_scoped():
       scopes = g.user_claims.get("scope", "").split()
       
       if "read:messages" not in scopes:
           return jsonify({"error": "Insufficient permissions"}), 403
       
       return jsonify({
           "message": "Private scoped endpoint - read:messages permission granted",
           "user": g.user_claims.get("sub")
       })
   
   
   if __name__ == "__main__":
       app.run(debug=True, port=5000)
   
7. Lancez votre API

   Démarrez votre application Flask :

   python app.py
   

   Votre API fonctionne maintenant à l’adresse http://localhost:5000.

Vérification

Vous devriez maintenant avoir une API Flask protégée par Auth0 entièrement fonctionnelle qui s’exécute sur votre hôte local, avec trois points de terminaison :

• /api/public - Accessible sans authentification
• /api/private - Nécessite un jeton d’accès Auth0 valide
• /api/private-scoped - Nécessite une authentification et la permission read:messages

​

Testez votre API

Pour tester vos points de terminaison protégés, vous avez besoin d’un jeton d’accès.

​

Obtenir un jeton de test

1. Accédez au Auth0 Dashboard
2. Accédez à Applications → APIs
3. Sélectionnez votre API
4. Accédez à l’onglet Test
5. Copiez le jeton d’accès

​

Effectuer une requête

Testez le point de terminaison public (aucun jeton requis) :

curl http://localhost:5000/api/public

Testez l’endpoint protégé (jeton requis) :

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://localhost:5000/api/private

Remplacez YOUR_ACCESS_TOKEN par le jeton que vous avez copié depuis l’Auth0 Dashboard.

​

Utilisation avancée

Validation des claims personnalisés

Exigez la présence de claims précis dans le jeton d’accès :

try:
    claims = await api_client.verify_access_token(
        access_token=token,
        required_claims=["email_verified", "org_id"]
    )
except BaseAuthError as e:
    return jsonify({"error": "Missing required claims"}), 401

Authentification DPoP

Pour une sécurité accrue, activez DPoP (Demonstrating Proof-of-Possession). DPoP renforce OAuth 2.0 en liant les jetons d’accès à des clés cryptographiques.

import asyncio


# Configurer le client API avec DPoP activé (mode Allowed)
api_client = ApiClient(ApiClientOptions(
    domain=os.getenv("AUTH0_DOMAIN"),
    audience=os.getenv("AUTH0_AUDIENCE"),
    dpop_enabled=True,   # Par défaut - active la prise en charge de DPoP
    dpop_required=False  # Par défaut - autorise les jetons Bearer et DPoP
))

# Pour le mode Required (DPoP uniquement, rejette les jetons Bearer)
# dpop_required=True

# Décorateur compatible avec DPoP
def require_auth_dpop(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        headers = {
            "authorization": request.headers.get("Authorization", ""),
            "dpop": request.headers.get("DPoP", "")  # en-tête de preuve DPoP
        }
        
        try:
            # verify_request() détecte automatiquement l’utilisation de Bearer ou de DPoP
            claims = asyncio.run(api_client.verify_request(
                headers=headers,
                http_method=request.method,
                http_url=request.url
            ))
            g.user_claims = claims
            return f(*args, **kwargs)
        except BaseAuthError as e:
            return jsonify({"error": str(e)}), e.get_status_code(), e.get_headers()
    
    return decorated_function

@app.route("/api/dpop-protected")
@require_auth_dpop
def dpop_protected():
    return jsonify({
        "message": "Successfully authenticated with DPoP or Bearer",
        "user": g.user_claims.get("sub")
    })

La méthode verify_request() détecte automatiquement si la requête utilise l’authentification Bearer ou DPoP. Lorsque DPoP est utilisé, elle valide à la fois le jeton d’accès et la preuve DPoP conformément à la RFC 9449.

Autorisation basée sur les scopes

Créez un décorateur pour vérifier des scopes précis :

def require_scope(required_scope):
    def decorator(f):
        @wraps(f)
        async def wrapper(*args, **kwargs):
            if not hasattr(g, "user_claims"):
                return jsonify({"error": "Unauthorized"}), 401
            
            scopes = g.user_claims.get("scope", "").split()
            
            if required_scope not in scopes:
                return jsonify({"error": "Insufficient permissions"}), 403
            
            return await f(*args, **kwargs)
        return wrapper
    return decorator


@app.route("/api/admin")
@require_auth
@require_scope("admin:write")
async def admin_endpoint():
    return jsonify({"message": "Admin access granted"})

Pratiques exemplaires de gestion des erreurs

Mettez en place une gestion complète des erreurs avec des types d’erreur précis :

from auth0_api_python.errors import (
    BaseAuthError,
    VerifyAccessTokenError,
    GetTokenByExchangeProfileError,
    ApiError
)

@app.errorhandler(BaseAuthError)
def handle_auth_error(error):
    """Gérer toutes les erreurs d’authentification Auth0"""
    return jsonify({
        "error": error.get_error_code(),
        "error_description": str(error)
    }), error.get_status_code(), error.get_headers()


@app.errorhandler(VerifyAccessTokenError)
def handle_token_verification_error(error):
    """Gérer spécifiquement les échecs de vérification de jeton"""
    app.logger.warning(f"Token verification failed: {str(error)}")
    return jsonify({
        "error": "invalid_token",
        "error_description": str(error)
    }), 401, error.get_headers()


@app.errorhandler(ApiError)
def handle_api_error(error):
    """Gérer les erreurs de l’Auth0 API (réseau, limites de débit, etc.)"""
    app.logger.error(f"Auth0 API error: {error.code} - {error.message}")
    return jsonify({
        "error": error.code,
        "error_description": error.message
    }), error.status_code or 500


@app.errorhandler(Exception)
def handle_generic_error(error):
    """Capturer toutes les erreurs inattendues"""
    app.logger.error(f"Unexpected error: {str(error)}", exc_info=True)
    return jsonify({"error": "Internal server error"}), 500

Toutes les erreurs d’authentification dérivent de BaseAuthError, qui fournit des méthodes comme get_status_code(), get_headers() et get_error_code() pour générer des réponses HTTP appropriées avec des en-têtes WWW-Authenticate.

Utilisation du middleware before_request

Pour les applications où la plupart des points de terminaison exigent une authentification, utilisez before_request de Flask pour valider les jetons de façon globale :

from flask import g

PUBLIC_ROUTES = ["/api/public", "/health"]

@app.before_request
async def verify_token():
    # Ignorer l’authentification pour les routes publiques
    if request.path in PUBLIC_ROUTES:
        return
    
    auth_header = request.headers.get("Authorization", "")
    
    if not auth_header.startswith("Bearer "):
        return jsonify({"error": "Missing authorization"}), 401
    
    token = auth_header.split(" ")[1]
    
    try:
        claims = await api_client.verify_access_token(token)
        g.user_claims = claims
    except BaseAuthError as e:
        return jsonify({"error": str(e)}), e.get_status_code(), e.get_headers()


@app.route("/api/protected-data")
async def protected_data():
    # Les claims sont automatiquement accessibles dans g.user_claims
    return jsonify({"user_id": g.user_claims["sub"]})

​

Problèmes courants

401 Non autorisé - audience invalide

Symptôme : Vous obtenez des erreurs 401 même avec des jetons qui semblent valides

Cause : L’audience de votre jeton ne correspond pas à celle configurée dans votre client API

Solution :

1. Vérifiez que AUTH0_AUDIENCE dans votre fichier .env correspond exactement à votre identifiant d’API Auth0
2. L’audience respecte la casse
3. Assurez-vous que l’audience est au format URL ou URN (p. ex., https://my-api et non my-api)

401 Non autorisé - issuer invalide

Symptôme : La validation du jeton échoue en raison d’une non-correspondance de l’issuer

Cause : La configuration du domaine ne correspond pas à l’issuer du jeton

Solution :

1. Vérifiez que AUTH0_DOMAIN est correct (p. ex., tenant.us.auth0.com)
2. N’incluez pas https:// dans le domaine
3. N’ajoutez pas de barre oblique à la fin

Valeurs de configuration introuvables

Symptôme : Valeurs None ou erreurs liées aux variables d’environnement

Cause : Variables d’environnement non chargées ou fichier .env introuvable

Solution :

1. Assurez-vous que le fichier .env existe à la racine de votre projet
2. Vérifiez que load_dotenv() est appelé avant d’accéder à os.getenv()
3. Vérifiez que les noms de variables correspondent exactement (respect de la casse)

Erreurs de prise en charge asynchrone dans Flask

Symptôme : RuntimeError: This event loop is already running ou erreurs async semblables

Cause : Utilisation de routes async sans Flask 3.0+ ou mélange incorrect de sync et d’async

Solution :

1. Mettez à niveau vers Flask 3.0 ou une version ultérieure : pip install --upgrade flask
2. Assurez-vous que tous les gestionnaires de route qui utilisent api_client sont déclarés avec async def
3. N’utilisez pas asyncio.run() dans les gestionnaires de route

Erreurs de jeton expiré

Symptôme : VerifyAccessTokenError: Token is expired

Cause : Le jeton d’accès a dépassé sa date d’expiration

Solution :

1. Demandez un nouveau jeton à partir de l’onglet Test de l’Auth0 Dashboard
2. Implémentez l’actualisation du jeton dans votre application cliente
3. Les jetons du Dashboard sont généralement valides pendant 24 heures

En-tête Authorization manquant

Symptôme : Erreur Missing or invalid authorization header

Cause : La requête n’inclut pas l’en-tête Authorization ou utilise un format incorrect

Solution :

1. Assurez-vous que l’en-tête s’appelle Authorization (A majuscule)
2. Utilisez le format : Authorization: Bearer YOUR_TOKEN
3. N’incluez pas de guillemets autour du jeton

​

Ressources supplémentaires

Documentation du SDK

Documentation complète du SDK et référence de l’API

Documentation Flask

Documentation officielle du framework Flask

Auth0 Dashboard

Gérez votre tenant Auth0 et vos API

Guide d’authentification des API

En savoir plus sur les jetons d’accès et la sécurité des API

DPoP Documentation

En savoir plus sur la sécurité par preuve de possession

Forum de la communauté

Obtenez de l’aide auprès de la communauté Auth0

​

Étapes suivantes

Consultez le dépôt d’exemples de l’API Python d’Auth0 pour voir des exemples complets et fonctionnels avec Flask.