0Pricing
FastAPI Backend Development Bootcamp · レッスン

リフレッシュトークンとトークンローテーション

短命のアクセストークンとローテーションするリフレッシュトークン、サーバー側の失効処理を設計し、トークン窃取の影響を抑えます。

「リフレッシュトークンとトークンローテーション」はCoddyKit上の無料FastAPI Backend Development Bootcampレッスンです。 これはレッスン3/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはFastAPI Backend Development Bootcamp学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 FastAPI Backend Development Bootcampコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Why Two Tokens?

A single long-lived JWT access token is convenient but dangerous: if it leaks, an attacker can use it until it expires. Since JWTs are stateless, you cannot easily revoke one mid-flight.

The standard OAuth2 answer is to split responsibilities into two tokens:

  • Access token — short-lived (5-15 min), sent on every request, verified by signature only (no DB hit).
  • Refresh token — long-lived (days/weeks), used only to obtain a new access token, and tracked server-side so it can be revoked.

This way a stolen access token is useless within minutes, while users still stay logged in for a long time.

Anatomy of the Token Pair

The login endpoint returns both tokens. The client keeps the access token in memory and the refresh token somewhere more protected (e.g. an HttpOnly cookie).

Notice the very different expiry windows. The access token is intentionally short so a leak has a tiny blast radius.

from datetime import datetime, timedelta, timezone

ACCESS_TOKEN_TTL = timedelta(minutes=15)
REFRESH_TOKEN_TTL = timedelta(days=7)

def expiry(ttl: timedelta) -> str:
    return (datetime.now(timezone.utc) + ttl).isoformat()

login_response = {
    "access_token": "<jwt>",
    "access_expires": expiry(ACCESS_TOKEN_TTL),
    "refresh_token": "<opaque-or-jwt>",
    "refresh_expires": expiry(REFRESH_TOKEN_TTL),
    "token_type": "bearer",
}

for k, v in login_response.items():
    print(f"{k}: {v}")

Signing an Access Token

Access tokens are JWTs signed with your secret. They carry a sub (user id), an exp claim, and a type claim so the server can refuse a refresh token where an access token is expected.

This snippet uses python-jose, the library most FastAPI tutorials rely on. It depends on an external package, so it is not standalone-runnable here.

from datetime import datetime, timedelta, timezone
from jose import jwt

SECRET = "change-me"
ALGO = "HS256"

def create_access_token(user_id: str) -> str:
    now = datetime.now(timezone.utc)
    payload = {
        "sub": user_id,
        "type": "access",
        "iat": now,
        "exp": now + timedelta(minutes=15),
    }
    return jwt.encode(payload, SECRET, algorithm=ALGO)

The Refresh Token Needs State

An access token is verified by signature alone — no database needed. A refresh token is different: to support revocation and rotation, the server must remember it.

The trick: never store the raw refresh token. Store only a hash of it, just like a password. If your DB leaks, the stored hashes cannot be replayed.

  • Generate a high-entropy random string as the token.
  • Hash it (SHA-256) and persist the hash, user id, expiry, and a revoked flag.
  • On refresh, hash the incoming token and look it up.
import hashlib, secrets

def new_refresh_token() -> tuple[str, str]:
    raw = secrets.token_urlsafe(48)          # give this to the client
    token_hash = hashlib.sha256(raw.encode()).hexdigest()  # store this
    return raw, token_hash

raw, stored = new_refresh_token()
print("client receives:", raw[:16], "...")
print("db stores hash :", stored[:16], "...")
print("lookup matches :", hashlib.sha256(raw.encode()).hexdigest() == stored)

What Is Token Rotation?

Rotation means every time a refresh token is used, it is consumed and replaced by a brand-new one. A refresh token is therefore single-use.

Sequence on each refresh:

  • Validate the presented refresh token (exists, not revoked, not expired).
  • Mark it revoked/used.
  • Issue a fresh access token and a fresh refresh token.
  • Return the new pair to the client.

Without rotation, a stolen refresh token works for its entire lifetime. With rotation, using it changes it — which is exactly what lets us detect theft.

Modeling the Stored Token

Here is a minimal in-memory model of the refresh-token store so you can see the moving parts before wiring a real database. Each record knows its owner, expiry, and whether it has been used or revoked.

In production this maps to a SQL table (with the hash as the key) or a Redis entry with a TTL.

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone

@dataclass
class RefreshRecord:
    token_hash: str
    user_id: str
    expires_at: datetime
    revoked: bool = False

    def is_valid(self, now: datetime) -> bool:
        return not self.revoked and now < self.expires_at

now = datetime.now(timezone.utc)
rec = RefreshRecord("abc123", "user-7", now + timedelta(days=7))
print("valid now      :", rec.is_valid(now))
rec.revoked = True
print("valid revoked  :", rec.is_valid(now))

The Rotation Logic

This is the heart of the lesson: a pure function that takes a presented refresh token, validates it, revokes it, and mints a replacement. No framework involved — just the algorithm.

Run it: the first refresh succeeds and returns a new token; reusing the old token afterward fails because it was rotated out.

import hashlib, secrets
from datetime import datetime, timedelta, timezone

store = {}  # token_hash -> {user_id, exp, revoked}

def _hash(raw): return hashlib.sha256(raw.encode()).hexdigest()

def issue(user_id):
    raw = secrets.token_urlsafe(32)
    store[_hash(raw)] = {
        "user_id": user_id,
        "exp": datetime.now(timezone.utc) + timedelta(days=7),
        "revoked": False,
    }
    return raw

def rotate(raw):
    rec = store.get(_hash(raw))
    now = datetime.now(timezone.utc)
    if not rec or rec["revoked"] or now >= rec["exp"]:
        raise ValueError("invalid refresh token")
    rec["revoked"] = True            # consume the old one
    return issue(rec["user_id"])     # mint a fresh one

old = issue("user-7")
new = rotate(old)
print("rotated to new token:", new[:12], "...")
try:
    rotate(old)
except ValueError as e:
    print("reuse of old token blocked:", e)

Detecting Token Theft via Reuse

Rotation gives a powerful security signal. If a refresh token that was already used shows up again, there are only two explanations:

  • The legitimate client never received the new token (rare), or
  • An attacker stole the old token and is replaying it.

Because you cannot tell which, the safe response is to treat reuse as a breach of the whole token family: revoke every refresh token for that user (or that session lineage) and force re-login.

This is called automatic reuse detection and is recommended by the OAuth2 Security Best Current Practice (RFC 9700).

Reuse Detection in Code

To detect reuse we keep a per-user family of tokens. A normal rotation revokes one token and adds its successor. If a token marked used=True is presented again, we nuke the entire family.

Run it to see a stolen-token replay trigger a full family wipe.

import secrets

family = {}  # token -> {"used": bool}

def issue():
    t = secrets.token_urlsafe(16)
    family[t] = {"used": False}
    return t

def rotate(t):
    rec = family.get(t)
    if rec is None:
        raise ValueError("unknown token")
    if rec["used"]:
        family.clear()  # reuse detected -> revoke whole family
        raise ValueError("REUSE DETECTED: all sessions revoked")
    rec["used"] = True
    return issue()

t1 = issue()
t2 = rotate(t1)      # normal rotation
print("rotation ok, new token issued")
try:
    rotate(t1)       # attacker replays the stolen old token
except ValueError as e:
    print(e)
print("tokens remaining:", len(family))

The FastAPI Refresh Endpoint

Now the FastAPI wiring. The refresh token arrives in the request body (or an HttpOnly cookie). The endpoint rotates it and returns a fresh pair.

Key choices visible here:

  • Reject anything that is not a refresh token type.
  • Return 401 on any validation failure — never leak why.
  • Always issue a new refresh token alongside the access token.

This depends on FastAPI and your store, so it is illustrative rather than standalone-runnable.

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel

router = APIRouter()

class RefreshIn(BaseModel):
    refresh_token: str

class TokenPair(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"

@router.post("/auth/refresh", response_model=TokenPair)
async def refresh(body: RefreshIn):
    try:
        user_id = validate_and_consume(body.refresh_token)  # raises on reuse/expiry
    except ValueError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid refresh token",
        )
    return TokenPair(
        access_token=create_access_token(user_id),
        refresh_token=create_refresh_token(user_id),
    )

Storing and Revoking Server-Side

Server-side state is what makes revocation possible. A logout, a password change, or a detected breach should immediately invalidate refresh tokens.

Practical guidance:

  • Where: SQL table for durability, or Redis with a TTL equal to the token lifetime for speed and automatic expiry.
  • What to store: the SHA-256 hash, user id, expiry, a revoked flag, and optionally a family_id for reuse detection.
  • Logout: mark the presented token (and optionally its whole family) revoked.
  • Global logout: revoke all of a user's tokens — e.g. after a password reset.

Access tokens stay stateless and simply expire on their own within minutes, which is why short TTLs matter so much.

def logout(token_hash: str, conn) -> None:
    conn.execute(
        "UPDATE refresh_tokens SET revoked = TRUE WHERE token_hash = %s",
        (token_hash,),
    )

def revoke_all_for_user(user_id: str, conn) -> None:
    conn.execute(
        "UPDATE refresh_tokens SET revoked = TRUE WHERE user_id = %s",
        (user_id,),
    )

Quick Check

Test your understanding of the core rotation decision.

Recap

You now know how to build secure session management with rotating refresh tokens:

  • Two tokens: short-lived stateless access tokens (5-15 min) plus long-lived refresh tokens tracked server-side.
  • Hash, never store raw: persist only the SHA-256 of the refresh token, like a password.
  • Rotation: every refresh consumes the old token (single-use) and issues a fresh pair.
  • Reuse detection: a replayed used token means likely theft — revoke the whole family and force re-login (RFC 9700).
  • Revocation: server-side state (SQL or Redis-with-TTL) lets logout, password change, and breach response invalidate tokens instantly.

The result: a stolen access token dies in minutes, a stolen refresh token is detected on first replay, and users still enjoy long-lived sessions.

よくある質問

「リフレッシュトークンとトークンローテーション」レッスンは無料ですか？

はい。「リフレッシュトークンとトークンローテーション」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、FastAPI Backend Development Bootcampコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 FastAPI Backend Development Bootcampコースには全4レッスンが含まれています。

「リフレッシュトークンとトークンローテーション」で何を学びますか？

短命のアクセストークンとローテーションするリフレッシュトークン、サーバー側の失効処理を設計し、トークン窃取の影響を抑えます。 ブラウザで直接実行するハンズオンコードでFastAPI Backend Development Bootcampを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

FastAPI Backend Development Bootcampを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのFastAPI Backend Development Bootcampは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン3/4です。

「リフレッシュトークンとトークンローテーション」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このFastAPI Backend Development Bootcampレッスンでコードを書いて実行できますか？

はい。すべてのFastAPI Backend Development Bootcampレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. OAuth2パスワードフローとトークン発行
  2. python-joseによるJWTの署名と検証
  3. リフレッシュトークンとトークンローテーション
  4. スコープベースの認可とロールガード
← FastAPI Backend Development Bootcampに戻る