/// tip

In the next chapter, you will see a real secure implementation, with password hashing and <abbr title="JSON Web Tokens">JWT</abbr> tokens.

But for now, let's focus on the specific details we need.

///

{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}

/// tip

  - 🤖 自动生成的前端客户端。
  - 🧪 [Playwright](https://playwright.dev) 用于端到端测试。
  - 🦇 支持暗黑模式。
- 🐋 [Docker Compose](https://www.docker.com) 用于开发与生产。
- 🔒 默认启用安全的密码哈希。
- 🔑 JWT（JSON Web Token）认证。
- 📫 基于邮箱的密码找回。
- ✅ 使用 [Pytest](https://pytest.org) 进行测试。
- 📞 [Traefik](https://traefik.io) 用作反向代理/负载均衡。
- 🚢 使用 Docker Compose 的部署指南，包括如何设置前端 Traefik 代理以自动处理 HTTPS 证书。

All the security schemes defined in OpenAPI, including:

* HTTP Basic.
* **OAuth2** (also with **JWT tokens**). Check the tutorial on [OAuth2 with JWT](tutorial/security/oauth2-jwt.md).
* API keys in:
    * Headers.
    * Query parameters.
    * Cookies, etc.

Plus all the security features from Starlette (including **session cookies**).

如果你想保护你的 API，有很多更好的措施，例如：

- 确保为请求体和响应定义完善的 Pydantic 模型。
- 使用依赖配置所需的权限和角色。
- 绝不要存储明文密码，只存储密码哈希。
- 实现并使用成熟的密码学工具，比如 pwdlib 和 JWT 令牌等。
- 在需要的地方使用 OAuth2 作用域添加更细粒度的权限控制。
- ...等。

尽管如此，你可能确实有非常特定的用例，需要在某些环境（例如生产环境）禁用 API 文档，或根据环境变量的配置来决定。

## 基于设置和环境变量的条件式 OpenAPI { #conditional-openapi-from-settings-and-env-vars }

github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
github.com/golang-jwt/jwt/v4 v4.5.2 h1:YtQM7lnr8iZ+j5q71MGKkNw9Mn7AjHM68uc9g5fXeUI=
github.com/golang-jwt/jwt/v4 v4.5.2/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
github.com/golang-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=

  - 🤖 自動生成されたフロントエンドクライアント。
  - 🧪 End-to-Endテスト向けの [Playwright](https://playwright.dev)。
  - 🦇 ダークモードのサポート。
- 🐋 開発および本番向けの [Docker Compose](https://www.docker.com)。
- 🔒 デフォルトでの安全なパスワードハッシュ化。
- 🔑 JWT（JSON Web Token）認証。
- 📫 メールベースのパスワードリカバリ。
- ✅ [Pytest](https://pytest.org) によるテスト。
- 📞 リバースプロキシ / ロードバランサとしての [Traefik](https://traefik.io)。
- 🚢 Docker Composeを使用したデプロイ手順（自動HTTPS証明書を処理するフロントエンドTraefikプロキシのセットアップ方法を含む）。

如果你想保護 API，有許多更好的作法，例如：

- 確保針對請求本文與回應，具備定義良好的 Pydantic 模型。
- 透過依賴設定所需的權限與角色。
- 切勿儲存明文密碼，只儲存密碼雜湊。
- 實作並使用成熟且廣為人知的密碼學工具，例如 pwdlib 與 JWT 權杖等。
- 視需要以 OAuth2 scopes 新增更細緻的權限控管。
- ...等。

儘管如此，在某些特定情境下，你可能確實需要在某些環境（例如正式環境）停用 API 文件，或依據環境變數的設定來決定是否啟用。

## 透過設定與環境變數的條件式 OpenAPI { #conditional-openapi-from-settings-and-env-vars }

所有的校验都由完善且强大的 **Pydantic** 处理。

### 安全性及身份验证 { #security-and-authentication }

集成了安全性和身份认证。杜绝数据库或者数据模型的渗透风险。

OpenAPI 中定义的安全模式，包括：

* HTTP 基本认证。
* **OAuth2**（也使用 **JWT tokens**）。在 [使用 JWT 的 OAuth2](tutorial/security/oauth2-jwt.md) 查看教程。
* API 密钥，在:
    * 请求头。
    * 查询参数。
    * Cookies，等等。

加上来自 Starlette（包括 **session cookie**）的所有安全特性。

所有的这些都是可复用的工具和组件，可以轻松与你的系统，数据仓库，关系型以及 NoSQL 数据库等等集成。

而且它還應該有一個 `access_token`，其值為包含我們存取權杖的字串。

在這個簡單示例中，我們會不安全地直接回傳相同的 `username` 當作 token。

/// tip

下一章你會看到真正安全的實作，包含密碼雜湊與 <abbr title="JSON Web Tokens - JSON 網頁權杖">JWT</abbr> tokens。

但現在先把注意力放在我們需要的這些細節上。

///

{* ../../docs_src/security/tutorial003_an_py310.py hl[87] *}

/// tip

依照規範，你應該回傳一個包含 `access_token` 與 `token_type` 的 JSON，就像這個範例。

所有的驗證都由完善且強大的 **Pydantic** 處理。

### 安全性及身份驗證 { #security-and-authentication }

FastAPI 已經整合了安全性和身份驗證的功能，但不會強制與特定的資料庫或資料模型進行綁定。

OpenAPI 中定義的安全模式，包括：

* HTTP 基本認證。
* **OAuth2**（也使用 **JWT tokens**）。在 [OAuth2 with JWT](tutorial/security/oauth2-jwt.md) 查看教學。
* API 密鑰，在：
    * 標頭（Header）
    * 查詢參數
    * Cookies，等等。

加上來自 Starlette（包括 **session cookie**）的所有安全特性。