FastAPIでセッションを使う：これを見ればOK！

By /

FastAPIでセッションを使う：これを見ればOK！ 完全ガイド

はじめに

FastAPIは、PythonでAPIを構築するためのモダンで高速（高性能）なWebフレームワークです。その特徴は、非同期処理への対応、自動ドキュメント生成（OpenAPI/Swagger UI）、Pythonの型ヒントを活用した強力なバリデーション機能などにあります。非常に人気があり、多くの開発現場で採用が進んでいます。

しかし、FastAPIはそのAPI構築に特化した設計思想から、伝統的なWebフレームワークが持つような組み込みのセッション管理機能は提供していません。APIは基本的にステートレス（状態を持たない）な通信を前提としているためです。それでも、Webアプリケーション、特にブラウザからの利用を想定したアプリケーションにおいては、ユーザーの状態を維持するためのセッション機能は不可欠な要素となります。例えば、ログインしているユーザーを識別したり、ショッピングカートの内容を一時的に保存したり、ユーザーの言語設定を記憶したりする場合にセッションが利用されます。

HTTPプロトコル自体はステートレスです。つまり、サーバーはリクエストごとに独立した通信として扱います。過去のリクエストや、同じユーザーからの別のリクエストについて、サーバーはデフォルトでは何も知りません。このステートレス性を補い、連続するリクエストを特定のユーザーと結びつけるための仕組みがセッションです。

セッション管理は、通常、以下の要素を組み合わせて実現されます。
1. セッションIDの生成: サーバーがユーザーに対して一意な識別子（セッションID）を発行します。
2. セッションIDの交換: サーバーはセッションIDをクライアント（通常はブラウザ）に送信します。最も一般的な方法は、HTTPレスポンスヘッダーのSet-Cookieを使って、クライアントのブラウザにセッションIDを含むクッキーとして保存させることです。
3. セッションIDの送信: クライアントは、以降のリクエストごとに、保存したセッションIDを含むクッキーをHTTPリクエストヘッダーのCookieとしてサーバーに送信します。
4. セッションデータの保存: サーバーはクライアントから送信されたセッションIDをキーとして、ユーザー固有のデータ（ログイン情報、設定など）をサーバー側のストレージ（メモリ、ファイル、データベース、KVSなど）に保存します。または、セッションID自体にデータを暗号化して含めることもあります（クッキーベースセッション）。
5. セッションデータの利用: サーバーはクライアントから送られてきたセッションIDを使って、保存されているセッションデータを読み出し、リクエスト処理に利用します。

FastAPIでこのようなセッション管理を実装するには、サードパーティ製のライブラリや、基盤となっているStarletteフレームワークの機能を利用するのが一般的です。この記事では、FastAPIでセッションを使うための基本的な考え方から、具体的なライブラリの利用方法、そしてセキュリティに関する考慮事項まで、網羅的に解説します。

この記事を読むことで、あなたは以下のことを習得できます。
* FastAPIでセッションが必要な理由と、その基本的な仕組み
* FastAPIでセッションを実装するための主要なアプローチ
* StarletteのSessionMiddlewareを使ったクッキーベースセッションの実装方法
* セッションデータの保存、読み出し、削除の方法
* セッション設定に関する様々なオプションと、その意味
* セッション管理におけるセキュリティ上の注意点
* より高度なセッション管理（サーバーストレージ）の可能性

さあ、FastAPIでセッションを自在に操るための知識を身につけましょう。

FastAPIにおけるセッション管理の基礎

前述の通り、FastAPI自体はセッション機能を持っていません。これは、FastAPIがAPI構築、特にステートレスなRESTful APIやマイクロサービスを意識して設計されているためです。しかし、FastAPIを使って伝統的なWebアプリケーション（HTMLテンプレートを返したり、ブラウザベースのユーザーインターフェースを持つアプリケーション）を構築する場合、セッションは不可欠な要素となります。

FastAPIでセッション管理を実現するための主なアプローチは以下の2つです。

  1. クッキーベースセッション:

    • セッションデータ全体、またはセッションIDから派生する情報を、クライアントのブラウザに保存されるクッキーに格納します。
    • セッションデータ自体をクッキーに保存する場合、データは通常、署名（signature）や暗号化が施されます。署名によりデータの改ざんを検知でき、暗号化によりデータの盗聴を防ぎます。
    • 利点: サーバー側に特別なストレージ（データベースやKVS）が不要なため、実装がシンプルでスケールしやすい（サーバーの負荷が少ない）。
    • 欠点: クッキーの容量制限があるため、大量のデータを保存できない。機密性の高いデータを保存する際は、強力な暗号化が必要。すべてのリクエスト/レスポンスでクッキーデータがやり取りされるため、通信量がわずかに増加する。セキュリティ上のリスク（クッキーの盗難など）に注意が必要。
    • FastAPI/Starletteにおいては、starlette.middleware.sessions.SessionMiddleware がこの方式を提供します。

  2. サーバーストレージベースセッション:

    • クライアントのブラウザにはセッションIDのみをクッキーとして保存します。
    • 実際のセッションデータは、サーバー側のストレージ（メモリ、ファイル、リレーショナルデータベース、NoSQLデータベース、インメモリデータストア（Redis, Memcachedなど））に保存します。
    • サーバーはクライアントから送られてきたセッションIDをキーとして、ストレージからセッションデータを取得します。
    • 利点: 大量のデータを保存できる。機密性の高いデータはサーバー側に保持されるため、クッキーベースに比べてセキュリティリスクが低い。
    • 欠点: サーバー側にストレージが必要になる。複数のサーバーインスタンスでアプリケーションを運用する場合（スケールアウト時）、セッションストレージを共有する必要がある。ストレージへのアクセスがパフォーマンスボトルネックになる可能性がある。
    • FastAPI/Starlette向けのサードパーティライブラリ（例: starlette-sessionsなど）を利用するか、自前で実装する必要があります。

どちらのアプローチを選択するかは、アプリケーションの要件、データの機密性、予想されるトラフィック量、インフラ構成などによって異なります。

多くの一般的なWebアプリケーションのセッション管理においては、ログイン状態の維持やちょっとした設定情報の保存など、比較的少量で機密性の高すぎないデータを扱うことが多いです。このような場合、実装の手軽さからクッキーベースのセッションが選ばれることがよくあります。特に、Starletteに標準で含まれるSessionMiddlewareは、FastAPIと非常にスムーズに連携するため、手軽にセッション機能を導入したい場合に最適な選択肢となります。

この記事では、まず最も手軽で広く利用されているstarlette.middleware.sessions.SessionMiddlewareを使ったクッキーベースセッションの実装方法について、詳細に解説します。その後、より堅牢なサーバーストレージベースのセッションについても触れる予定です。

セッションライブラリの選定

FastAPIでセッションを実装するために利用できるライブラリはいくつか存在します。

  • starlette.middleware.sessions.SessionMiddleware:

    • FastAPIの基盤となっているStarletteフレームワークに標準で含まれるミドルウェアです。
    • クッキーベースのセッションを提供します。セッションデータは署名付きクッキーとしてクライアントに保存されます。
    • シンプルで導入が容易です。FastAPIアプリケーションにミドルウェアとして追加するだけで利用できます。
    • この記事のメインで解説するライブラリです。

  • starlette-sessions:

    • Starlette/FastAPI向けのセッション管理ライブラリです。
    • 様々なバックエンドストレージ（メモリ、ファイル、Redis、MongoDB、SQLAlchemyなど）に対応しています。
    • クッキーベースだけでなく、サーバーストレージベースのセッション管理も実現できます。
    • より高度な要件や、大規模なアプリケーション、分散システムなどでセッションを管理したい場合に検討する価値があります。

  • その他:

    • 上記以外にも、PyramidやFlaskといった他のPython Webフレームワーク向けのセッションライブラリを、FastAPI/Starletteのミドルウェアとしてラップして利用することも技術的には可能ですが、互換性やメンテナンスの面でstarlette系のライブラリが推奨されます。

この記事では、手軽さ、Starlette/FastAPIとの親和性の高さ、そして一般的なWebアプリケーションでの利用頻度を考慮し、starlette.middleware.sessions.SessionMiddlewareに焦点を当てて解説を進めます。このミドルウェアの使い方を習得すれば、FastAPIアプリケーションに基本的なセッション機能を導入できるようになります。

SessionMiddlewareを利用するために必要な特別な依存関係は、Starlette自体です。FastAPIはStarlette上に構築されているため、通常FastAPIをインストールすればStarletteも一緒にインストールされます。明示的にインストールする場合は以下のコマンドを使用します。

bash
pip install starlette

また、SessionMiddlewareはクッキーにセッションデータを格納する際に、内部でデータ構造をシリアライズ/デシリアライズするためにjsonライブラリ（Python標準ライブラリ）を使用します。さらに、クッキーの署名/検証のためにitsdangerousライブラリを使用します。これらも通常、FastAPIやStarletteの依存関係として自動的にインストールされますが、もしインストールされていない場合は以下のコマンドでインストールできます。

bash
pip install itsdangerous

これで、SessionMiddlewareを利用するための準備は完了です。

starlette.middleware.sessions.SessionMiddleware を使ったセッション実装

それでは、実際にSessionMiddlewareを使ってFastAPIアプリケーションにセッション機能を導入する方法を見ていきましょう。

セットアップ

SessionMiddlewareをFastAPIアプリケーションに追加するのは非常に簡単です。アプリケーションインスタンスを作成する際に、add_middlewareメソッドを使用します。

最も重要な設定は secret_key です。このキーは、セッションクッキーの署名に使用されます。このキーが漏洩すると、セッションデータを偽造される可能性があるため、非常に重要です。本番環境では、安全なランダムな値を使い、環境変数などから読み込むようにしてください。

“`python
import uvicorn
from fastapi import FastAPI, Request
from starlette.middleware.sessions import SessionMiddleware
import os

アプリケーションインスタンスを作成

app = FastAPI()

セッションミドルウェアを追加

secret_key は必須。本番環境では環境変数などから読み込むこと！

デバッグやテスト用に固定値を使うことも可能だが、非推奨。

SECRET_KEY = os.environ.get(“SESSION_SECRET_KEY”, “your-default-secret-key-please-change-me”)
app.add_middleware(SessionMiddleware, secret_key=SECRET_KEY)

FastAPIアプリケーションはUvicornなどのASGIサーバーで実行されます。

以下のif name == “main“:ブロックは、このスクリプトを直接実行可能にするためのものです。

if name == “main“:
uvicorn.run(app, host=”0.0.0.0”, port=8000)
“`

上記の例では、SECRET_KEYを環境変数から読み込み、環境変数が設定されていない場合のデフォルト値も指定しています。本番環境では、必ず環境変数などに設定し、コード内に直接書き込まないように強く推奨します。安全なsecret_keyを生成するには、例えばPythonのsecretsモジュールなどを使うことができます。

“`python
import secrets
import base64

ランダムなバイト列を生成

random_bytes = secrets.token_bytes(32) # 例: 32バイト

Base64エンコードして文字列にする

secret_key = base64.b64encode(random_bytes).decode(‘utf-8’)
print(secret_key)
``
生成された文字列を環境変数SESSION_SECRET_KEY` に設定して利用します。

SessionMiddlewareに追加できる主な設定オプションは以下の通りです。

  • secret_key (必須): セッションクッキーの署名に使用されるキーです。バイト列または文字列である必要があります。セキュリティ上非常に重要です。
  • cookie_name (デフォルト: 'session'): セッションIDを保存するクッキーの名前です。必要に応じて変更できます。
  • max_age (デフォルト: 14 * 24 * 60 * 60 (2週間)): セッションクッキーの有効期限を秒数で指定します。ブラウザはこの期間が過ぎるとクッキーを削除します。
  • https_only (デフォルト: False): Trueに設定すると、セッションクッキーはHTTPS接続でのみ送信されるようになります。本番環境では必ずTrueに設定してください。これにより、中間者攻撃によるセッションクッキーの盗聴を防ぎます。
  • same_site (デフォルト: 'lax'): クッキーのSameSite属性を設定します。クロスサイトリクエストにおけるクッキーの送信ルールを制御します。
    • 'strict': 同一サイトからのリクエストでのみ送信。
    • 'lax': 同一サイトからのリクエスト、または異なるサイトからのトップレベルナビゲーション（リンククリックなど）のGETリクエストで送信。
    • 'none': クロスサイトリクエストを含め、すべてのリクエストで送信（https_onlyが必須）。
      セキュリティを考慮すると、'lax'または'strict'が推奨されます。
  • session_cookie (デフォルト: True): Trueの場合、セッションクッキーにHttpOnly属性が設定されます。JavaScriptからのクッキーアクセスを防ぎ、XSS（クロスサイトスクリプティング）攻撃によるセッションIDの盗難リスクを軽減します。通常はTrueのままにしておくべきです。
  • path (デフォルト: '/'): クッキーが有効なパスを設定します。指定したパス以下のURLへのリクエストでのみクッキーが送信されます。
  • domain (デフォルト: None): クッキーが有効なドメインを設定します。サブドメイン間でセッションを共有したい場合などに設定します。
  • secure (デフォルト: False): Trueに設定すると、クッキーはHTTPS接続でのみ送信されます。https_only=Trueを設定した場合、内部的にこのオプションもTrueになります。通常はhttps_onlyを使えば十分です。

本番環境での設定例としては、以下のような形が推奨されます。

“`python
import uvicorn
from fastapi import FastAPI, Request
from starlette.middleware.sessions import SessionMiddleware
import os

app = FastAPI()

本番環境では必須：安全なキーを環境変数から読み込み

SECRET_KEY = os.environ.get(“SESSION_SECRET_KEY”)
if not SECRET_KEY:
# 本番環境ではキーが設定されていない場合はエラーとするなど、より厳密にすべき
print(“警告: SESSION_SECRET_KEY 環境変数が設定されていません。開発環境のみで利用してください。”)
SECRET_KEY = “fallback-secret-key-for-development” # 開発用フォールバック

app.add_middleware(
SessionMiddleware,
secret_key=SECRET_KEY,
max_age=3600, # セッション有効期限を1時間に設定 (秒)
https_only=True, # 本番環境では必須！HTTPS接続のみでクッキーを送信
same_site=’lax’ # CSRF対策に有効な設定の一つ
)

if name == “main“:
# 本番環境では host=’0.0.0.0′ は適切だが、portは環境に合わせて変更
uvicorn.run(app, host=”0.0.0.0”, port=8000)
“`

セッションデータへのアクセスと操作

SessionMiddlewareを追加すると、FastAPIのエンドポイントのRequestオブジェクトを通じてセッションデータにアクセスできるようになります。セッションデータは辞書ライクなオブジェクトとして提供されます。

  • セッションへのアクセス: リクエストハンドラー関数の引数としてrequest: Requestを受け取ることで、request.sessionとしてアクセスできます。
  • データの読み出し: request.session['key'] または request.session.get('key')
  • データの書き込み: request.session['key'] = value
  • データの削除: del request.session['key']
  • セッション全体のクリア: request.session.clear()

request.sessionはPythonの辞書と同じように操作できます。ただし、セッションデータとして保存できるのは、JSONとしてシリアライズ可能なデータ型（文字列、数値、ブール値、リスト、辞書など）に限られます。カスタムクラスのインスタンスなどを直接保存することはできません。

具体的なコード例

いくつかの具体的な例を通じて、セッションの操作方法を見てみましょう。

例1: シンプルな訪問回数カウンター

セッションを使って、ユーザーがページを訪れた回数をカウントする例です。

“`python
import uvicorn
from fastapi import FastAPI, Request
from starlette.middleware.sessions import SessionMiddleware
from starlette.responses import HTMLResponse
import os

app = FastAPI()

Secret key from environment or fallback for development

SECRET_KEY = os.environ.get(“SESSION_SECRET_KEY”, “your-default-secret-key-please-change-me”)
app.add_middleware(SessionMiddleware, secret_key=SECRET_KEY)

@app.get(“/”)
async def read_root(request: Request):
# セッションから ‘visit_count’ を取得。なければ 0
visit_count = request.session.get(‘visit_count’, 0)

# visit_count をインクリメント
visit_count += 1

# 更新した visit_count をセッションに保存
request.session['visit_count'] = visit_count

# HTMLレスポンスを返す
html_content = f"""
<!DOCTYPE html>
<html>
<head>
    <title>Visit Counter</title>
</head>
<body>
    <h1>FastAPI Session Counter</h1>
    <p>このページを訪れた回数: {visit_count} 回</p>
    <p><a href="/">リロードしてカウントを増やす</a></p>
    <p><a href="/clear">セッションをクリアする</a></p>
</body>
</html>
"""
return HTMLResponse(content=html_content)

@app.get(“/clear”)
async def clear_session(request: Request):
# セッション全体をクリア
request.session.clear()
html_content = “””
<!DOCTYPE html>


Session Cleared

Session Cleared

セッションデータがクリアされました。

カウンターページに戻る



“””
return HTMLResponse(content=html_content)

if name == “main“:
# 環境変数 SESSION_SECRET_KEY が設定されていなければ、警告を表示
if os.environ.get(“SESSION_SECRET_KEY”) is None:
print(“警告: 環境変数 SESSION_SECRET_KEY が設定されていません。開発/テスト用途以外では、安全なキーを設定してください。”)
print(f”現在のキー: {SECRET_KEY}”)

uvicorn.run(app, host="0.0.0.0", port=8000)

“`

このコードを実行し、ブラウザで http://localhost:8000/ にアクセスしてリロードを繰り返すと、表示される訪問回数が増えていくことが確認できます。/clear にアクセスするとセッションがリセットされ、カウンターが0に戻ります。

例2: シンプルなログイン状態の管理

セッションを使って、ユーザーがログインしているかどうかを管理する例です。ここでは認証の実際のロジックは省略し、セッションへのユーザー情報の保存と削除に焦点を当てます。

“`python
import uvicorn
from fastapi import FastAPI, Request, Form, HTTPException
from starlette.middleware.sessions import SessionMiddleware
from starlette.responses import HTMLResponse, RedirectResponse
from starlette.status import HTTP_303_SEE_OTHER
import os

app = FastAPI()

Secret key

SECRET_KEY = os.environ.get(“SESSION_SECRET_KEY”, “your-default-secret-key-please-change-me”)
app.add_middleware(SessionMiddleware, secret_key=SECRET_KEY)

ダミーのユーザーデータベース

DUMMY_USERS = {
“testuser”: {“password”: “password123”, “display_name”: “テストユーザー”}
}

@app.get(“/”)
async def read_root(request: Request):
# セッションからユーザー情報を取得
user = request.session.get(‘user’)

if user:
    # ログイン済みの場合はウェルカムメッセージを表示
    html_content = f"""
    <!DOCTYPE html>
    <html>
    <head>
        <title>Welcome</title>
    </head>
    <body>
        <h1>ようこそ、{user['display_name']}さん！</h1>
        <p>これはログイン後のページです。</p>
        <p><a href="/logout">ログアウト</a></p>
    </body>
    </html>
    """
else:
    # 未ログインの場合はログインフォームを表示
    html_content = """
    <!DOCTYPE html>
    <html>
    <head>
        <title>Login</title>
    </head>
    <body>
        <h1>ログイン</h1>
        <form action="/login" method="post">
            <label for="username">ユーザー名:</label><br>
            <input type="text" id="username" name="username"><br>
            <label for="password">パスワード:</label><br>
            <input type="password" id="password" name="password"><br><br>
            <input type="submit" value="ログイン">
        </form>
    </body>
    </html>
    """
return HTMLResponse(content=html_content)

@app.post(“/login”)
async def login(request: Request, username: str = Form(…), password: str = Form(…)):
# ダミーの認証ロジック
user_info = DUMMY_USERS.get(username)

if user_info and user_info["password"] == password:
    # 認証成功: セッションにユーザー情報を保存
    request.session['user'] = {"username": username, "display_name": user_info["display_name"]}
    # ログイン後、トップページにリダイレクト
    return RedirectResponse(url="/", status_code=HTTP_303_SEE_OTHER)
else:
    # 認証失敗
    # エラーメッセージなどをセッションに保存することも可能
    # request.session['error'] = "ユーザー名またはパスワードが違います"
    raise HTTPException(status_code=401, detail="Invalid credentials")

@app.get(“/logout”)
async def logout(request: Request):
# セッションからユーザー情報を削除
if ‘user’ in request.session:
del request.session[‘user’]
# またはセッション全体をクリア
# request.session.clear()

# ログアウト後、トップページにリダイレクト
return RedirectResponse(url="/", status_code=HTTP_303_SEE_OTHER)

if name == “main“:
# 環境変数 SESSION_SECRET_KEY が設定されていなければ、警告を表示
if os.environ.get(“SESSION_SECRET_KEY”) is None:
print(“警告: 環境変数 SESSION_SECRET_KEY が設定されていません。開発/テスト用途以外では、安全なキーを設定してください。”)
print(f”現在のキー: {SECRET_KEY}”)

uvicorn.run(app, host="0.0.0.0", port=8000)

“`

この例では、/ でログイン状態をチェックし、ログインしていなければログインフォームを表示します。フォームから /login にPOSTリクエストを送信すると、ダミーの認証を行い、成功すればセッションにユーザー情報を保存して / にリダイレクトします。/logout にアクセスするとセッションからユーザー情報を削除し、/ にリダイレクトして未ログイン状態に戻します。

このシンプルな例からもわかるように、request.sessionはPythonの辞書と同じ感覚で操作できるため、非常に直感的に利用できます。

高度な設定と注意点

SessionMiddlewareの各種設定オプションについて、さらに掘り下げてみましょう。

  • secret_key のセキュリティ:

    • 繰り返しになりますが、secret_keyはセッションデータの署名に使われるため、非常に重要です。予測可能なキーや短いキーは絶対に使用しないでください。
    • 安全なキーは、最低でも32バイト以上のランダムなバイト列をBase64エンコードしたものなどが推奨されます。
    • コード内に直接書き込むのは避け、環境変数やシークレット管理システムから読み込むように徹底してください。DockerやKubernetesなどのコンテナ環境では、シークレットとして安全に管理できます。

  • max_age の設定:

    • セッションの有効期限です。ユーザーの活動がなくてもセッションを維持したい期間を設定します。
    • セキュリティの観点からは、長すぎる有効期限は推奨されません。セッションハイジャックのリスクを高めます。機密性の高い情報を扱う場合は、有効期限を短く設定することを検討してください。
    • ユーザーがブラウザを閉じてもセッションを維持したい場合は、max_ageを適切な時間に設定します（永続的なセッション）。設定しない場合や0の場合は、ブラウザを閉じるとセッションクッキーは削除されます（ブラウザセッション）。

  • https_only の重要性:

    • このオプションをTrueに設定すると、セッションクッキーはHTTPS接続でのみブラウザからサーバーに送信されるようになります。
    • HTTP接続（暗号化されていない通信）では、セッションクッキーが平文でネットワーク上を流れてしまいます。これにより、攻撃者が通信を傍受してセッションクッキーを盗み、そのユーザーになりすます（セッションハイジャック）リスクが高まります。
    • 本番環境では、サイト全体をHTTPSで運用し、https_onlyをTrueに設定することは必須のセキュリティ対策です。

  • same_site 属性:

    • クロスサイトリクエストフォージェリ（CSRF）攻撃への対策の一つとして有効です。
    • 'lax' がデフォルトで推奨される設定です。これにより、サードパーティコンテキスト（例: 他のサイトに埋め込まれたiframeや画像リクエスト）からのリクエストではクッキーが送信されにくくなります。トップレベルナビゲーション（ユーザーがリンクをクリックしてサイトに遷移するなど）のGETリクエストでは送信されるため、多くのサイトで互換性があります。
    • 'strict' はより厳格で、同一サイトからのリクエストでのみクッキーが送信されます。CSRF対策としては強力ですが、他のサイトからのリンクをユーザーがクリックしてサイトに遷移した場合などでもセッションが引き継がれないため、ユーザー体験に影響を与える可能性があります。
    • 'none' はクロスサイトリクエストでもクッキーを送信しますが、この場合secure=True（またはhttps_only=True）が必須です。これは、広告配信など、意図的にクロスサイトでクッキーを送信する必要がある場合に利用されますが、セキュリティリスクを理解した上で慎重に使用する必要があります。
    • 特に理由がなければ、デフォルトの'lax'を使用するのが一般的です。

  • セッションクッキー名 (cookie_name) の変更:

    • デフォルトの 'session' 以外の名前に変更することで、使用しているフレームワークやライブラリの種類を隠蔽する効果がわずかに期待できますが、大きなセキュリティ効果はありません。識別しやすい名前にすることで、開発やデバッグがしやすくなる場合があります。

  • クッキーベースセッションの限界:

    • SessionMiddleware はクッキーベースのセッションです。セッションデータ全体がクッキーに格納され、各リクエスト/レスポンスでやり取りされます。
    • データ容量の制限: クッキーには通常、ブラウザごとに4KB程度の容量制限があります。大量のデータをセッションに保存することはできません。大きなリストや辞書を保存しようとすると、エラーが発生したり、クッキーが無視されたりする可能性があります。
    • パフォーマンス: セッションデータが大きいほど、リクエスト/レスポンスのヘッダーサイズが増加し、通信オーバーヘッドが増えます。
    • セキュリティ（機密性）: データは署名されているため改ざん検知は可能ですが、デフォルトでは暗号化されていません（StarletteのSessionMiddlewareは署名のみ）。機密性の高いデータをセッションに保存する場合、別途暗号化を検討するか、サーバーストレージ方式を選択する必要があります。ただし、署名だけでもデータの改ざんを防げるため、多くのユースケースでは十分です。パスワードやクレジットカード情報など、絶対にクライアント側に漏洩してはいけない情報はセッションクッキーに保存すべきではありません。

これらの点を踏まえて、アプリケーションの要件に合わせて適切な設定を行い、クッキーベースセッションの限界を理解しておくことが重要です。

より堅牢なセッション管理：サーバーストレージ

クッキーベースセッションの限界（容量制限、機密性の懸念、パフォーマンス）を克服するために、セッションデータをサーバー側のストレージに保存する「サーバーストレージベースセッション」という方式があります。

この方式では、クライアントのブラウザにはセッションIDのみを含む小さなクッキーを保存します。実際のセッションデータ（ログインしているユーザーの情報、ショッピングカートの内容など）は、サーバー上のデータベースやKVS（Key-Value Store）などに保存されます。サーバーはクライアントから送られてきたセッションIDを使って、ストレージから対応するセッションデータを取得します。

サーバーストレージとして利用できるものには、以下のようなものがあります。

  • メモリ: 最もシンプルですが、アプリケーションの再起動でデータが失われ、複数のサーバーインスタンスで共有できないため、開発・テスト用途に限定されます。
  • ファイル: ファイルシステムにセッションデータを保存します。メモリよりは永続性がありますが、I/Oオーバーヘッドがあり、複数のサーバーでの共有や同時アクセスに課題があります。
  • リレーショナルデータベース (PostgreSQL, MySQLなど): 構造化されたデータとしてセッションを管理できます。永続性があり、トランザクションなども利用可能ですが、セッション管理のためだけにRDBを使うのはオーバーキルな場合もあります。
  • NoSQLデータベース (MongoDBなど): ドキュメント指向などで柔軟にデータを保存できますが、セッション管理に特化しているわけではありません。
  • インメモリデータストア/KVS (Redis, Memcachedなど): キーと値の形式で高速にデータを読み書きできます。セッション管理のバックエンドとして非常に一般的で、高速性、永続性（Redisの場合）、分散対応など、多くの要件を満たせます。

FastAPI/Starletteでサーバーストレージベースのセッションを実装するには、以下のような方法があります。

  1. starlette-sessions のようなライブラリを使う:

    • これはStarlette/FastAPI向けのセッション管理ライブラリで、様々なバックエンドストレージに対応したアダプターを提供しています。
    • 例えば、starlette-sessions[redis] をインストールすればRedisをバックエンドとして利用できます。
    • ミドルウェアとしてアプリケーションに追加し、どのバックエンドを使用するかを設定します。

    簡単な例（Redisバックエンドの場合 – starlette-sessions[redis] がインストールされている前提）：

    “`python
    import uvicorn
    from fastapi import FastAPI, Request
    from starlette_sessions import SessionMiddleware
    from starlette_sessions.stores import RedisStore
    import redis

    Redisクライアントを初期化 (ローカルで動作している前提)

    redis_client = redis.Redis(host=’localhost’, port=6379, db=0)
    store = RedisStore(redis_client=redis_client)

    app = FastAPI()

    セッションミドルウェアを追加し、ストアを指定

    secret_key は署名/暗号化に使われるわけではないが、セッションID生成などに使われる場合がある

    ここではストアがデータ管理を行うため、SessionMiddlewareの設定はシンプルになる

    app.add_middleware(
    SessionMiddleware,
    store=store,
    cookie_name=’server_session_id’, # セッションIDを保存するクッキー名
    max_age=3600,
    https_only=False # 本番環境ではTrueに！
    )

    @app.get(“/”)
    async def read_root(request: Request):
    visit_count = request.session.get(‘visit_count’, 0)
    visit_count += 1
    request.session[‘visit_count’] = visit_count # データはRedisに保存される
    return {“message”: f”Visit count: {visit_count}”}

    @app.get(“/clear”)
    async def clear_session(request: Request):
    await request.session.clear() # 非同期操作になる場合がある
    return {“message”: “Session cleared”}

    if name == “main“:
    uvicorn.run(app, host=”0.0.0.0”, port=8000)
    ``
    このように、    starlette-sessionsを使うことで、バックエンドのストレージを簡単に切り替えたり、SessionMiddlewareにはない高度な機能（例えば、特定のセッションIDをサーバー側から強制的に無効化するなど）を利用できるようになります。ただし、ライブラリの仕様やAPIはstarlette.middleware.sessions.SessionMiddlewareとは異なる場合があるため、ドキュメントを確認する必要があります。上記の例はstarlette-sessions`の概念を示すためのものであり、実際のAPIはライブラリのバージョンによって異なる可能性があります。

  2. 自前で実装する:

    • FastAPIの依存性注入（Dependency Injection）システムやミドルウェアを活用して、セッションIDを含むクッキーの読み書き、サーバー側ストレージとの連携ロジックを自前で実装することも可能です。
    • これは最も柔軟な方法ですが、実装コストが高く、セキュリティ（セッションIDの安全な生成、ストレージへの安全なアクセス、セッション固定攻撃やハイジャックへの対策など）に関する深い知識が必要になります。
    • 特別な要件がある場合や、既存のセッション管理システムと連携する必要がある場合に検討されることがあります。

サーバーストレージベースセッションは、クッキーベースの制限を克服し、より大規模でセキュアなアプリケーションに適しています。特に、複数のサーバーでアプリケーションを運用する場合（ロードバランシングやオートスケーリング）、セッションデータを共有できる外部ストレージ（Redisなど）を利用することが必須となります。

どの方式を選択するかは、アプリケーションの規模、データの機密性、開発チームのスキルセット、運用体制などを総合的に考慮して決定する必要があります。多くの場合、小規模から中規模のアプリケーションで、機密性の高くないデータを扱う場合は、SessionMiddlewareを使ったクッキーベースセッションで十分であり、導入の容易さから推奨されます。より高度な要件やセキュリティが求められる場合は、サーバーストレージベースのセッション、特にRedisなどをバックエンドとするstarlette-sessionsのようなライブラリの利用を検討するのが良いでしょう。

セッションと認証

セッションは認証機能と密接に関連しています。認証とは、ユーザーが「誰であるか」を確認するプロセスです。セッションは、認証済みのユーザーの状態を、複数のリクエスト間で維持するための仕組みです。

一般的なセッションを使った認証フローは以下のようになります。

  1. ログインリクエスト: ユーザーがユーザー名とパスワードを送信してログインを試みます。
  2. 認証: サーバーは送信されたユーザー名とパスワードを検証します（データベースの照合など）。
  3. セッションの開始: 認証に成功した場合、サーバーはそのユーザーのためのセッションを開始します。セッションIDが生成され、セッションストア（クッキーまたはサーバーストレージ）にユーザー情報（ユーザーID、ユーザー名など）が保存されます。
  4. セッションIDの送信: サーバーはセッションIDをクライアントのブラウザにクッキーとして送信します。
  5. 認証済みリクエスト: 以降、ブラウザはセッションIDクッキーを含むリクエストを送信します。
  6. セッションデータの取得: サーバーは受信したセッションIDを使って、セッションストアからユーザー情報を取得します。
  7. 認証状態の確認: サーバーはセッションデータが存在し、有効であることを確認し、そのユーザーがログイン済みであると判断します。
  8. リソースへのアクセス: ログイン済みユーザーのみがアクセスできるリソース（例: マイページ、設定変更画面）へのアクセスを許可します。
  9. ログアウトリクエスト: ユーザーがログアウトをリクエストします。
  10. セッションの破棄: サーバーはセッションストアから対応するセッションデータを削除し、ブラウザにセッションクッキーを削除するよう指示します（有効期限を過去に設定するなど）。

FastAPIでは、この認証フローを実現するためにセッションを活用できます。例えば、先ほどのログイン例のように、認証成功時にユーザー情報をセッションに保存し、各リクエストでセッションをチェックしてユーザーがログイン済みかどうかを判断します。

FastAPIでは、認証機能をより構造的に実装するために、依存性注入システムを活用することがよくあります。例えば、セッションにユーザー情報が存在するかどうかをチェックし、存在すればそのユーザーオブジェクトを返し、存在しなければ認証エラー（例: HTTPException(status_code=401)）を発生させる依存関数を作成できます。この依存関数を各エンドポイントに追加することで、簡単に認証ガードを設けることができます。

“`python
from fastapi import FastAPI, Request, Depends, HTTPException, status
from starlette.middleware.sessions import SessionMiddleware
import os

… (SessionMiddlewareのセットアップは省略) …

SECRET_KEY = os.environ.get(“SESSION_SECRET_KEY”, “your-default-secret-key-please-change-me”)
app = FastAPI()
app.add_middleware(SessionMiddleware, secret_key=SECRET_KEY)

認証済みのユーザーを取得する依存関数

async def get_current_user(request: Request):
user = request.session.get(‘user’)
if user is None:
# 認証されていない場合は401 Unauthorizedエラーを返す
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=”Not authenticated”
# WWW-Authenticateヘッダーを追加することも可能だが、ここでは省略
)
return user

@app.get(“/profile”)
async def read_profile(current_user: dict = Depends(get_current_user)):
# get_current_user が成功した場合のみ、このエンドポイントに到達
return {“message”: f”プロフィールページへようこそ、{current_user[‘display_name’]}さん”}

… (ログイン/ログアウトエンドポイントは前の例を参照) …

“`

このように依存性注入と組み合わせることで、認証ロジックを再利用可能な関数として定義し、セッションベースの認証をFastAPIで効果的に実装できます。

ただし、セッション自体は認証を行うメカニズムではなく、認証状態を維持するための手段であることに注意してください。強力なパスワードポリシー、安全な認証情報の保管、レート制限などの認証に関するセキュリティ対策は別途必要です。

セキュリティに関する考慮事項

セッション管理は、ユーザーの状態を維持する便利な機能である一方で、セキュリティリスクも伴います。特にクッキーベースのセッション（SessionMiddleware）を利用する場合、以下のセキュリティに関する考慮事項を理解し、適切な対策を講じることが非常に重要です。

  1. secret_key の管理:

    • 最も重要な対策です。このキーが漏洩すると、攻撃者はセッションクッキーを偽造したり、セッションデータを改ざんしたりすることが可能になります。
    • 安全なランダムなキーを使用し、環境変数やシークレット管理システムを通じてアプリケーションに渡すようにしてください。バージョン管理システム（Gitなど）にコードの一部として含めないようにしましょう。

  2. HTTPSの使用 (https_only=True):

    • セッションクッキーがHTTP接続で送信されると、ネットワーク上の第三者によって容易に傍受されてしまいます。これにより、セッションハイジャック攻撃が可能になります。
    • 本番環境ではサイト全体をHTTPSで運用し、SessionMiddlewareのhttps_onlyオプションをTrueに設定することは絶対に行うべき必須の対策です。

  3. HttpOnly 属性 (session_cookie=True):

    • この属性が付与されたクッキーは、JavaScriptからアクセスすることができません（document.cookieなどで読み取れない）。
    • これにより、XSS（クロスサイトスクリプティング）攻撃が発生した場合でも、攻撃者がセッションクッキーを盗み出すリスクを大幅に軽減できます。
    • SessionMiddlewareではデフォルトでsession_cookie=Trueとなっているため、通常はこのままで問題ありません。特別な理由がない限り変更しないでください。

  4. SameSite 属性:

    • CSRF（クロスサイトリクエストフォージェリ）攻撃への対策として有効です。
    • 異なるサイトからのリクエスト時にセッションクッキーが自動送信されるのを制御します。
    • デフォルトの'lax'は多くのケースで安全かつ互換性があります。より厳格なセキュリティが必要な場合は'strict'を検討します。'none'はhttps_only=Trueが必須であり、特別な理由がない限り避けるべきです。

  5. セッション有効期限 (max_age) の適切な設定:

    • セッションが長期間有効すぎると、セッションハイジャックされたクッキーが長く悪用されるリスクが高まります。
    • アプリケーションのセキュリティ要件に合わせて、適切な有効期限を設定してください。機密性の高い情報を扱うセッション（例: 銀行取引）は短く、一般的な利用のセッション（例: ブログのログイン状態）は長くするなど、柔軟に設定できます。
    • ユーザーがログアウトした際には、必ずセッションをサーバー側で破棄する処理（request.session.clear()など）を実行してください。

  6. セッション固定攻撃 (Session Fixation):

    • 攻撃者が正規ユーザーに対して、事前に用意したセッションIDを使わせる攻撃です。ユーザーがそのセッションIDでログインすると、攻撃者はそのセッションIDを使ってユーザーになりすますことができます。
    • 対策としては、ログイン成功時にセッションIDを再生成することが有効です。SessionMiddlewareはデフォルトでログイン成功時にセッションIDを再生成する機能は持っていませんが、より高度なセッションライブラリや、自前での実装で対応可能です。または、ログイン成功後に新しいセッションデータで上書き保存し、古いセッションIDでアクセスできなくするなどの工夫が考えられます。

  7. セッションハイジャック (Session Hijacking):

    • 攻撃者が何らかの方法で正規ユーザーのセッションIDを盗み出し、そのセッションIDを使ってユーザーになりすます攻撃です。
    • 主な対策は、HTTPSの使用、HttpOnly属性、短いセッション有効期限、そして可能であればセッションIDの再生成です。ユーザーのIPアドレスやユーザーエージェントなどがセッション開始時と異なる場合に警告を出す、あるいは再認証を求めるなどの対策も考えられますが、これらはユーザー体験に影響を与える可能性があるため、慎重な検討が必要です。

  8. クッキーへの機密情報の保存:

    • クッキーベースセッションの場合、セッションデータは署名されているとはいえ、クライアント側のブラウザに保存されます。
    • パスワード、クレジットカード情報、個人情報など、絶対にクライアント側に漏洩してはいけない機密情報は、セッションクッキーに直接保存しないでください。
    • これらの情報はサーバー側の安全な場所に（例えば、データベースに暗号化して）保存し、セッションにはその情報への参照（ユーザーIDなど）のみを保存するように設計すべきです。

これらのセキュリティ対策を適切に講じることで、FastAPIアプリケーションにおけるセッション管理をより安全に行うことができます。特に、HTTPSの利用とsecret_keyの安全な管理は、セッションセキュリティの基本中の基本であることを忘れないでください。

まとめ

この記事では、FastAPIでセッションを使うための詳細な方法について解説しました。

FastAPIはデフォルトでセッション機能を持っていませんが、基盤であるStarletteのSessionMiddlewareを利用することで、手軽にクッキーベースのセッション機能を導入できます。SessionMiddlewareは、セッションデータを署名付きクッキーとしてクライアントに保存し、リクエストオブジェクト(request.session)を通じてPythonの辞書ライクなインターフェースでセッションデータの読み書きを可能にします。

SessionMiddlewareをアプリケーションに追加する際は、特にsecret_key、max_age、https_only、same_siteといったオプションを適切に設定することが重要です。中でもsecret_keyの安全な管理と、本番環境でのHTTPS利用およびhttps_only=Trueの設定は、セッションセキュリティの観点から必須と言えます。

クッキーベースセッションは手軽さが魅力ですが、データ容量に制限があり、機密性の高いデータ保存には注意が必要です。より堅牢で大規模なアプリケーションでは、セッションIDのみをクッキーに保存し、実際のセッションデータをサーバー側のストレージ（Redis, データベースなど）に保存する「サーバーストレージベースセッション」が適しています。FastAPI/Starletteでは、starlette-sessionsのようなライブラリがこの方式をサポートしています。

セッションは認証機能と密接に関連しており、ログイン状態の維持などに広く利用されます。FastAPIの依存性注入システムを活用することで、セッションを使った認証ロジックを効果的に実装できます。

セッション管理にはセキュリティリスクが伴います。secret_keyの厳重な管理、HTTPSの強制、HttpOnly属性、SameSite属性の利用、適切なセッション有効期限の設定、機密情報の取り扱いに十分注意することで、これらのリスクを軽減できます。

この記事を通じて、あなたはFastAPIでのセッションの必要性、SessionMiddlewareを使った基本的な実装方法、設定オプションの意味、およびセッション管理におけるセキュリティ上の重要な考慮事項について学ぶことができました。

多くの場合、小規模から中規模のWebアプリケーションであれば、SessionMiddlewareを使ったクッキーベースセッションで十分な機能と手軽さを得られます。一方で、大規模なシステム、高いセキュリティ要件、あるいは大量のセッションデータを扱う必要がある場合は、サーバーストレージベースのセッションを検討することをお勧めします。

FastAPIでセッションを使いこなすことで、よりリッチでインタラクティブなWebアプリケーションを構築することが可能になります。ぜひ、これらの知識を活かして、あなたのFastAPIプロジェクトにセッション機能を実装してみてください。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール