litestar-authentication

認証

実行ワークフロー

1. まず、クライアントと信頼境界に基づいて、セッション、JWT ヘッダー、JWT Cookie、OAuth2 パスワードベアラー、カスタムミドルウェアのいずれかの認証方式を選択します。
2. on_app_init またはミドルウェアを使って、アプリケーションスコープで認証を一度だけ設定します。
3. ログイン、スキーマ、ヘルスチェック、その他の公開ルートについて、除外ルールを明示的に設定します。
4. 認証が確立された後に限り、request.user と request.auth を使用します。
5. 認可チェックには別途ガードを適用します。
6. 認証情報がない場合や無効な場合の動作を、例外処理の方針に沿って一貫させます。

基本ルール

• 認証はリクエストの解析や認可とは分離します。
• 可能であれば、認証固有のビジネスロジックに進む前に、リクエストの解析で入力フィールドを検証します。
• カスタムミドルウェアより、組み込みのセキュリティバックエンドを優先します。
• ID 情報の取得元が組み込みバックエンドに適合しない場合に限り、カスタムミドルウェアを使用します。
• request.user と request.auth は、解析の代替手段ではなく、認証済みコンテキストとして扱います。
• 除外ルールは限定的にし、レビュー可能な状態に保ちます。
• プロジェクトで別の対応が文書化されていない限り、ID 認証の失敗は 401 の動作に統一します。

選択ガイド

• サーバー管理のセッションを使用するブラウザー中心のアプリケーションには、SessionAuth を使用します。
• トークンをヘッダーに含める API クライアントには、JWTAuth を使用します。
• トークンを Cookie に保存することを意図したブラウザーフローには、JWTCookieAuth を使用します。
• パスワードフローでのトークン発行のセマンティクスが必要な場合は、OAuth2PasswordBearerAuth を使用します。
• 認証情報の取得元や検証ロジックがカスタムの場合は、AbstractAuthenticationMiddleware を使用します。
• ID 認証の設定を超えて、認可ポリシー、シークレット、多層防御への対応が必要な場合は、litestar-security を使用します。

参照ファイル

必要なセクションのみを読みます。

• カスタムミドルウェア、組み込みバックエンド、リクエストの認証コンテキスト、除外ルール、ログインパターンについては、references/auth-patterns.md を読みます。

推奨されるデフォルト設定

• 認証ミドルウェアまたはバックエンドの登録は、アプリケーションスコープに設定します。
• 明示的に公開するルートのみを除外します。
• 認証処理の実行後に、型付きの Request または ASGIConnection を通じて認証済みコンテキストにアクセスします。
• トークンの発行とログアウトのフローは明示的にし、テスト可能な状態に保ちます。
• 401 / 403 のレスポンス形式は、litestar-exception-handling に委ねます。

アンチパターン

• すべてのルートハンドラーで認証ヘッダーを手動で解析する。
• 認可ポリシーを認証ミドルウェアに混在させる。
• 認証から除外されたルートで request.user が利用可能だと想定する。
• 広範なパス除外を使用し、意図せず公開範囲を広げる。
• ローカルの例以外でシークレットやサンプルトークンをハードコードする。

検証チェックリスト

• 保護されたエンドポイントが、認証情報の欠如や無効な認証情報を拒否することを確認します。
• 公開ルートが、明示的に除外された場合にのみ公開されることを確認します。
• 認証済みルートで、request.user と request.auth が期待される型になっていることを確認します。
• ログインとログアウトのフローが、意図したトークンまたはセッションの動作になることを確認します。
• ID 認証の失敗が、例外処理の契約に沿っていることを確認します。
• テストで認証済みと未認証の両方の経路をカバーしていることを確認します。

スキル間の引き継ぎ

• ID 認証に固有ではない、ヘッダー、Cookie、本文の解析には litestar-requests を使用します。
• 認可、シークレットの適切な取り扱い、より広範なセキュリティ対策には litestar-security を使用します。
• 401 と 403 の契約を標準化するには litestar-exception-handling を使用します。
• 認証境界、除外ルール、トークンフローのテストには litestar-testing を使用します。

Litestar のリファレンス

• https://docs.litestar.dev/latest/usage/security/abstract-authentication-middleware.html
• https://docs.litestar.dev/latest/usage/security/security-backends.html
• https://docs.litestar.dev/latest/usage/security/jwt.html
• https://docs.litestar.dev/latest/usage/security/excluding-and-including-endpoints.html