ログアウト

ログアウトを行うPOST /logoutエンドポイントを実装します。JWTはステートレスな設計上、発行済みのアクセストークンをサーバ側から即時に無効化することは本来できません。「ログアウトしても、そのアクセストークンが有効期限まで生き残ってしまう」という状態は本来のログアウトの意図とかみ合わないため、DBにアクセストークンの無効化リスト(ブラックリスト)を持ち、認証依存で照合する形で即時無効化を実現します。

本章のログアウトでは、以下の2つを同時に行います。

  • アクセストークンをrevoked_access_tokensテーブルに登録し、認証依存で拒否させる
  • リフレッシュトークンをrefresh_tokensテーブルのrevoked_atで失効させ、以降の/refreshを拒否させる

1. 無効化用モデルの追加

まず、失効させたアクセストークンを管理するモデルをmodels.pyに追加します。

class RevokedAccessToken(SQLModel, table=True):
    __tablename__ = "revoked_access_tokens"
    id: Optional[int] = Field(default=None, primary_key=True)
    token: str = Field(sa_column=Column(String(512), unique=True, nullable=False, index=True))
    expires_at: datetime
    revoked_at: datetime = Field(default_factory=datetime.utcnow)

続いて、setup_db.pyでSQLModel.metadata.create_allが実行される際に新しいモデルが認識されるよう、setup_db.pyのimport側にもRevokedAccessTokenが含まれていることを確認します(from models import ...で*または対象モデルを列挙している場合、RevokedAccessTokenも併せてimportします)。準備できたら、テーブル作成スクリプトを実行してrevoked_access_tokensテーブルを作成します。

Windowsの場合:

python setup_db.py

Macの場合:

python3 setup_db.py

コードを解説します。

token: str = Field(sa_column=Column(String(512), unique=True, nullable=False, index=True))

TokenにはJWTの文字列そのものを保管します。JWTはヘッダ.ペイロード.署名の3パートを連結した長めの文字列なので、String(512)で十分な長さを確保します。unique=Trueとindex=Trueにより、同じトークンを重複登録しない制約と、検索の高速化を同時に指定しています。

expires_at: datetime

このトークンの有効期限(JWT側のexpと同じ値)を保存します。今回のハンズオンでは使いませんが、有効期限を過ぎたレコードは検証時に既に弾かれるため、バッチ処理で古いレコードを削除するためのカラムになります。

2. 認証依存への無効化チェック追加

続いて、get_current_userに「アクセストークンがブラックリストに載っていないか」を確認する処理を追加します。dependencies.pyのimportにselectとRevokedAccessTokenを追加します。

from typing import Annotated

from fastapi import Depends, HTTPException
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from sqlmodel import Session, select

from auth import parse_access_token
from database import get_session
from models import RevokedAccessToken, User

続いて、get_current_userを以下のように書き換えます。

def get_current_user(
    credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    session: Annotated[Session, Depends(get_session)],
) -> User:
    try:
        user_id = parse_access_token(credentials.credentials)
    except Exception:
        raise HTTPException(status_code=401, detail="トークンが無効です")

    revoked = session.exec(
        select(RevokedAccessToken).where(
            RevokedAccessToken.token == credentials.credentials
        )
    ).first()
    if revoked is not None:
        raise HTTPException(status_code=401, detail="トークンが無効化されています")

    user = session.get(User, user_id)
    if user is None:
        raise HTTPException(status_code=401, detail="ユーザが見つかりません")
    return user

コードを解説します。

revoked = session.exec(
    select(RevokedAccessToken).where(
        RevokedAccessToken.token == credentials.credentials
    )
).first()
if revoked is not None:
    raise HTTPException(status_code=401, detail="トークンが無効化されています")

JWTの検証(署名・有効期限)を通過したあとに、revoked_access_tokensテーブルにそのトークンが登録されていないかを確認します。見つかった場合は無効化済みとして401 Unauthorizedで拒否します。この照合が入ることで、ログアウト直後のアクセストークンを即座に拒否できるようになります。

3. logout ハンドラの追加

handlers.pyのimportにtimedelta、HTTPAuthorizationCredentials、ACCESS_TOKEN_TTL_SECONDS、RevokedAccessToken、dependenciesのsecurityを追加します。

from datetime import datetime, timedelta
from typing import Annotated

from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import HTTPAuthorizationCredentials
from sqlmodel import Session, select

from auth import (
    ACCESS_TOKEN_TTL_SECONDS,
    generate_access_token,
    generate_refresh_token,
    hash_password,
    refresh_token_expires_at,
    verify_password,
)
from database import get_session
from dependencies import get_current_user, security
from models import (
    LoginRequest,
    RefreshRequest,
    RefreshToken,
    RevokedAccessToken,
    SignupRequest,
    TokenResponse,
    User,
)

続いて、handlers.pyの末尾(refresh関数の下)にlogoutハンドラを追加します。アクセストークンをrevoked_access_tokensテーブルに登録し、あわせてリフレッシュトークンも失効させます。Depends(get_current_user)を付けることで、認証依存を通過したリクエストだけがこのハンドラに到達するようになります。

@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
def logout(
    payload: RefreshRequest,
    credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    current_user: Annotated[User, Depends(get_current_user)],
    session: Annotated[Session, Depends(get_session)],
):
    revoked = RevokedAccessToken(
        token=credentials.credentials,
        expires_at=datetime.utcnow() + timedelta(seconds=ACCESS_TOKEN_TTL_SECONDS),
    )
    session.add(revoked)

    rt = session.exec(
        select(RefreshToken).where(
            RefreshToken.token == payload.refresh_token,
            RefreshToken.revoked_at.is_(None),
        )
    ).first()
    if rt is not None:
        rt.revoked_at = datetime.utcnow()
        session.add(rt)

    session.commit()

4. コードの解説

@router.post("/logout", status_code=status.HTTP_204_NO_CONTENT)
def logout(
    payload: RefreshRequest,
    credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    current_user: Annotated[User, Depends(get_current_user)],
    session: Annotated[Session, Depends(get_session)],
):

logoutハンドラのシグネチャです。payloadでリフレッシュトークンを、credentialsで生のアクセストークン文字列(Bearer を除いた部分)を取り出し、get_current_userで認証必須にします。get_current_userを通過するのは有効かつ無効化されていないトークンだけなので、このハンドラに到達する時点でトークンは有効です。status_code=status.HTTP_204_NO_CONTENTにより、戻り値なしでも204 No Contentが返る設定です。

revoked = RevokedAccessToken(
    token=credentials.credentials,
    expires_at=datetime.utcnow() + timedelta(seconds=ACCESS_TOKEN_TTL_SECONDS),
)
session.add(revoked)

取り出したアクセストークンをrevoked_access_tokensテーブルに登録します。以降このトークンで保護されたAPIを叩くと、get_current_userのブラックリスト照合で弾かれるようになります。

rt = session.exec(
    select(RefreshToken).where(
        RefreshToken.token == payload.refresh_token,
        RefreshToken.revoked_at.is_(None),
    )
).first()
if rt is not None:
    rt.revoked_at = datetime.utcnow()
    session.add(rt)

続けて、リクエストボディで受け取ったリフレッシュトークンをrefresh_tokensテーブルのrevoked_atで失効させます。revoked_at IS NULLの条件で、まだ失効していないレコードだけを対象にします。

session.commit()

アクセストークンのブラックリスト登録とリフレッシュトークンの失効を同じトランザクションでコミットします。status_code=status.HTTP_204_NO_CONTENTの指定により、戻り値なしでも204 No Contentが返る設定です。

5. 動作確認

前のセクションで取得した最新のアクセストークン(eyJhbGci...)とリフレッシュトークン(a91b7e3d...)を/logoutに送り、両方を失効させます。アクセストークンはAuthorizationヘッダに、リフレッシュトークンはリクエストボディに載せます。

curl -i -X POST http://localhost:8000/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"a91b7e3d..."}'

以下のような実行結果が表示されます。

HTTP/1.1 204 No Content

204 No Contentが返り、アクセストークンはrevoked_access_tokensテーブルに登録され、リフレッシュトークンはrefresh_tokensテーブルのrevoked_atに時刻が入りました。

即時無効化が働いていることを確認するため、先ほどログアウトに使ったアクセストークンで、もう一度/notesを叩いてみます。

curl -i -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." http://localhost:8000/notes

以下のような実行結果が表示されます。

HTTP/1.1 401 Unauthorized
...
{"detail":"トークンが無効化されています"}

アクセストークン自体はまだ有効期限内ですが、get_current_userのブラックリスト照合で拒否されました。JWTが本来持てなかった「即時無効化」を、DBのブラックリストで実現できていることが確認できます。

念のため、リフレッシュトークン側も無効化されていることを確認します。同じリフレッシュトークンで/refreshを叩くと、失効エラーで拒否されます。

curl -X POST http://localhost:8000/refresh -H "Content-Type: application/json" -d '{"refresh_token":"a91b7e3d..."}'
{"detail":"refresh token が無効または失効しています"}

アクセストークン・リフレッシュトークンの両方が無効化された状態になり、そのセッションからは新規のトークン発行もAPI呼び出しもできなくなりました。これで、DB管理方式による即時無効化を含めたログアウトの仕組みが一通り動くことが確認できます。

💡 ポイント
revoked_access_tokensテーブルは、放置すると失効済みトークンのレコードが増え続けます。expires_atを過ぎたレコードは有効期限側でどのみち弾かれるため、日次のバッチ処理などでexpires_at < NOW()のレコードをDELETEする運用にすると、テーブルサイズを一定に保てます。本章では簡素化のためクリーンアップ処理は入れていません。