# 认证 (/zh/docs/requests/auth)

**认证** 标签页说明请求如何证明自己的身份。选择一个 **类型**，填写它的字段，Echolot 就会在每次发送请求时添加凭据。在文件夹或工作区上设置一次认证，其中的每个请求都可以使用它。

<Shot id="requests-http-auth-oauth" alt="Orders 的认证标签页，选择了 OAuth 2：OAuth 2.0 的客户端凭据授权类型、令牌 URL、客户端 ID 和范围，底部是带“获取令牌”的令牌栏" />

## 不要把凭据放进文件 [#keep-credentials-out-of-files]

每个字段都可以使用 `{{variables}}`。把密码、令牌和密钥放在保存于钥匙串中的[机密变量](/docs/workspaces/secrets)里，并在字段中写 `{{password}}`。这样请求文件就不含任何机密，你可以放心提交。

当你在凭据字段中输入字面值时，它下方会出现警告：**以纯文本形式存储在工作区文件中。** 点按 **移到钥匙串**，Echolot 就会把该值存为工作区的机密变量，并在原处写入 `{{name}}`。

Echolot 添加的凭据在请求页面显示它们的地方会被遮蔽：在 **自动生成** 的标头中，以及 URL 栏下方的 URL 预览中。

## 从文件夹和工作区继承 [#inherit-from-folders-and-the-workspace]

**继承** 是默认值。继承的请求使用其上方最近一个设置了认证的文件夹的认证，然后才是工作区的认证。在 **使用** 下，标签页会说明适用的是哪一个，例如 `Folder “Orders”: Bearer Token`，
并带一个打开它的按钮：**编辑文件夹认证…** 或 **编辑工作区认证…**。上方都没有设置认证时，请求不发送任何认证。

<Shot id="requests-http-auth-inherit" alt="设为“继承”的请求的认证标签页：使用 Folder “Orders”: Bearer Token，带“编辑文件夹认证…”按钮" />

有自己认证的请求会保留它，它的 **认证** 标签页还会显示一行 **工作区认证**，列出工作区的认证，并带一个打开它的按钮：**工作区认证…**，或在工作区还没有认证时显示 **设置工作区认证…**。
**工作区认证…** 也在命令面板中（<kbd>⌘</kbd><kbd>K</kbd>）。

要一次为许多请求设置认证：

1. 在边栏中右键点按某个文件夹并选取 **文件夹设置…**。对于工作区，请使用请求 **认证** 标签页或命令面板中的 **工作区认证…**，或者点按边栏底部的工作区切换器并选取 **工作区设置…**。
2. 打开 **认证** 标签页并选择类型。文件夹也可以继承；工作区不能。在设置下方，标签页会说明有多少个设为 **继承** 的请求使用这个认证。
3. 对于 OAuth 2.0，直接在那里登录：底部的令牌栏与请求中的用法相同（见 [OAuth 2.0](#oauth-20)），每个继承该认证的请求都使用这个令牌。**获取令牌** 会先存储认证。
   只有认证已存储后，栏中才会显示该文件夹或工作区自己的令牌，所以它绝不会显示或遗忘属于上层认证的令牌。
4. 点按 **完成**。

<Shot id="workspaces-folder-auth-oauth" alt="文件夹设置的认证标签页，选择了 OAuth 2.0，显示它的令牌 URL 和客户端、带“获取令牌”的令牌栏，以及继承它的请求数量" />

在 Alpenglow 示例中，**Orders** 文件夹用 `{{token}}` 设置了 **Bearer 令牌**，每个订单请求都继承它。**Auth › Sign in** 通过[捕获](/docs/requests/captures)用自己的响应填入 `{{token}}`。

## 选择类型 [#choose-a-type]

| 类型 | Echolot 的做法 |
| --- | --- |
| **继承** | 使用文件夹或工作区的认证。 |
| **无认证** | 不发送任何凭据，即使文件夹设置了凭据也是如此。 |
| **Basic** | 根据用户名和密码添加 `Authorization: Basic …`。 |
| **Digest** | 应答服务器的 Digest 质询。 |
| **Bearer 令牌** | 添加 `Authorization: Bearer <token>`。 |
| **API 密钥** | 把密钥作为标头或查询参数添加。 |
| **OAuth 1.0** | 使用你已有的令牌，以 OAuth 1.0 为每个请求签名。 |
| **OAuth 2.0** | 获取访问令牌，并作为 Bearer 令牌或在地址中发送。 |
| **AWS 签名** | 以 AWS Signature Version 4 为每个请求签名。 |
| **JWT Bearer** | 每次发送都签发新的 JSON Web Token。 |
| **Hawk** | 以 Hawk 为每个请求签名。 |
| **Akamai EdgeGrid** | 以 EG1-HMAC-SHA256 为每个请求签名。 |
| **NTLM** | 应答服务器的 NTLM 质询。 |

你自己在 **标头** 标签页中添加的 `Authorization` 标头，会取代 **认证** 标签页将要添加的那个。

### Basic [#basic]

填写 **用户名** 和 **密码**。Echolot 会把它们以 Base64 编码后放在 `Authorization` 标头中发送。可以用 Alpenglow 中的 **Echo › Basic auth** 试一试。

### Digest [#digest]

填写 **用户名** 和 **密码**。第一次发送不带凭据；当服务器以 Digest 质询回应 401 时，Echolot 会用第二个请求应答它一次。两者在交换中都显示为跳转。

### Bearer 令牌 [#bearer-token]

填写 **令牌**，通常是 `{{token}}`。**前缀** 默认为 `Bearer`；对于需要其他词的服务器，可以更改它，也可以清空它，只发送令牌。

### API 密钥 [#api-key]

填写 **键**（标头或参数的名称，默认为 `X-API-Key`）和 **值**，然后在 **添加到** 下选择它放在哪里：**标头** 或 **查询**。

### OAuth 2.0 [#oauth-20]

Echolot 替你获取访问令牌，并把它作为 `Authorization: Bearer <token>` 添加。

| 字段 | 含义 |
| --- | --- |
| **授权类型** | **授权码**、**客户端凭据**、**设备码** 或 **密码（旧版）**。 |
| **授权 URL** | 你登录的地方（授权码）。 |
| **设备 URL** | 设备码的来源（设备码）。 |
| **令牌 URL** | 令牌的来源。 |
| **用户名**、**密码** | 用户自己的登录信息（密码）。与任何其他凭据一样，密码可以移到钥匙串。 |
| **客户端 ID**、**客户端密钥** | 客户端的凭据。公开客户端的密钥留空。 |
| **范围** | 要请求的范围，用空格分隔，例如 `read write`。 |
| **受众** | 用于需要它的服务器。 |
| **重定向 URI** | 授权码。留空表示自动：在空闲端口上使用环回地址 `http://127.0.0.1:<port>/callback`。 |
| **PKCE（S256）** | 授权码。默认开启。 |
| **客户端认证** | 客户端 ID 和密钥如何到达令牌 URL：**HTTP Basic**（默认）或 **在正文中**。 |
| **令牌添加到** | **标头**（默认）或 **URL**：令牌作为查询参数，名称在 **参数** 下指定（默认为 `access_token`）。地址会出现在日志和历史记录中，所以只对不接受其他方式的 API 使用 URL。 |
| **标头前缀** | 标头中令牌前面的词，默认为 `Bearer`。 |

在标签页底部，令牌栏显示是否有令牌。点按 **获取令牌**：

- **授权码** 会在浏览器中打开授权 URL。在那里登录；Echolot 会接住重定向，并在你完成之前显示 **请在浏览器中完成登录…**。
- **设备码** 会显示带一个代码的 **在其他设备上登录**。点按 **打开**（带页面的主机名），在那里输入代码并批准；Echolot 会等待，并显示 **正在等待批准…**。
- **客户端凭据** 直接向令牌 URL 请求。这种授权类型无需点按 **获取令牌**：第一次发送会自己获取令牌。
- **密码（旧版）** 把用户名和密码发送到令牌 URL，同样无需点按：第一次发送会获取令牌。只对要求它的旧版 API 使用。这种授权类型已被弃用，因为密码本身会离开你的 Mac，
  所以服务器提供授权码时，请优先选择授权码。

Echolot 不提供隐式授权，它同样已被弃用。大多数仍提供隐式授权的服务器也提供授权码，导入的隐式授权会变成授权码；请确认服务器接受它。

有了令牌之后，栏中会显示 **钥匙串中的访问令牌**，以及它的类型、到期时间、是否 **自动刷新** 和它的范围。**获取新令牌** 会替换它；**忘记** 会删除它。

令牌如何保存和使用：

- 令牌存储在钥匙串中，从不写入工作区文件。
- 令牌属于设置该认证的请求、文件夹或工作区，也属于签发它时所用的环境和设置：切换环境，或更改令牌 URL、客户端 ID、范围或其他决定令牌属于谁的设置，会使用或获取它自己的令牌，
  绝不会发送为其他情形签发的令牌。从文件夹继承 OAuth 的请求共用它的令牌。**忘记** 会删除所有环境的令牌。
- 令牌过期后，下一次发送会用它的刷新令牌刷新它。客户端凭据或密码令牌会重新获取。否则发送会停止，并显示 **此请求需要 OAuth 令牌：请先在“认证”标签页中获取。** 或
  **OAuth 令牌已过期且无法刷新：请在“认证”标签页中获取新的令牌。**

要试一试，请发送 Alpenglow 中的 **Auth › Orders with OAuth 2**：它对演示 API 使用客户端凭据。

#### 高级 [#advanced]

大多数服务器用不到这些，所以它们折叠在 **高级** 下。其中有内容被设置时，它会自动展开。

<Shot id="requests-http-auth-oauth-advanced" alt="OAuth 2.0 的“高级”部分：自动刷新、刷新 URL，以及授权请求、令牌请求和刷新请求的参数表" />

- **自动刷新** 默认开启。关闭它可以原样发送已过期的令牌，看看 API 如何回应。客户端凭据和密码授权类型仍会获取第一个令牌。
- **刷新 URL** 用于刷新端点不是令牌 URL 的服务器。留空表示使用令牌 URL。
- **授权请求**、**令牌请求** 和 **刷新请求** 为需要标准字段之外内容的服务器添加参数：Google 的 `access_type = offline`（让它给出刷新令牌）、Azure AD 的 `resource`、租户或 API 版本。
  每一行有一个键、一个值（可以使用变量，所以机密可以留在钥匙串中），对于令牌请求和刷新请求，还有它放在哪里：**正文**、**标头** 或 **URL**。与标准参数同名的参数会替换它。授权请求的参数会放入登录地址，
  对于设备码则放入设备授权请求。它们绝不会替换 `state` 或 PKCE 质询。

### OAuth 1.0 [#oauth-10]

适用于仍在使用 OAuth 1.0 的 API：NetSuite、Magento 和 Adobe Commerce、X 的 v1.1 端点，以及 Jira 或 Confluence Server 的应用程序链接等。Echolot 用你已有的令牌为每个请求签名。它不会运行获取令牌的三方流程，Postman 也不会。

<Shot id="requests-http-auth-oauth1" alt="使用 OAuth 1.0 的认证标签页：签名方法、Consumer Key 和 Consumer Secret、访问令牌和令牌密钥，以及“添加到”标头" />

1. 选择 **签名方法**：**HMAC-SHA1**（最常见）、**HMAC-SHA256**、**HMAC-SHA512**、**RSA-SHA1**、**RSA-SHA256**、**RSA-SHA512** 或 **PLAINTEXT**。
2. 填写 **Consumer Key**，然后填写 **Consumer Secret**；使用 RSA 时则填写 **私钥**（粘贴它，或点按 **选取 PEM 文件…** 直接把它放入钥匙串）。
3. 填写 **访问令牌**，除 RSA 外还要填写 **令牌密钥**。对于在拥有令牌之前发出的请求，把它们留空。
4. 在 **添加到** 下选择 **标头**（`Authorization: OAuth …`，默认）、**URL** 或 **正文**。**正文** 会签入表单正文，没有正文的请求则签入地址。
5. **高级** 中有 **Realm**、**回调 URL** 和 **验证码**（用于你手动完成的三方流程的各步骤）、**添加 oauth_version="1.0"**（默认开启）和 **将正文哈希加入签名**（`oauth_body_hash`，用于不是表单的正文）。

每个请求在发送时签名，带有新的时间戳和 nonce，覆盖方法、地址、它的查询和表单正文的字段。

### AWS 签名 [#aws-signature]

填写 **访问密钥 ID**、**秘密访问密钥**、**区域**（默认为 `us-east-1`）和 **服务**（默认为 `execute-api`；还有 `s3`、`lambda`、`es` 等）。**会话令牌** 只用于临时凭据。每个请求在发送时签名，使用它实际发出时的时间、主机和正文。

### JWT Bearer [#jwt-bearer]

Echolot 为每次发送签发新的令牌。

1. 选择 **算法**：**HS256**、**HS384** 或 **HS512**（带机密的 HMAC），**RS256**、**RS384**、**RS512**、**PS256**、**PS384** 或 **PS512**（RSA 私钥），或者 **ES256** 或 **ES384**（椭圆曲线私钥）。
2. 对于 HMAC，填写 **密钥**；当提供方给你的是 Base64 形式时，勾选 **密钥为 Base64**。对于私钥，把它粘贴到 **私钥** 中，或点按 **选取 PEM 文件…**：密钥会直接进入钥匙串，字段按名称引用它。
   密钥可以是 PKCS #8、PKCS #1 或 SEC 1 PEM。
3. 以 JSON 编写 **声明**。其中可以包含变量：`{"sub": "{{userID}}"}`。
4. 如果服务器需要，添加 **标头字段**，例如 `kid`。`alg` 和 `typ` 会替你设置。
5. **添加“iat”（签发时间）** 默认开启。**有效期** 会添加 `exp`，为从现在起这么多秒之后（默认为 300）；0 表示不添加。你在 JSON 中自己设置的声明会按原样保留。
6. 在 **添加到** 下选择 **标头**（带 **前缀**，默认为 `Bearer`）或 **查询**（带 **参数** 名称，默认为 `token`）。

### Hawk [#hawk]

填写 **ID** 和 **键**，选择 **算法**（**SHA-256** 或 **SHA-1**），如果服务器需要，再添加 **App 数据（ext）**。勾选 **将正文哈希加入签名** 以包含载荷哈希。每个请求都用时间、nonce、方法、路径、主机和端口签名。

### Akamai EdgeGrid [#akamai-edgegrid]

填写 **客户端令牌**、**客户端密钥** 和 **访问令牌**。**要签名的标头** 是以逗号分隔的列表，通常为空。**签名的正文字节数** 限制 POST 正文有多少参与哈希（默认为 131072）。

### NTLM [#ntlm]

填写 **用户名** 和 **密码**，如果服务器需要，再填写 **域** 和 **工作站**。Echolot 支持 NTLMv2：它在同一个连接上应答服务器的质询，401 会作为跳转保留在交换中。

NTLM 认证的是连接而不是请求，所以它需要 HTTP/1.1。当 HTTP 版本为 **自动** 时，Echolot 对 NTLM 请求使用 HTTP/1.1；选择了 **HTTP/2** 或 **HTTP/3** 时，发送会被拒绝。
见[请求设置](/docs/requests/settings#http-version)。

## 凭据只留在其来源 [#credentials-stay-with-their-origin]

当重定向指向另一个源（不同的协议、主机或端口）时，Echolot 不会把你的凭据带过去。它会丢弃：

- `Authorization`、`Proxy-Authorization` 和 `Cookie` 标头，
- 常见的 API 密钥标头（`X-API-Key`、`Api-Key`、`Apikey`、`X-Auth-Token`、`X-Access-Token`、`Private-Token`、`X-Functions-Key`）、你的 **API 密钥** 认证所使用的标头，以及值中含有机密变量的任何标头，
- Digest、AWS 签名、OAuth 1.0、Hawk、EdgeGrid 和 NTLM 的签名，以及为第一个主机选定的客户端证书。

新主机的证书和代理适用于前往那里的这一跳。见[请求设置](/docs/requests/settings#redirects)。

## 受保护的环境 [#protected-environments]

**获取令牌** 也会发送请求。当窗口的环境受保护时，它会像 **发送** 一样先询问。见[受保护的环境](/docs/workspaces/protected-environments)。