FastAPIにJWT認証を実装する(PyJWT + pwdlib)

FastAPI
スポンサーリンク

FastAPIで、ログインするとJWTのトークンを発行し、トークンを付けたリクエストだけを通すAPIを作ります。実際に動かして、トークンの期限切れや改ざんがどう扱われるかも確かめました。

結論

FastAPIの公式チュートリアルと同じく、トークンの作成と検証には PyJWT、パスワードのハッシュには pwdlib(Argon2)を使います。公式チュートリアルのコードをもとに、秘密鍵を環境変数から読むように変え、確認に必要な部分だけにしぼったのが次の main.py です。

import os
from datetime import datetime, timedelta, timezone
from typing import Annotated

import jwt
from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jwt.exceptions import InvalidTokenError
from pwdlib import PasswordHash
from pydantic import BaseModel

# 秘密鍵はコードに書かず、環境変数で渡す
SECRET_KEY = os.environ["SECRET_KEY"]
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = int(os.environ.get("ACCESS_TOKEN_EXPIRE_MINUTES", "30"))

password_hash = PasswordHash.recommended()
DUMMY_HASH = password_hash.hash("dummypassword")

# 確認用のユーザー。本番では、データベースに保存したハッシュを使う
fake_users_db = {
    "alice": {"username": "alice", "hashed_password": password_hash.hash("secret")},
}


class Token(BaseModel):
    access_token: str
    token_type: str


class User(BaseModel):
    username: str


oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()


def authenticate_user(username: str, password: str) -> User | None:
    user = fake_users_db.get(username)
    if user is None:
        # ユーザーがいなくても照合して、応答時間の差を小さくする
        password_hash.verify(password, DUMMY_HASH)
        return None
    if not password_hash.verify(password, user["hashed_password"]):
        return None
    return User(username=user["username"])


def create_access_token(username: str) -> str:
    expire = datetime.now(timezone.utc) + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    return jwt.encode({"sub": username, "exp": expire}, SECRET_KEY, algorithm=ALGORITHM)


async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]) -> User:
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
    except InvalidTokenError:
        raise credentials_exception
    username = payload.get("sub")
    if username is None or username not in fake_users_db:
        raise credentials_exception
    return User(username=username)


@app.post("/token")
async def login(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]) -> Token:
    user = authenticate_user(form_data.username, form_data.password)
    if user is None:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return Token(access_token=create_access_token(user.username), token_type="bearer")


@app.get("/users/me")
async def read_users_me(current_user: Annotated[User, Depends(get_current_user)]) -> User:
    return current_user
  • POST /token にユーザー名とパスワードを送ると、トークンが返ります。
  • GET /users/me は、Authorization: Bearer <トークン> のヘッダーがあり、トークンを検証できたときだけ応答します。
  • 存在しないユーザーでもダミーのハッシュと照合するのは、公式チュートリアルのコードにならったものです。ユーザーの有無で応答時間に差が出にくくする狙いです。
  • ユーザーとパスワード(alice、secret)は確認用の例です。本番では、データベースに保存したハッシュを使います。

動作確認した環境

  • Python 3.15.2(Dockerイメージ python:3.15.2-slim)
  • FastAPI 0.162.0、uvicorn 0.54.0、python-multipart 0.0.33、PyJWT 2.15.1、pwdlib 0.3.1(argon2-cffi 25.1.0)
  • Docker 29.7.2(Windows 11 の Docker Desktop。Linuxコンテナの設定)
  • APIを呼んだシェル: Git Bash(Windows)の bash と curl 8.14.1。Windowsの章だけ、PowerShell 7.6.5 と Windows PowerShell 5.1
  • 確認日: 2026年11月5日

この記事は、MacとWindowsの両方の読者を対象にしています。APIはDockerのコンテナで動かすので、MacでもWindowsでもDockerがあれば同じように動かせます。違いが出るのは、自分のPCのシェルからAPIを呼ぶところです(「MacとWindowsで違う点」の章)。Macのターミナルでは確認していません。

この記事のコマンドは、Claude(AI)が上から順に実行して確認しました。Windowsの章は、同じイメージを使って別に確かめています。出力は、ビルドの表示、docker run -d が表示するコンテナID、エラーの詳しい表示など、一部を省略しています。

準備

空のフォルダに、main.py と次の3つのファイルを置きます。

requirements.txt(バージョンは確認したものに固定しています)

fastapi==0.162.0
uvicorn==0.54.0
python-multipart==0.0.33
pyjwt==2.15.1
pwdlib[argon2]==0.3.1

python-multipart は、/token がフォーム形式でユーザー名とパスワードを受け取るために必要です。

Dockerfile

FROM python:3.15.2-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py tamper.py ./
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

tamper.py(後で改ざんを試すための確認用のスクリプト。APIには使いません)

# 確認用: トークンの中身を表示し、有効期限だけを書き換えたトークンを作る(署名はそのまま)
import base64
import json
import sys

header, payload, signature = sys.argv[1].split(".")
data = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
print("payload:", data)

data["exp"] = 4102444800  # 2100-01-01
forged = base64.urlsafe_b64encode(json.dumps(data, separators=(",", ":")).encode()).rstrip(b"=").decode()
print("forged:", f"{header}.{forged}.{signature}")

フォルダの中で、イメージを作ります(ビルドの出力は省略)。

$ ls
Dockerfile
main.py
requirements.txt
tamper.py
$ docker build -t fastapi-jwt-demo .

秘密鍵を作って起動する

トークンの署名に使う秘密鍵を作ります。公式チュートリアルでは openssl rand -hex 32 を使っていますが、ここではOSによらず使えるように、イメージの中のPythonで作ります。表示された値は確認用の例です。自分で作った値を使い、コードやリポジトリには書かないでください。

$ docker run --rm fastapi-jwt-demo python -c "import secrets; print(secrets.token_hex(32))"
7a99d873143c5fae42e4d4082c2174495d1159c5a2bbe992e5f1fa3e8c01ac18

秘密鍵を環境変数 SECRET_KEY で渡して起動します。-p 127.0.0.1:18100:8000 のようにIPアドレスを付けると、自分のPCからだけ接続を受け付けます。-p 18100:8000 と書くと、ホストのすべてのアドレスで公開されます(Dockerの公式ドキュメント)。確認用のユーザーでログインできるAPIなので、ここでは自分のPCに限定しました。

起動には数秒かかります。docker logs で Application startup complete. が出たのを確かめてから、次に進みます(この記事では、以降のコンテナでも同じように確かめています)。

$ docker run -d --name fastapi-jwt -p 127.0.0.1:18100:8000 -e SECRET_KEY=7a99d873143c5fae42e4d4082c2174495d1159c5a2bbe992e5f1fa3e8c01ac18 fastapi-jwt-demo
$ docker logs fastapi-jwt
INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

ログインしてトークンを受け取る

/token に、フォーム形式でユーザー名とパスワードを送ります。

$ curl -s -X POST http://127.0.0.1:18100/token -d "username=alice&password=secret"
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6MTc5Mzg4MDY3Nn0.Geq_EkvRUZKMrxa4eOiiIjqS7NBnw-FcW68HgVbxVVA","token_type":"bearer"}

以降のコマンドのために、access_token の値を変数 TOKEN に入れておきます(bash と zsh の書き方)。

$ TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6MTc5Mzg4MDY3Nn0.Geq_EkvRUZKMrxa4eOiiIjqS7NBnw-FcW68HgVbxVVA

トークンを付けて呼ぶ

$ curl -s http://127.0.0.1:18100/users/me -H "Authorization: Bearer $TOKEN"
{"username":"alice"}

エラーになる場合

ここからは、-i でレスポンスのヘッダーも表示しています。

パスワードの間違いと、存在しないユーザー

どちらも同じ401とメッセージになりました。どちらが間違っているかを返さないので、ユーザー名が存在するかどうかを応答から探られにくくなります。

$ curl -s -i -X POST http://127.0.0.1:18100/token -d "username=alice&password=wrong"
HTTP/1.1 401 Unauthorized
date: Thu, 05 Nov 2026 11:41:16 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 43
content-type: application/json

{"detail":"Incorrect username or password"}
$ curl -s -i -X POST http://127.0.0.1:18100/token -d "username=nobody&password=secret"
HTTP/1.1 401 Unauthorized
date: Thu, 05 Nov 2026 11:41:16 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 43
content-type: application/json

{"detail":"Incorrect username or password"}

Authorization ヘッダーがない、または Bearer を付け忘れた

ヘッダーがないときも、Bearer を付けずにトークンだけを送ったときも、トークンの検証の前に Not authenticated になりました。

$ curl -s -i http://127.0.0.1:18100/users/me
HTTP/1.1 401 Unauthorized
date: Thu, 05 Nov 2026 11:41:16 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 30
content-type: application/json

{"detail":"Not authenticated"}
$ curl -s -i http://127.0.0.1:18100/users/me -H "Authorization: $TOKEN"
HTTP/1.1 401 Unauthorized
date: Thu, 05 Nov 2026 11:41:16 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 30
content-type: application/json

{"detail":"Not authenticated"}

このトークンの中身は誰でも読める。改ざんすると署名で弾かれる

この記事で作る署名付きのJWTは、ペイロード(中身)がBase64URLで符号化されているだけで、暗号化されていません。tamper.py で中身を表示すると、ユーザー名と有効期限がそのまま読めました。パスワードなど秘密の情報は、トークンに入れないようにします。

続けて、有効期限だけを2100年に書き換えたトークンを作り、元の署名のまま送ると、401になりました。

$ docker exec fastapi-jwt python tamper.py $TOKEN
payload: {'sub': 'alice', 'exp': 1793880676}
forged: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6NDEwMjQ0NDgwMH0.Geq_EkvRUZKMrxa4eOiiIjqS7NBnw-FcW68HgVbxVVA
$ FORGED=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6NDEwMjQ0NDgwMH0.Geq_EkvRUZKMrxa4eOiiIjqS7NBnw-FcW68HgVbxVVA
$ curl -s -i http://127.0.0.1:18100/users/me -H "Authorization: Bearer $FORGED"
HTTP/1.1 401 Unauthorized
date: Thu, 05 Nov 2026 11:41:17 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 43
content-type: application/json

{"detail":"Could not validate credentials"}

有効期限が切れた

期限を1分にしたサーバーを、ポート18101で別に起動して試しました。受け取った直後は通り、65秒待つと401になりました。

$ docker run -d --name fastapi-jwt-short -p 127.0.0.1:18101:8000 -e SECRET_KEY=7a99d873143c5fae42e4d4082c2174495d1159c5a2bbe992e5f1fa3e8c01ac18 -e ACCESS_TOKEN_EXPIRE_MINUTES=1 fastapi-jwt-demo
$ docker logs fastapi-jwt-short
INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
$ curl -s -X POST http://127.0.0.1:18101/token -d "username=alice&password=secret"
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6MTc5Mzg3ODk0MH0.bCH4h8yQm5ZmPGW23YaoNm96JHK4f4uCVbNJzA59WRQ","token_type":"bearer"}
$ TOKEN2=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6MTc5Mzg3ODk0MH0.bCH4h8yQm5ZmPGW23YaoNm96JHK4f4uCVbNJzA59WRQ
$ curl -s http://127.0.0.1:18101/users/me -H "Authorization: Bearer $TOKEN2"
{"username":"alice"}
$ sleep 65
$ curl -s -i http://127.0.0.1:18101/users/me -H "Authorization: Bearer $TOKEN2"
HTTP/1.1 401 Unauthorized
date: Thu, 05 Nov 2026 11:42:24 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 43
content-type: application/json

{"detail":"Could not validate credentials"}

期限切れも改ざんも、同じ Could not validate credentials になります。このコードは PyJWT の InvalidTokenError をまとめて捕まえていて、期限切れの ExpiredSignatureError もその一種だからです(PyJWTのドキュメント)。期限切れだけ別のメッセージにしたいときは、ExpiredSignatureError を先に捕まえます。この書き分けは試していません。

別の秘密鍵のサーバーでは、トークンが使えない

ポート18101のサーバーを、別の秘密鍵で起動し直しました。ポート18100のサーバーで受け取った TOKEN は、まだ期限内でも、このサーバーでは401になりました。運用中のサーバーの秘密鍵を入れ替えると、そのサーバーは古い鍵で発行したトークンを受け付けなくなり、利用者はログインし直すことになります。

$ docker rm -f fastapi-jwt-short
fastapi-jwt-short
$ docker run --rm fastapi-jwt-demo python -c "import secrets; print(secrets.token_hex(32))"
4427356c39b744ec10c5618a8ba8e71affacd2d3feea2c46738461fa7efdd3ec
$ docker run -d --name fastapi-jwt-short -p 127.0.0.1:18101:8000 -e SECRET_KEY=4427356c39b744ec10c5618a8ba8e71affacd2d3feea2c46738461fa7efdd3ec fastapi-jwt-demo
$ docker logs fastapi-jwt-short
INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
$ curl -s -i http://127.0.0.1:18101/users/me -H "Authorization: Bearer $TOKEN"
HTTP/1.1 401 Unauthorized
date: Thu, 05 Nov 2026 11:42:29 GMT
server: uvicorn
www-authenticate: Bearer
content-length: 43
content-type: application/json

{"detail":"Could not validate credentials"}

確認が終わったら、コンテナを消します。

$ docker rm -f fastapi-jwt fastapi-jwt-short
fastapi-jwt
fastapi-jwt-short

MacとWindowsで違う点

docker のコマンドは、MacのターミナルでもWindowsのPowerShellでも同じです。違うのは、APIを呼ぶ curl と、変数の書き方です。

項目Mac(ターミナル)Windows(PowerShell)
APIを呼ぶcurlcurl.exe
変数に入れるTOKEN=eyJ...$TOKEN = "eyJ..."
変数を使う"Authorization: Bearer $TOKEN""Authorization: Bearer $TOKEN"

Macの欄は、この記事の本文のbashと同じ書き方で、zshの公式ドキュメントの変数(パラメーター)の書き方とも同じです。Macのターミナルでは確認していません。Windowsの欄は、次の章で確かめました(変数に入れる行は、$TOKEN = $res.access_token の形で確かめています)。

Windowsで確かめた準備

Windows 11 のPowerShell 7.6.5 で、ポート18102にもう1つコンテナを起動しました。秘密鍵は変数に入れて渡しています。

PS> $secret = docker run --rm fastapi-jwt-demo python -c "import secrets; print(secrets.token_hex(32))"
PS> docker run -d --name fastapi-jwt-win -p 127.0.0.1:18102:8000 -e SECRET_KEY=$secret fastapi-jwt-demo
PS> docker logs fastapi-jwt-win
INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

このコンテナに対して、PowerShell 7.6.5 と Windows PowerShell 5.1 から同じ行を実行しました。

Windows PowerShell 5.1 の curl は別のコマンド

Windows PowerShell 5.1 では、curl は Invoke-WebRequest の別名で、curl のオプションを渡すとエラーになりました(エラーの表示は先頭の行だけを載せています)。

PS> (Get-Command curl).CommandType
Alias
PS> curl -X POST http://127.0.0.1:18102/token -d "username=alice&password=secret"
Invoke-WebRequest : A parameter cannot be found that matches parameter name 'X'.

PowerShell 7.6.5 では、curl はWindowsに入っている C:\WINDOWS\system32\curl.exe を指していて、そのまま動きました。どちらのPowerShellでも確実に curl を使うには、curl.exe と書きます。次は Windows PowerShell 5.1 の結果で、PowerShell 7.6.5 でも同じように動きました。

PS> curl.exe -s -X POST http://127.0.0.1:18102/token -d "username=alice&password=secret"
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImV4cCI6MTc5Mzg4MDc2NX0.mfbwOPDavo-lMjSxA1ATO2N_-gylwIBsD9R-5pzaWxk","token_type":"bearer"}

PowerShellらしく書くなら Invoke-RestMethod

Invoke-RestMethod は、JSONをオブジェクトにして返すので、トークンを取り出しやすくなります。次の行は、PowerShell 7.6.5 と Windows PowerShell 5.1 の両方で同じ結果になりました。

PS> $res = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:18102/token -Body @{ username = "alice"; password = "secret" }
PS> $res.token_type
bearer
PS> Invoke-RestMethod -Uri http://127.0.0.1:18102/users/me -Headers @{ Authorization = "Bearer $($res.access_token)" }

username
--------
alice
PS> $TOKEN = $res.access_token
PS> curl.exe -s http://127.0.0.1:18102/users/me -H "Authorization: Bearer $TOKEN"
{"username":"alice"}

401などのエラーのときは、Invoke-RestMethod は例外になり、エラーの表示の中にレスポンスの本文が入りました。表示の形は、PowerShell 7.6.5 と 5.1 で違いました(次は 5.1 の表示の先頭の行)。

PS> Invoke-RestMethod -Method Post -Uri http://127.0.0.1:18102/token -Body @{ username = "alice"; password = "wrong" }
Invoke-RestMethod : {"detail":"Incorrect username or password"}

確認が終わったら、コンテナを消します。

PS> docker rm -f fastapi-jwt-win
fastapi-jwt-win

参考

スポンサーリンク
FastAPIPython
スポンサーリンク
シェアする
hayoをフォローする

コメント

タイトルとURLをコピーしました