-# 使用（哈希）密码和 JWT Bearer 令牌的 OAuth2
+# OAuth2 实现密码哈希与 Bearer JWT 令牌验证
-既然我们已经有了所有的安全流程，就让我们来使用 <abbr title="JSON Web Tokens">JWT</abbr> 令牌和安全哈希密码让应用程序真正地安全吧。
+至此，我们已经编写了所有安全流，本章学习如何使用 <abbr title="JSON Web Tokens">JWT</abbr> 令牌（Token）和安全密码哈希（Hash）实现真正的安全机制。
-你可以在应用程序中真正地使用这些代码，在数据库中保存密码哈希值，等等。
+本章的示例代码真正实现了在应用的数据库中保存哈希密码等功能。
-æ\88\91们å°\86ä»\8eä¸\8aä¸\80ç« ç»\93æ\9d\9fç\9a\84ä½\8dç½®å¼\80å§\8bï¼\8cç\84¶å\90\8e对示ä¾\8bè¿\9bè¡\8cæ\89©å\85\85。
+æ\8e¥ä¸\8bæ\9d¥ï¼\8cæ\88\91们紧æ\8e¥ä¸\8aä¸\80ç« ï¼\8c继ç»å®\8cå\96\84å®\89å\85¨æ\9cºå\88¶。
-## 关于 JWT
+## JWT 简介
-JWT 表示 「JSON Web Tokens」。
+JWT 即**JSON 网络令牌**（JSON Web Tokens）。
-它是一个将 JSON 对象编码为密集且没有空格的长字符串的标准。字符串看起来像这样：
+JWT 是一种将 JSON 对象编码为没有空格，且难以理解的长字符串的标准。JWT 的内容如下所示：
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```
-它没有被加密，因此任何人都可以从字符串内容中还原数据。
+JWT 字符串没有加密，任何人都能用它恢复原始信息。
-但它经过了签名。因此，当你收到一个由你发出的令牌时，可以校验令牌是否真的由你发出。
+但 JWT 使用了签名机制。接受令牌时，可以用签名校验令牌。
-通过这种方式，你可以创建一个有效期为 1 周的令牌。然后当用户第二天使用令牌重新访问时，你知道该用户仍然处于登入状态。
+使用 JWT 创建有效期为一周的令牌。第二天，用户持令牌再次访问时，仍为登录状态。
-ä¸\80å\91¨å\90\8e令ç\89\8cå°\86ä¼\9aè¿\87æ\9c\9fï¼\8cç\94¨æ\88·å°\86ä¸\8dä¼\9aé\80\9aè¿\87认è¯\81ï¼\8cå¿\85é¡»å\86\8d次ç\99»å½\95æ\89\8dè\83½è\8e·å¾\97ä¸\80个æ\96°ä»¤ç\89\8cã\80\82è\80\8cä¸\94å¦\82æ\9e\9cç\94¨æ\88·ï¼\88æ\88\96第ä¸\89æ\96¹ï¼\89è¯\95å\9b¾ä¿®æ\94¹ä»¤ç\89\8c以篡æ\94¹è¿\87æ\9c\9fæ\97¶é\97´ï¼\8cä½ å°\86å\9b 为ç¾å\90\8dä¸\8då\8c¹é\85\8dè\80\8cè\83½å¤\9få\8f\91è§\89。
+令ç\89\8cäº\8eä¸\80å\91¨å\90\8eè¿\87æ\9c\9fï¼\8cå±\8aæ\97¶ï¼\8cç\94¨æ\88·èº«ä»½éª\8cè¯\81å°±ä¼\9a失败ã\80\82å\8fªæ\9c\89å\86\8d次ç\99»å½\95ï¼\8cæ\89\8dè\83½è\8e·å¾\97æ\96°ç\9a\84令ç\89\8cã\80\82å¦\82æ\9e\9cç\94¨æ\88·ï¼\88æ\88\96第ä¸\89æ\96¹ï¼\89篡æ\94¹ä»¤ç\89\8cç\9a\84è¿\87æ\9c\9fæ\97¶é\97´ï¼\8cå\9b 为ç¾å\90\8dä¸\8då\8c¹é\85\8dä¼\9a导è\87´èº«ä»½éª\8cè¯\81失败。
-如
果你想上手体验 JWT 令牌并了解其工作方式，可访问 <a href="https://jwt.io/" class="external-link" target="_blank">https://jwt.io</a>。
+如
需深入了解 JWT 令牌，了解它的工作方式，请参阅 <a href="https://jwt.io/" class="external-link" target="_blank">https://jwt.io</a>。
## 安装 `python-jose`
-我们需要安装 `python-jose` 以在 Python 中生成和校验 JWT 令牌：
+安装 `python-jose`，在 Python 中生成和校验 JWT 令牌：
<div class="termy">
</div>
-<a href="https://github.com/mpdavis/python-jose" class="external-link" target="_blank">Python-jose</a> 需要一个额外的加密后端。
+<a href="https://github.com/mpdavis/python-jose" class="external-link" target="_blank">Python-jose</a> 需要安装配套的加密后端。
-
è¿\99é\87\8cæ\88\91们使ç\94¨ç\9a\84æ\98¯æ\8e¨è\8d\90ç\9a\84å\90\8e端ï¼
\9a<a href="https://cryptography.io/" class="external-link" target="_blank">pyca/cryptography</a>ã
\80\82+
æ\9c¬æ\95\99ç¨\8bæ\8e¨è\8d\90ç\9a\84å\90\8e端æ\98¯ï¼
\9a<a href="https://cryptography.io/" class="external-link" target="_blank">pyca/cryptography</a>ã
\80\82
-!!! tip
- 本教程曾经使用过 <a href="https://pyjwt.readthedocs.io/" class="external-link" target="_blank">PyJWT</a>。
+!!! tip "提示"
- 但是后来更新为使用 Python-jose，因为它提供了 PyJWT 的所有功能，以及之后与其他工具进行集成时你可能需要的一些其他功能。
+ 本教程以前使用 <a href="https://pyjwt.readthedocs.io/" class="external-link" target="_blank">PyJWT</a>。
-## 哈希密码
+ 但后来换成了 Python-jose，因为 Python-jose 支持 PyJWT 的所有功能，还支持与其它工具集成时可能会用到的一些其它功能。
-「哈希」的意思是：将某些内容（在本例中为密码）转换为看起来像乱码的字节序列（只是一个字符串）。
+## 密码哈希
-每次你传入完全相同的内容（完全相同的密码）时，你都会得到完全相同的乱码。
+**哈希**是指把特定内容（本例中为密码）转换为乱码形式的字节序列（其实就是字符串）。
-但是你不能从乱码转换回密码。
+每次传入完全相同的内容时（比如，完全相同的密码），返回的都是完全相同的乱码。
-### 为什么使用哈希密码
+但这个乱码无法转换回传入的密码。
-如果你的数据库被盗，小偷将无法获得用户的明文密码，只能拿到哈希值。
+### 为什么使用密码哈希
-因此，小偷将无法尝试在另一个系统中使用这些相同的密码（由于许多用户在任何地方都使用相同的密码，因此这很危险）。
+原因很简单，假如数据库被盗，窃贼无法获取用户的明文密码，得到的只是哈希值。
+
+这样一来，窃贼就无法在其它应用中使用窃取的密码，要知道，很多用户在所有系统中都使用相同的密码，风险超大）。
## 安装 `passlib`
-PassLib 是一个用于处理哈希密码的很棒的 Python 包。
+Passlib 是处理密码哈希的 Python 包。
-它支持许多安全哈希算法以及配合算法使用的实用程序。
+它支持很多安全哈希算法及配套工具。
-æ\8e¨è\8d\90ç\9a\84ç®\97æ³\95æ\98¯ ã\80\8cBcryptã\80\8d。
+æ\9c¬æ\95\99ç¨\8bæ\8e¨è\8d\90ç\9a\84ç®\97æ³\95æ\98¯ **Bcrypt**。
-因此，安装附带 Bcrypt 的 PassLib：
+因此，请先安装附带 Bcrypt 的 PassLib：
<div class="termy">
</div>
-!!! tip
- 使用 `passlib`，你甚至可以将其配置为能够读取 Django，Flask 的安全扩展或许多其他工具创建的密码。
+!!! tip "提示"
+
+ `passlib` 甚至可以读取 Django、Flask 的安全插件等工具创建的密码。
+
+ 例如，把 Django 应用的数据共享给 FastAPI 应用的数据库。或利用同一个数据库，可以逐步把应用从 Django 迁移到 FastAPI。
- å\9b æ¤ï¼\8cä½ å°\86è\83½å¤\9fï¼\8c举个ä¾\8bå\90ï¼\8cå°\86æ\95°æ\8d®åº\93ä¸æ\9d¥è\87ª Django åº\94ç\94¨ç\9a\84æ\95°æ\8d®å\85±äº«ç»\99ä¸\80个 FastAPI åº\94ç\94¨ã\80\82æ\88\96è\80\85使ç\94¨å\90\8cä¸\80æ\95°æ\8d®åº\93ä½\86é\80\90æ¸\90å°\86åº\94ç\94¨ä»\8e Django è¿\81移å\88° FastAPI。
+ 并ä¸\94ï¼\8cç\94¨æ\88·å\8f¯ä»¥å\90\8cæ\97¶ä»\8e Django åº\94ç\94¨æ\88\96 FastAPI åº\94ç\94¨ç\99»å½\95。
- 而你的用户将能够同时从 Django 应用或 FastAPI 应用登录。
+## 密码哈希与校验
-## 哈希并校验密码
+从 `passlib` 导入所需工具。
-从 `passlib` 导入我们需要的工具。
+创建用于密码哈希和身份校验的 PassLib **上下文**。
-创建一个 PassLib 「上下文」。这将用于哈希和校验密码。
+!!! tip "提示"
-!!! tip
- PassLib 上下文还具有使用不同哈希算法的功能，包括仅允许用于校验的已弃用的旧算法等。
+ PassLib 上下文还支持使用不同哈希算法的功能，包括只能校验的已弃用旧算法等。
- 例如，你可以使用它来读取和校验由另一个系统（例如Django）生成的密码，但是使用其他算法例如 Bcrypt 生成新的密码哈希值。
+ 例如，用它读取和校验其它系统（如 Django）生成的密码，但要使用其它算法，如 Bcrypt，生成新的哈希密码。
- 并å\90\8cæ\97¶å\85¼å®¹æ\89\80æ\9c\89ç\9a\84è¿\99äº\9bå\8a\9fè\83½。
+ å\90\8cæ\97¶ï¼\8cè¿\99äº\9bå\8a\9fè\83½é\83½æ\98¯å\85¼å®¹ç\9a\84。
-创建一个工具函数以哈希来自用户的密码。
+接下来，创建三个工具函数，其中一个函数用于哈希用户的密码。
-ç\84¶å\90\8eå\88\9b建å\8f¦ä¸\80个工å\85·å\87½æ\95°ï¼\8cç\94¨äº\8eæ ¡éª\8cæ\8e¥æ\94¶ç\9a\84å¯\86ç \81æ\98¯å\90¦ä¸\8eå\98å\82¨ç\9a\84å\93\88å¸\8cå\80¼å\8c¹é\85\8d。
+第ä¸\80个å\87½æ\95°ç\94¨äº\8eæ ¡éª\8cæ\8e¥æ\94¶ç\9a\84å¯\86ç \81æ\98¯å\90¦å\8c¹é\85\8då\98å\82¨ç\9a\84å\93\88å¸\8cå\80¼。
-再创建另一个工具函数用于认证并返回用户。
+第三个函数用于身份验证，并返回用户。
```Python hl_lines="7 48 55-56 59-60 69-75"
{!../../../docs_src/security/tutorial004.py!}
```
-!!! note
- 如果你查看新的（伪）数据库 `fake_users_db`，你将看到哈希后的密码现在的样子：`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`。
+!!! note "笔记"
+
+ 查看新的（伪）数据库 `fake_users_db`，就能看到哈希后的密码：`"$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36WQoeG6Lruj3vjPGga31lW"`。
## 处理 JWT 令牌
导入已安装的模块。
-创建一个随机密钥，该密钥将用于对 JWT 令牌进行签名。
+创建用于 JWT 令牌签名的随机密钥。
-要生成一个安全的随机密钥，可使用以下命令：
+使用以下命令，生成安全的随机密钥：
<div class="termy">
</div>
-然后将输出复制到变量 「SECRET_KEY」 中（不要使用示例中的这个）。
+然后，把生成的密钥复制到变量**SECRET_KEY**，注意，不要使用本例所示的密钥。
-创建用于设定 JWT 令牌签名算法的变量 「ALGORITHM」，并将其设置为 `"HS256"`。
+创建指定 JWT 令牌签名算法的变量 **ALGORITHM**，本例中的值为 `"HS256"`。
-创建一个设置令牌过期时间的变量。
+创建设置令牌过期时间的变量。
-å®\9aä¹\89ä¸\80个å°\86å\9c¨ä»¤ç\89\8c端ç\82¹ä¸ç\94¨äº\8e响应的 Pydantic 模型。
+å®\9aä¹\89令ç\89\8c端ç\82¹响应的 Pydantic 模型。
-创建一个生成新的访问令牌的工具函数。
+创建生成新的访问令牌的工具函数。
```Python hl_lines="6 12-14 28-30 78-86"
{!../../../docs_src/security/tutorial004.py!}
## 更新依赖项
-更新 `get_current_user` 以接收与之前相同的令牌，但这次使用的是 JWT 令牌。
+更新 `get_current_user` 以接收与之前相同的令牌，但这里用的是 JWT 令牌。
-解码接收到的令牌，对其进行校验，然后返回当前用户。
+解码并校验接收到的令牌，然后，返回当前用户。
-如果令牌无效，立即返回一个 HTTP 错误。
+如果令牌无效，则直接返回 HTTP 错误。
```Python hl_lines="89-106"
{!../../../docs_src/security/tutorial004.py!}
## 更新 `/token` *路径操作*
-使用令牌的过期时间创建一个 `timedelta` 对象。
+用令牌过期时间创建 `timedelta` 对象。
-创建一个真实的 JWT 访问令牌并返回它。
+创建并返回真正的 JWT 访问令牌。
```Python hl_lines="115-128"
{!../../../docs_src/security/tutorial004.py!}
```
-### 关于 JWT 「主题」 `sub` 的技术细节
+### JWT `sub` 的技术细节
-JWT 的规范中提到有一个 `sub` 键，值为该令牌的主题。
+JWT 规范还包括 `sub` 键，值是令牌的主题。
-使用它并不是必须的，但这是你放置用户标识的地方，所以我们在示例中使用了它。
+该键是可选的，但要把用户标识放在这个键里，所以本例使用了该键。
-除了识别用户并允许他们直接在你的 API 上执行操作之外，JWT 还可以用于其他事情。
+除了识别用户与许可用户在 API 上直接执行操作之外，JWT 还可能用于其它事情。
-例如，你可以识别一个 「汽车」 或 「博客文章」。
+例如，识别**汽车**或**博客**。
-然后你可以添加关于该实体的权限，比如「驾驶」（汽车）或「编辑」（博客）。
+接着，为实体添加权限，比如**驾驶**（汽车）或**编辑**（博客）。
-然后，你可以将 JWT 令牌交给用户（或机器人），他们可以使用它来执行这些操作（驾驶汽车，或编辑博客文章），甚至不需要有一个账户，只需使用你的 API 为其生成的 JWT 令牌。
+然后，把 JWT 令牌交给用户（或机器人），他们就可以执行驾驶汽车，或编辑博客等操作。无需注册账户，只要有 API 生成的 JWT 令牌就可以。
-使用这样的思路，JWT 可以用于更复杂的场景。
+同理，JWT 可以用于更复杂的场景。
-å\9c¨è¿\99äº\9bæ\83\85å\86µä¸\8bï¼\8cå\87 个å®\9eä½\93å\8f¯è\83½æ\9c\89ç\9b¸å\90\8cç\9a\84 IDï¼\8cæ¯\94å¦\82说 `foo`ï¼\88ä¸\80个ç\94¨æ\88· `foo`ï¼\8cä¸\80è¾\86车 `foo`ï¼\8cä¸\80ç¯\87å\8d\9a客æ\96\87ç« `foo`ï¼\89。
+å\9c¨è¿\99äº\9bæ\83\85å\86µä¸\8bï¼\8cå¤\9a个å®\9eä½\93ç\9a\84 ID å\8f¯è\83½æ\98¯ç\9b¸å\90\8cç\9a\84ï¼\8c以 ID `foo` 为ä¾\8bï¼\8cç\94¨æ\88·ç\9a\84 ID æ\98¯ `foo`ï¼\8c车ç\9a\84 ID æ\98¯ `foo`ï¼\8cå\8d\9a客ç\9a\84 ID ä¹\9fæ\98¯ `foo`。
-因此，为了避免 ID 冲突，当为用户创建 JWT 令牌时，你可以在 `sub` 键的值前加上前缀，例如 `username:`。所以，在这个例子中，`sub` 的值可以是：`username:johndoe`。
+为了避免 ID 冲突，在给用户创建 JWT 令牌时，可以为 `sub` 键的值加上前缀，例如 `username:`。因此，在本例中，`sub` 的值可以是：`username:johndoe`。
-要记住的重点是，`sub` 键在整个应用程序中应该有一个唯一的标识符，而且应该是一个字符串。
+注意，划重点，`sub` 键在整个应用中应该只有一个唯一的标识符，而且应该是字符串。
-## 检查效果
+## 检查
运行服务器并访问文档： <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>。
-你会看到如下用户界面：
+可以看到如下用户界面：
<img src="https://fastapi.tiangolo.com/img/tutorial/security/image07.png">
-像以前一样对应用程序进行认证。
+用与上一章同样的方式实现应用授权。
使用如下凭证：
-用户名: `johndoe`
-密码: `secret`
+用户名: `johndoe` 密码: `secret`
+
+!!! check "检查"
-!!! check
- 请注意，代码中没有任何地方记录了明文密码 「`secret`」，我们只保存了其哈希值。
+ 注意，代码中没有明文密码**`secret`**，只保存了它的哈希值。
<img src="https://fastapi.tiangolo.com/img/tutorial/security/image08.png">
-访é\97® `/users/me/` 端ç\82¹ï¼\8cä½ å°\86è\8e·å¾\97å¦\82ä¸\8b响应：
+è°\83ç\94¨ `/users/me/` 端ç\82¹ï¼\8cæ\94¶å\88°ä¸\8bé\9d¢ç\9a\84响应：
```JSON
{
<img src="https://fastapi.tiangolo.com/img/tutorial/security/image09.png">
-如果你打开开发者工具，将看到数据是如何发送的并且其中仅包含了令牌，只有在第一个请求中发送了密码以校验用户身份并获取该访问令牌，但之后都不会再发送密码：
+打开浏览器的开发者工具，查看数据是怎么发送的，而且数据里只包含了令牌，只有验证用户的第一个请求才发送密码，并获取访问令牌，但之后不会再发送密码：
<img src="https://fastapi.tiangolo.com/img/tutorial/security/image10.png">
-!!! note
- 注意请求中的 `Authorization` 首部，其值以 `Bearer` 开头。
+!!! note "笔记"
+
+ 注意，请求中 `Authorization` 响应头的值以 `Bearer` 开头。
-## 使用 `scopes` 的进阶用法
+## `scopes` 高级用法
-OAuth2 具有「作用域」的概念。
+OAuth2 支持**`scopes`**（作用域）。
-你可以使用它们向 JWT 令牌添加一组特定的权限。
+**`scopes`**为 JWT 令牌添加指定权限。
-然后，你可以将此令牌直接提供给用户或第三方，使其在一些限制下与你的 API 进行交互。
+让持有令牌的用户或第三方在指定限制条件下与 API 交互。
-你可以在之后的**进阶用户指南**中了解如何使用它们以及如何将它们集成到 **FastAPI** 中。
+**高级用户指南**中将介绍如何使用 `scopes`，及如何把 `scopes` 集成至 **FastAPI**。
-## 总结
+## 小结
-通过目前你所看到的，你可以使用像 OAuth2 和 JWT 这样的标准来构建一个安全的 **FastAPI** 应用程序。
+至此，您可以使用 OAuth2 和 JWT 等标准配置安全的 **FastAPI** 应用。
-å\9c¨å\87 ä¹\8eæ\89\80æ\9c\89ç\9a\84æ¡\86æ\9e¶ä¸ï¼\8cå¤\84ç\90\86å®\89å\85¨æ\80§é\97®é¢\98é\83½å¾\88容æ\98\93æ\88\90为ä¸\80个ç\9b¸å½\93å¤\8dæ\9d\82ç\9a\84è¯\9dé¢\98。
+å\87 ä¹\8eå\9c¨æ\89\80æ\9c\89æ¡\86æ\9e¶ä¸ï¼\8cå¤\84ç\90\86å®\89å\85¨é\97®é¢\98å¾\88å¿«é\83½ä¼\9aå\8f\98å¾\97é\9d\9e常å¤\8dæ\9d\82。
-许多高度简化了安全流程的软件包不得不在数据模型、数据库和可用功能上做出很多妥协。而这些过于简化流程的软件包中，有些其实隐含了安全漏洞。
+有些包为了简化安全流，不得不在数据模型、数据库和功能上做出妥协。而有些过于简化的软件包其实存在了安全隐患。
---
-**FastAPI** ä¸\8d对任ä½\95æ\95°æ\8d®åº\93ã\80\81æ\95°æ\8d®æ¨¡å\9e\8bæ\88\96å·¥å\85·å\81\9aä»»ä½\95妥协。
+**FastAPI** ä¸\8då\90\91ä»»ä½\95æ\95°æ\8d®åº\93ã\80\81æ\95°æ\8d®æ¨¡å\9e\8bæ\88\96å·¥å\85·å\81\9a妥协。
-å®\83ç»\99äº\86ä½ æ\89\80æ\9c\89ç\9a\84ç\81µæ´»æ\80§æ\9d¥é\80\89æ\8b©æ\9c\80é\80\82å\90\88ä½ é¡¹ç\9b®ç\9a\84å\89\8dè\80\85。
+å¼\80å\8f\91è\80\85å\8f¯ä»¥ç\81µæ´»é\80\89æ\8b©æ\9c\80é\80\82å\90\88项ç\9b®ç\9a\84å®\89å\85¨æ\9cºå\88¶。
-你可以直接使用许多维护良好且使用广泛的包，如 `passlib` 和 `python-jose`，因为 **FastAPI** 不需要任何复杂的机制来集成外部包。
+还可以直接使用 `passlib` 和 `python-jose` 等维护良好、使用广泛的包，这是因为 **FastAPI** 不需要任何复杂机制，就能集成外部的包。
-但它为你提供了一些工具，在不影响灵活性、健壮性和安全性的前提下，尽可能地简化这个过程。
+而且，**FastAPI** 还提供了一些工具，在不影响灵活、稳定和安全的前提下，尽可能地简化安全机制。
-而且你可以用相对简单的方式使用和实现安全、标准的协议，比如 OAuth2。
+**FastAPI** 还支持以相对简单的方式，使用 OAuth2 等安全、标准的协议。
-你可以在**进阶用户指南**中了解更多关于如何使用 OAuth2 「作用域」的信息，以实现更精细的权限系统，并同样遵循这些标准。带有作用域的 OAuth2 是很多大的认证提供商使用的机制，比如 Facebook、Google、GitHub、微软、Twitter 等，授权第三方应用代表用户与他们的 API 进行交互。
+**高级用户指南**中详细介绍了 OAuth2**`scopes`**的内容，遵循同样的标准，实现更精密的权限系统。OAuth2 的作用域是脸书、谷歌、GitHub、微软、推特等第三方身份验证应用使用的机制，让用户授权第三方应用与 API 交互。
projects / thirdparty / fastapi / fastapi.git / commitdiff
