Flask API

このガイドでは、Flask を使用して構築した新規または既存の Python API に Auth0 を統合する方法を説明します。

前提条件: 開始する前に、以下がインストールされていることを確認してください。

• Python 3.9 以降
• pip または Poetry パッケージマネージャー
• jq - Auth0 CLI のセットアップに必要
• 任意のコードエディター

Flask のバージョン互換性: このクイックスタートでは、ネイティブの async サポートを利用するために Flask 3.0 以降が必要です。

​

はじめに

このガイドでは、Flask で構築した新規または既存の Python API に Auth0 を統合する方法を説明します。

1. 新しい Flask プロジェクトを作成する

   Flask API 用の新しいディレクトリを作成します。

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

   仮想環境を作成して、有効化します。

   python -m venv venv
   source venv/bin/activate  # Windowsの場合: venv\Scripts\activate
   
2. 依存関係をインストール

   次の依存関係を含む requirements.txt ファイルを作成します。

   requirements.txt

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

   依存関係をインストールします:

   pip install -r requirements.txt
   
3. Auth0 API をセットアップする

   次に、Auth0 テナントで新しい API を作成し、アプリケーションを設定する必要があります。

   これには、CLI コマンドを実行して自動的に行う方法と、Dashboard から手動で行う方法があります。

   ダッシュボード

   1. Auth0 Dashboard → Applications → APIs に移動します
   2. Create API をクリックします
   3. API の詳細を入力します。
      • Name: My Flask API
      • Identifier: https://my-flask-api (これがオーディエンスになります)
      • Signing Algorithm: RS256
   4. Create をクリックします
   5. Auth0 Dashboard から ドメイン をコピーします (場所: Applications → Applications → [Your App] → Settings)
   6. 作成した Identifier をコピーします (これがオーディエンスです)

   ドメイン には https:// を含めないでください。ドメイン名のみを使用します (例: your-tenant.auth0.com) 。

   対象者 (API Identifier) は API の一意の識別子であり、有効な URI であれば任意の値を指定できます。

   CLI

   Auth0 API を作成して .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
   

   $ApiName = "My Flask API"; $ApiIdentifier = "https://my-flask-api"; winget install Auth0.CLI; auth0 login --no-input; auth0 apis create -n "$ApiName" -i "$ApiIdentifier" --signing-alg RS256 --json | Set-Content -Path auth0-api-details.json; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Audience = (Get-Content -Raw auth0-api-details.json | ConvertFrom-Json).identifier; Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_AUDIENCE=$Audience"; Remove-Item auth0-api-details.json; Write-Output ".env file created with your Auth0 API details:"; Get-Content .env
   
4. API の権限を定義する

   特定のリソースへのアクセスを制御するため、API の権限 (スコープ) を設定します。

   1. Auth0 Dashboard で、Applications → APIs に移動します
   2. API (My Flask API) を選択します
   3. Permissions タブを開きます
   4. Add Permission をクリックします
   5. 次の権限を追加します。
      • Permission (Scope): read:messages
      • Description: Read messages
   6. Add をクリックします

   権限は、その API に対して実行できる操作を定義します。write:messages、delete:messages など、複数の権限を追加できます。このクイックスタートの /api/private-scoped エンドポイントには、read:messages 権限が必要です。

5. Auth0 のクライアントを設定する

   手順 3 で CLI の方法を使用した場合、.env ファイルは自動的に作成されています。以下の app.py ファイルの作成に進んでください。

   Dashboard の方法を使用した場合は、Auth0 の設定を保存するため、プロジェクトのルートに .env ファイルを作成します。

   .env

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

   your-tenant.us.auth0.com は実際の Auth0 ドメインに置き換え、API_IDENTIFIER はダッシュボード上の API 識別子に合わせて更新してください。

   app.py ファイルを作成し、Auth0 API クライアントを設定します。

   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
   
   # 環境変数を読み込む
   load_dotenv()
   
   app = Flask(__name__)
   
   # Auth0 APIクライアントを初期化する（シングルトン - 一度だけ作成）
   api_client = ApiClient(ApiClientOptions(
       domain=os.getenv("AUTH0_DOMAIN"),
       audience=os.getenv("AUTH0_AUDIENCE")
   ))
   
6. 保護されたルートを作成する

   ルートを保護するデコレーターを追加し、パブリックエンドポイントとプライベートエンドポイントを作成します。

   app.py

   # 認証デコレーター
   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
   
   
   # パブリックエンドポイント - 認証不要
   @app.route("/api/public", methods=["GET"])
   def public():
       return jsonify({"message": "This endpoint is public"})
   
   
   # 保護されたエンドポイント - 認証が必要
   @app.route("/api/private", methods=["GET"])
   @require_auth
   def private():
       return jsonify({
           "message": "This endpoint requires authentication",
           "user": g.user_claims.get("sub")
       })
   
   
   # 権限検証付きの保護されたエンドポイント
   @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. API を起動する

   Flask アプリケーションを起動します。

   python app.py
   

   API は http://localhost:5000 で起動しています。

チェックポイント

これで、Auth0 で保護された完全に機能する Flask API が localhost 上で動作しており、次の 3 つのエンドポイントを利用できるはずです。

• /api/public - 認証なしでアクセス可能
• /api/private - 有効な Auth0 アクセストークンが必要
• /api/private-scoped - 認証と read:messages 権限が必要

​

APIをテストする

保護されたエンドポイントをテストするには、アクセストークンが必要です。

​

テスト用トークンを取得する

1. Auth0 Dashboard を開きます
2. Applications → APIs に移動します
3. 対象の API を選択します
4. Test タブを開きます
5. アクセストークンをコピーします

​

リクエストを送信する

公開エンドポイントをテストします (トークンは不要です) ：

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

保護されたエンドポイントをテストします (トークンが必要) :

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

YOUR_ACCESS_TOKEN を、Auth0 Dashboard からコピーしたトークンに置き換えます。

​

高度な使い方

カスタムクレームの検証

アクセストークンに特定のクレームが含まれていることを必須にします。

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

DPoP 認証

セキュリティをさらに強化するには、DPoP (Demonstrating Proof-of-Possession) を有効にします。DPoP は、アクセストークンを暗号鍵に結び付けることで OAuth 2.0 を強化します。

import asyncio


# DPoP を有効にして API クライアントを設定（Allowed モード）
api_client = ApiClient(ApiClientOptions(
    domain=os.getenv("AUTH0_DOMAIN"),
    audience=os.getenv("AUTH0_AUDIENCE"),
    dpop_enabled=True,   # デフォルト - DPoP サポートを有効化
    dpop_required=False  # デフォルト - Bearer と DPoP の両方のトークンを許可
))

# Required モードの場合（DPoP のみ、Bearer トークンは拒否）
# dpop_required=True

# DPoP 対応のデコレーター
def require_auth_dpop(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        headers = {
            "authorization": request.headers.get("Authorization", ""),
            "dpop": request.headers.get("DPoP", "")  # DPoP 証明ヘッダー
        }
        
        try:
            # verify_request() は Bearer または 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")
    })

verify_request() メソッドは、リクエストで Bearer 認証と DPoP 認証のどちらが使われているかを自動的に判別します。DPoP が使用されている場合は、RFC 9449 に従ってアクセストークンと DPoP 証明の両方を検証します。

スコープベースの認可

特定のスコープを確認するデコレーターを作成します。

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"})

エラー処理のベストプラクティス

特定のエラー型を使って、包括的なエラー処理を実装します。

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

@app.errorhandler(BaseAuthError)
def handle_auth_error(error):
    """Handle all Auth0 authentication errors"""
    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):
    """Handle token verification failures specifically"""
    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):
    """Handle Auth0 API errors (network, rate limits, 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):
    """Catch-all for unexpected errors"""
    app.logger.error(f"Unexpected error: {str(error)}", exc_info=True)
    return jsonify({"error": "Internal server error"}), 500

すべての認証エラーは BaseAuthError を継承しており、BaseAuthError は get_status_code()、get_headers()、get_error_code() などのメソッドを提供します。これにより、WWW-Authenticate ヘッダーを含む適切な HTTP レスポンスを返せます。

Before-Request ミドルウェアの使用

ほとんどのエンドポイントで認証が必要なアプリケーションでは、Flask の before_request を使用してトークンをグローバルに検証します。

from flask import g

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

@app.before_request
async def verify_token():
    # 公開ルートでは認証をスキップ
    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():
    # クレームは g.user_claims から自動的に利用可能
    return jsonify({"user_id": g.user_claims["sub"]})

​

よくある問題

401 Unauthorized - 無効なオーディエンス

症状: 有効に見えるトークンでも 401 エラーが発生する

原因: トークン内のオーディエンスが、API クライアントに設定されたオーディエンスと一致していない

解決策:

1. .env ファイル内の AUTH0_AUDIENCE が Auth0 API Identifier と完全に一致していることを確認します
2. オーディエンスでは大文字と小文字が区別されます
3. オーディエンスが URL または URN 形式であることを確認します (例: my-api ではなく https://my-api)

401 Unauthorized - 無効な issuer

症状: issuer の不一致により、トークンの検証に失敗する

原因: ドメイン設定がトークンの issuer と一致していない

解決策:

1. AUTH0_DOMAIN が正しいことを確認します (例: tenant.us.auth0.com)
2. ドメインに https:// を含めないでください
3. 末尾のスラッシュを含めないでください

設定値が見つからない

症状: None の値や環境変数に関するエラーが発生する

原因: 環境変数が読み込まれていないか、.env ファイルが見つからない

解決策:

1. プロジェクトのルートに .env ファイルが存在することを確認します
2. os.getenv() を呼び出す前に load_dotenv() が実行されていることを確認します
3. 変数名が完全に一致していることを確認します (大文字と小文字は区別されます)

Flask の非同期サポートエラー

症状: RuntimeError: This event loop is already running または同様の非同期エラーが発生する

原因: Flask 3.0+ を使用せずに非同期ルートを使っているか、同期処理と非同期処理を誤って混在させている

解決策:

1. Flask 3.0 以降にアップグレードします: pip install --upgrade flask
2. api_client を使用するすべてのルートハンドラーが async def として宣言されていることを確認します
3. ルートハンドラー内で asyncio.run() を使用しないでください

トークンの有効期限切れエラー

症状: VerifyAccessTokenError: Token is expired

原因: アクセストークンの有効期限が切れている

解決策:

1. Auth0 Dashboard の Test タブから新しいトークンをリクエストします
2. クライアントアプリケーションにトークンの更新処理を実装します
3. Dashboard のトークンは通常 24 時間有効です

Authorization ヘッダーがない

症状: Missing or invalid authorization header エラー

原因: リクエストに Authorization ヘッダーが含まれていないか、形式が正しくない

解決策:

1. ヘッダー名が Authorization (A は大文字) であることを確認します
2. 次の形式を使用します: Authorization: Bearer YOUR_TOKEN
3. トークンを引用符で囲まないでください

​

追加リソース

SDK ドキュメント

SDK の完全なドキュメントと API リファレンス

Flask ドキュメント

Flask フレームワークの公式ドキュメント

Auth0 Dashboard

Auth0 のテナントと API を管理

API 認証ガイド

アクセストークンと API セキュリティについて確認

DPoP ドキュメント

proof-of-possession セキュリティについて確認

コミュニティフォーラム

Auth0 コミュニティからサポートを受ける

​

次のステップ

Flask を使用した完全に動作するサンプルについては、Auth0 Python API samples repositoryを参照してください。