auth0-fastapi-api

Auth0 FastAPI API 統合

auth0-fastapi-api を使用して JWT アクセストークンを検証し、FastAPI の API エンドポイントを保護します。

注： この SDK は現在ベータ版です。安定版 1.0 のリリース前に API の仕様が変更される場合があります。最新バージョンは PyPI を確認してください。Python >= 3.9 および FastAPI >= 0.115.11 が必要です。

---

前提条件

• FastAPI アプリケーション（Python 3.9 以降）
• Auth0 API リソースが設定されていること（Application ではなく、API である必要があります）
• Auth0 の設定がまだ済んでいない場合は、まず auth0-quickstart スキルを使用してください

使用しないケース

• サーバーサイドレンダリングの Web アプリケーション — 代わりにセッションベースのログイン／ログアウトフローを使用してください
• シングルページアプリケーション — クライアント側の認証には auth0-react、auth0-vue、または auth0-angular を使用してください
• モバイルアプリケーション — auth0-react-native または auth0-android を使用してください
• トークンの発行 — このスキルはアクセストークンを検証するためのものであり、発行するためのものではありません

---

クイックスタートのワークフロー

1. SDK をインストールする

pip install auth0-fastapi-api python-dotenv

2. Auth0 API を作成する

Auth0 で API（Application ではありません）が必要です。

停止 — 続行する前にユーザーに確認してください。

次の質問をそのまま尋ね、ほかの操作を行う前に回答を待ってください。

「Auth0 API リソースをどのように作成しますか？

1. 自動 — リソースを作成し、正確な値を .env に自動で書き込む Auth0 CLI スクリプトを実行します。
2. 手動 — Auth0 ダッシュボード（または auth0 apis create）で API を作成し、ドメインとオーディエンスを教えてください。

どちらを希望しますか？（1 = 自動／2 = 手動）」

ユーザーが回答するまで、セットアップ手順に進まないでください。手動を既定として選ばないでください。

ユーザーが自動を選択した場合は、完全な CLI スクリプトについてセットアップガイドに従ってください。自動の方法では .env が自動で書き込まれるため、以下のステップ 3 を省略して、ステップ 4 に進んでください。

ユーザーが手動を選択した場合は、詳しい手順についてセットアップガイドの「手動セットアップ」セクションに従ってください。その後、以下のステップ 3 に進んでください。

手動で API を作成する際のクイックリファレンス：

# Using Auth0 CLI
auth0 apis create \
  --name "My FastAPI API" \
  --identifier https://my-api.example.com

または、Auth0 ダッシュボード → Applications → APIs で手動作成します

3. 環境を設定する

.env を作成します：

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

AUTH0_DOMAIN は Auth0 テナントのドメインです（https:// を除く）。AUTH0_AUDIENCE は Auth0 で API リソースを作成する際に設定した API 識別子です。

4. Auth0 を初期化する

import os
from fastapi import FastAPI, Depends
from fastapi_plugin import Auth0FastAPI
from dotenv import load_dotenv

load_dotenv()

app = FastAPI()

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

アプリケーションごとに Auth0FastAPI インスタンスを 1 つ作成し、ルート間で再利用してください。ドメインやオーディエンスをハードコードしないでください。必ず環境変数を使用してください。

5. ルートを保護する

# Require any valid access token
@app.get("/api/private")
async def private(claims: dict = Depends(auth0.require_auth())):
    return {"user": claims["sub"]}

# No authentication required
@app.get("/api/public")
async def public():
    return {"message": "Public endpoint"}

require_auth() 依存関係は Bearer トークンを検証し、発行者とオーディエンスを確認して、デコードされた JWT クレームを返します。

エラーレスポンス：

• 400 invalid_request — Authorization ヘッダーがない、または形式が正しくない
• 401 invalid_token — トークンの期限切れ、署名が無効、発行者またはオーディエンスが不正
• 403 insufficient_scope — トークンは有効だが、必要なスコープが不足している
• 500 internal_server_error — 予期しないエラー

レスポンス本文の形式：{"detail": {"error": "...", "error_description": "..."}}

6. スコープチェックでルートを保護する

# Requires the read:messages scope
@app.get("/api/messages")
async def get_messages(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
    return {"messages": []}

# Requires both read:data and write:data scopes
@app.post("/api/data")
async def write_data(claims: dict = Depends(auth0.require_auth(scopes=["read:data", "write:data"]))):
    return {"created": True}

require_auth(scopes=...) は JWT の scope クレームを確認します。指定されたスコープがすべて含まれている必要があります（AND ロジック）。スコープが不足している場合は 403 を返します。

7. アクセストークンのクレーム

デコードされた JWT クレームは、依存関係から直接返されます：

@app.get("/api/profile")
async def profile(claims: dict = Depends(auth0.require_auth())):
    return {
        "sub": claims["sub"],       # user ID
        "scope": claims.get("scope"),  # granted scopes
    }

主なクレーム：

• claims["sub"] — ユーザー／クライアント ID
• claims["scope"] — 許可されたスコープ（スペース区切り）
• claims["iss"] — 発行者（Auth0 ドメインの URL）
• claims["aud"] — オーディエンス
• claims["exp"] — 有効期限のタイムスタンプ
• claims["iat"] — 発行時のタイムスタンプ

8. クレームを必要とせずにルートを保護する

@app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
async def protected():
    return {"message": "You need a valid access token to see this."}

9. API をテストする

# No token — expect 401
curl http://localhost:8000/api/private

# With a valid access token
curl http://localhost:8000/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Client Credentials フロー、または Auth0 ダッシュボード → APIs → Test タブからテスト用トークンを取得してください。

---

よくある間違い

間違い	修正方法
ソースコード内に domain または audience をハードコードする	必ず環境変数から読み込んでください。認証情報をコードに埋め込まないでください
python-jose または PyJWT を直接使用する	不要です。auth0-fastapi-api が JWKS を通じてすべての検証を処理します
Authorization ヘッダーを手動で解析する	SDK がトークンを自動的に抽出して検証します
jwt.decode() を手動で呼び出す	SDK が JWKS エンドポイントに対してトークンを検証します。自分で検証しないでください
Auth0 JWT の検証に fastapi-users を使用する	このパッケージはユーザー管理用であり、Auth0 JWT の検証用ではありません
Auth0 で API ではなく Application を作成した	API リソース（Applications → APIs）を作成する必要があります。Application は適切な audience を持つアクセストークンを発行しません
domain に https:// 付きの完全な URL を渡す	domain は my-tenant.us.auth0.com のようなドメインのみを指定してください。https://my-tenant.us.auth0.com ではありません
アクセストークンではなく ID トークンを使用する	API 認証にはアクセストークンを使用する必要があります。ID トークンはクライアントアプリ用であり、API の認可には使用しません
SPA クライアント向けの CORS を設定していない	CORSMiddleware を追加し、フロントエンドのオリジンからのリクエストを許可してください
os.getenv() が何も通知せずに None を返す	python-dotenv がインストールされており、Auth0FastAPI() の初期化前に load_dotenv() が呼び出されていることを確認してください。または、早期にエラーを発生させるために os.environ[] を使用してください

---

DPoP のサポート

RFC 9449 に準拠した、組み込みの所有証明トークンバインディングです。DPoP は混合モード（Bearer トークンと DPoP トークンの両方を受け入れます）でデフォルトで有効です。設定については、統合ガイドを参照してください。

---

関連スキル

• auth0-quickstart - Auth0 の基本設定とフレームワークの検出
• auth0-mfa - 多要素認証の追加
• auth0-cli - ターミナルから Auth0 リソースを管理

---

クイックリファレンス

Auth0FastAPI の設定：

auth0 = Auth0FastAPI(
    domain=os.getenv("AUTH0_DOMAIN"),       # required (or use domains)
    audience=os.getenv("AUTH0_AUDIENCE"),    # required
    dpop_enabled=True,                       # default; set False for Bearer-only
    dpop_required=False,                     # default; set True to reject Bearer tokens
)

ルートの保護：

Depends(auth0.require_auth())                    # any valid token
Depends(auth0.require_auth(scopes="read:res"))   # single scope
Depends(auth0.require_auth(scopes=["r", "w"]))   # all scopes required

クレームへのアクセス：

claims["sub"]           # user/client ID
claims["scope"]         # space-separated scopes

環境変数：

• AUTH0_DOMAIN — Auth0 テナントのドメイン（例：tenant.us.auth0.com）
• AUTH0_AUDIENCE — API 識別子（例：https://api.example.com）

一般的なユースケース：

• ルートの保護 → Depends(auth0.require_auth())（ステップ 5 を参照）
• スコープの適用 → Depends(auth0.require_auth(scopes="..."))（ステップ 6 を参照）
• DPoP トークンバインディング → 統合ガイド
• リバースプロキシの設定 → 統合ガイド
• 高度な設定 → API リファレンス

---

詳細ドキュメント

• セットアップガイド — Auth0 CLI の設定、環境設定、テストトークンの取得
• 統合ガイド — DPoP、スコープ、エラー処理、リバースプロキシ、テスト
• API リファレンス — コンストラクターの全オプション、メソッドシグネチャ、エラーコード

---

参考資料

• auth0-fastapi-api GitHub
• PyPI の auth0-fastapi-api
• Auth0 FastAPI API クイックスタート
• FastAPI の依存性注入
• アクセストークンガイド