認証機能の実装準備

ここからハンズオンに入ります。プロジェクトフォルダの初期化、依存パッケージの導入、データベース・モデル・接続設定の準備までを行います。

1. プロジェクトの準備

任意の場所にjwt-auth-hands-onフォルダを作成し、Visual Studio Codeの「ファイル」→「フォルダーを開く」から作成したjwt-auth-hands-onフォルダを開きます。以降の操作は、Visual Studio Codeのターミナルから行います。

jwt-auth-hands-on/  ← このフォルダを作成

以下のコマンドで、Pythonがインストールされていることを確認します。

Windowsの場合:

python --version

Macの場合:

python3 --version

以下のようにPythonのバージョンが表示されれば、インストールは確認できています。

Python 3.12.x

バージョンが表示されない場合は、Pythonのインストールを先に実施してください。

続いて、必要なパッケージをまとめてインストールします。

Windowsの場合:

pip install fastapi uvicorn sqlmodel pymysql python-dotenv pyjwt bcrypt

Macの場合:

pip3 install fastapi uvicorn sqlmodel pymysql python-dotenv pyjwt bcrypt

インストールした各ライブラリの役割は以下のとおりです。

ライブラリ 役割
FastAPI 認証APIを実装するWebフレームワーク
uvicorn FastAPIアプリケーションを動かすASGI対応Webサーバ
SQLModel users・refresh_tokensテーブルをPythonクラスで扱うORM
PyMySQL PythonからMySQLに接続するドライバ
python-dotenv .envファイルから環境変数を読み込むライブラリ
PyJWT JWTの発行・検証を行うライブラリ
bcrypt パスワードのソルト付きハッシュ化・検証を行うライブラリ

2. データベースの作成

認証APIから接続するデータベースを作成します。テーブルはSQLModelから自動生成するため、ここではデータベースだけ用意します。

以下のコマンドで、MySQLがインストールされていることを確認します。

mysql --version

以下のようにMySQLのバージョンが表示されれば、インストールは確認できています。

mysql  Ver 8.0.xx for macos on arm64 (MySQL Community Server - GPL)

バージョンが表示されない場合は、MySQLのインストールを先に実施してください。

続いて、auth_hands_onデータベースを作成します。

mysql -u root -p -e "CREATE DATABASE auth_hands_on;"

パスワードを入力してエラーが出なければ、データベースが作成されています。

3. 環境変数ファイル(.env)の作成

DB接続情報とJWTの署名鍵を.envファイルにまとめます。Visual Studio Codeのエクスプローラーでjwt-auth-hands-onフォルダを右クリックし、「新しいファイル」を選択して.envという名前で作成します。

jwt-auth-hands-on/
└── .env  ← このファイルを作成

作成したファイルに以下の内容を記述して保存します。

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=auth_hands_on
JWT_SECRET=dev-secret-please-change
💡 ポイント
DB_PASSWORDは、MySQLのインストール時に設定したrootパスワードに置き換えてください。JWT_SECRETはJWTの署名に使う鍵で、開発時は任意の文字列で構いませんが、本番環境ではランダムに生成した十分な長さの値を使い、.envファイルは.gitignoreに加えてGitに含めないようにします。

4. モデル定義(models.py)

usersテーブルとrefresh_tokensテーブルに対応するSQLModelを定義します。同時に、リクエスト・レスポンスで使う非テーブルモデルもここに置きます。

Visual Studio Codeのエクスプローラーでjwt-auth-hands-onフォルダを右クリックし、「新しいファイル」を選択してmodels.pyを作成します。

jwt-auth-hands-on/
├── .env
└── models.py  ← このファイルを作成

作成したファイルに以下の内容を記述して保存します。

from datetime import datetime
from typing import Optional

from sqlmodel import Field, SQLModel

class User(SQLModel, table=True):
    __tablename__ = "users"
    id: Optional[int] = Field(default=None, primary_key=True)
    email: str = Field(unique=True, index=True, max_length=255)
    password_hash: str = Field(max_length=255)
    created_at: datetime = Field(default_factory=datetime.utcnow)

class RefreshToken(SQLModel, table=True):
    __tablename__ = "refresh_tokens"
    id: Optional[int] = Field(default=None, primary_key=True)
    user_id: int = Field(foreign_key="users.id", index=True)
    token: str = Field(unique=True, index=True, max_length=255)
    expires_at: datetime
    revoked_at: Optional[datetime] = None
    created_at: datetime = Field(default_factory=datetime.utcnow)

class SignupRequest(SQLModel):
    email: str
    password: str

class LoginRequest(SQLModel):
    email: str
    password: str

class TokenResponse(SQLModel):
    access_token: str
    refresh_token: str

class RefreshRequest(SQLModel):
    refresh_token: str

コードを解説します。

class User(SQLModel, table=True):
    __tablename__ = "users"
    id: Optional[int] = Field(default=None, primary_key=True)
    email: str = Field(unique=True, index=True, max_length=255)
    password_hash: str = Field(max_length=255)
    created_at: datetime = Field(default_factory=datetime.utcnow)

ユーザを表すテーブルモデルです。emailにはunique=Trueとindex=Trueを付けて重複登録を防ぎ、検索を高速化しています。password_hashにはハッシュ化された文字列を保存する前提のカラムです。

class RefreshToken(SQLModel, table=True):
    __tablename__ = "refresh_tokens"
    ...
    expires_at: datetime
    revoked_at: Optional[datetime] = None

リフレッシュトークンを表すテーブルモデルです。tokenカラムに発行済みのトークン文字列を保存し、expires_atで有効期限、revoked_atで失効時刻を管理します。revoked_atをOptional[datetime]にすることで、「まだ失効していない状態(NULL)」と「失効済み(時刻あり)」を区別できます。

class SignupRequest(SQLModel):
    email: str
    password: str

リクエストボディで使う非テーブルモデルです。table=Trueを指定していないため、DBには対応せずバリデーションのためだけに使われます。テーブルモデルとリクエストモデルを分けておくと、レスポンスにpassword_hashを含めるといった事故を防げます。

class TokenResponse(SQLModel):
    access_token: str
    refresh_token: str

ログイン・リフレッシュのレスポンスで返すトークンの組を表すモデルです。エンドポイント側で戻り値の型として使うことで、Swagger UIにスキーマが表示されるようになります。

5. DB接続設定(database.py)

続いて、DB接続とSessionの生成を扱うdatabase.pyを作成します。

jwt-auth-hands-on/
├── .env
├── models.py
└── database.py  ← このファイルを作成

作成したファイルに以下の内容を記述して保存します。

import os

from dotenv import load_dotenv
from sqlmodel import Session, SQLModel, create_engine

load_dotenv()

DB_HOST = os.getenv("DB_HOST", "localhost")
DB_USER = os.getenv("DB_USER", "root")
DB_PASSWORD = os.getenv("DB_PASSWORD", "")
DB_NAME = os.getenv("DB_NAME", "auth_hands_on")

DATABASE_URL = f"mysql+pymysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}/{DB_NAME}"

engine = create_engine(DATABASE_URL)

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

def get_session():
    with Session(engine) as session:
        yield session

前章までで扱った内容と同じ構成で、.envから接続情報を読み込み、create_engineでengineを作成しています。create_db_and_tablesはSQLModel.metadata.create_allでmodels.pyで定義したテーブルを一括作成し、get_sessionはDependsで注入するためのSessionのジェネレータです。

6. テーブル作成スクリプト(setup_db.py)

create_db_and_tablesを呼び出してテーブルを作成する独立スクリプトを作成します。アプリケーションの起動時ではなく、初回セットアップ時に一度だけ実行する形にします。

jwt-auth-hands-on/
├── .env
├── models.py
├── database.py
└── setup_db.py  ← このファイルを作成

作成したファイルに以下の内容を記述して保存します。

from database import create_db_and_tables
import models  # SQLModel.metadata にテーブル定義を登録するためのインポート

if __name__ == "__main__":
    create_db_and_tables()
    print("tables created.")

以下のコマンドでスクリプトを実行します。

Windowsの場合:

python setup_db.py

Macの場合:

python3 setup_db.py

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

tables created.

MySQL CLIでusersテーブルとrefresh_tokensテーブルが作成されていることを確認します。

mysql -u root -p -e "USE auth_hands_on; SHOW TABLES;"

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

+-------------------------+
| Tables_in_auth_hands_on |
+-------------------------+
| refresh_tokens          |
| users                   |
+-------------------------+

usersとrefresh_tokensが並んでいれば、モデルからのテーブル作成は成功しています。