2025年1月1日

認証ガイド

Roxは、モダンなパスキー（WebAuthn）と従来のパスワードの両方をサポートする、安全で柔軟な認証システムを提供します。

概要

Roxの認証はバックエンドAPIによって処理され、フロントエンドクライアントにシームレスに統合されています。以下のセキュリティベストプラクティスを優先しています：

  • JWT (JSON Web Tokens): ステートレスなセッション管理
  • Bcrypt: 安全なパスワードハッシュ化
  • WebAuthn: パスワードレス認証（パスキー）
  • レート制限: ブルートフォース攻撃の防止

認証方法

1. パスキー（推奨）

パスキーは最高レベルのセキュリティと利便性を提供します。ユーザーはデバイスの生体認証（FaceID、TouchID）やハードウェアセキュリティキーを使用してサインインできます。

登録フロー

  1. ユーザーがユーザー名を入力
  2. サーバーがチャレンジを生成
  3. ブラウザがユーザーに生体認証/デバイス認証を要求
  4. 公開鍵がサーバーに送信され保存される

ログインフロー

  1. ユーザーがユーザー名を入力
  2. サーバーがチャレンジを送信
  3. ブラウザが秘密鍵でチャレンジに署名
  4. サーバーが署名を検証し、JWTを発行

2. パスワード認証

従来の方法を好むユーザーや、互換性のあるデバイスを持っていないユーザーのために、Roxはパスワードベースの認証もサポートしています。

  • 要件: 最低8文字
  • 保存: ソルト付きBcryptハッシュ
  • セキュリティ: ログイン試行のレート制限

クライアント実装

Roxフロントエンド（Waku）は、専用の auth ストア（Jotai atom）を使用して認証状態を管理します。

// 例: ログイン状態の確認
const [user] = useAtom(currentUserAtom);

if (user) {
  console.log('ログイン中:', user.username);
}

APIエンドポイント

登録

  • POST /api/signup - 新規アカウント作成
  • POST /api/auth/register/options - WebAuthn登録オプション取得
  • POST /api/auth/register/verify - WebAuthn登録検証

ログイン

  • POST /api/signin - パスワードでログイン
  • POST /api/auth/login/options - WebAuthnログインオプション取得
  • POST /api/auth/login/verify - WebAuthnログイン検証

セッション

  • POST /api/signout - 現在のセッションを無効化
  • POST /api/i - 現在のユーザープロフィール取得

セキュリティ設定

管理者は .env で認証設定を構成できます：

# JWT設定
JWT_SECRET=your-secure-secret
JWT_EXPIRES_IN=7d

# レート制限
RATE_LIMIT_LOGIN_WINDOW=15m
RATE_LIMIT_LOGIN_MAX=5

トラブルシューティング

"認証に失敗しました"

  • ブラウザでCookieが有効になっているか確認してください。
  • システム時計が同期されていることを確認してください（TOTP/WebAuthnのため）。
  • バックエンドとフロントエンド間で JWT_SECRET が一致しているか確認してください（分離している場合）。

パスキーの問題

  • デバイスがWebAuthnをサポートしているか確認してください。
  • 別のブラウザやデバイスを試してください。
  • ドメインがHTTPSで提供されているか確認してください（WebAuthnに必須）。