Postman 授权请求
API 使用授权来确保客户端请求安全地访问数据。这可能涉及对请求的发送者进行身份验证,并确认他们有权访问或操作相关数据。如果您正在构建 API,则可以从多种身份验证模型中进行选择。如果您要集成第三方 API,所需的授权将由 API 提供商指定。
您可以将身份验证详细信息与您在 Postman 中发送的任何请求一起传递。授权数据可以包含在标头、正文中,或作为请求的参数。如果您在“授权”选项卡中输入您的身份验证详细信息,Postman 将自动为您选择的身份验证类型填充请求的相关部分。您可以使用变量和集合来更安全有效地定义授权细节,使您能够在多个地方重复使用相同的信息。
指定授权详细信息
在 Postman 中打开请求后,使用“授权”选项卡选择身份验证类型,然后完成所选类型的相关详细信息。正确的数据值将由服务器端的 API 确定。如果您使用的是第三方 API,请参阅提供商的文档以了解任何所需的身份验证详细信息。
您可以将这些身份验证类型与 Newman 和监视器以及 Postman 一起使用。
当您从“类型”下拉列表中选择一种类型时,Postman 将指示您的详细信息将包含在请求的哪些部分中,例如标头、正文、URL 或查询参数。当您选择或输入它们时,Postman 会将您的身份验证详细信息添加到请求的相关部分,因此您可以在运行请求之前预览数据的发送方式。
您的授权数据将出现在请求的相关部分,例如标题选项卡中。要显示自动添加的标题,请选择hidden。
将鼠标悬停在标题上以获取有关添加位置的信息。要更改授权标头,请返回授权选项卡并更新您的配置。
您不能直接在“标头”选项卡中覆盖由您的授权选择添加的标头。如果您需要与 Postman 自动生成的不同的身份验证标头,请更改Authorization中的设置,或删除您的身份验证设置并手动添加标头。
您的请求授权可以使用环境、集合和全局变量。Postman 不保存标头数据或查询参数,以避免暴露 API 密钥等敏感数据。
发送后,您可以在 Postman 控制台中检查整个请求的原始转储,包括身份验证数据。
继承授权
如果您将请求分组到集合和文件夹中,则可以指定要在整个组中重复使用的身份验证详细信息。
默认情况下,集合或文件夹内的请求将从父级继承身份验证,这意味着它们将使用您在文件夹或集合级别指定的相同身份验证。要为单个请求更改此设置,请在请求授权选项卡中进行不同的选择。
授权类型
从授权选项卡上的类型下拉列表中选择一种类型。您可以为请求、集合或文件夹选择授权类型。
无授权
除非您指定身份验证类型,否则 Postman 不会随请求发送授权详细信息。如果您的请求不需要授权,请从授权选项卡类型下拉列表中选择无授权。
API密钥
使用 API 密钥身份验证,您可以在请求标头或查询参数中向 API 发送键值对。在请求授权选项卡中,从类型列表中选择API 密钥。输入您的键名和值,然后从“添加到”下拉列表中选择“标头”或“查询参数”。您可以将您的值存储在变量中以获得额外的安全性。
Postman 会将相关信息附加到您的请求Headers或 URL 查询字符串中。
不记名令牌
不记名令牌使请求能够使用访问密钥进行身份验证,例如 JSON Web 令牌 (JWT)。令牌是一个文本字符串,包含在请求标头中。在请求授权选项卡中,从类型下拉列表中选择Bearer Token。在令牌字段中,输入您的 API 密钥值。为了增加安全性,将其存储在一个变量中并按名称引用该变量。
Postman 会将令牌值Bearer以要求的格式附加到请求授权标头的文本中,如下所示:
Bearer <Your API key>
如果需要自定义前缀,请使用密钥为Authorization的API 密钥。
JWT 承载
Postman 还支持生成 JWT 承载令牌来授权请求。您可以在编辑器中输入负载,然后生成 JWT 令牌并将其添加到请求中。在请求授权选项卡中,从类型下拉列表中选择JWT Bearer。
- 将 JWT 令牌添加到- 选择请求标头或查询参数以指定将 JWT 令牌添加到您的请求的方式。
- 算法- 选择用于 JWT 令牌的算法。支持的算法包括:HS - 带 SHA 的 HMACRS - 带 SHA 的 RSA (RSASSA-PKCS1-v1_5)ES - 带 SHA 的 ECDSAPS - 带 SHA 的 RSA (RSASSA-PSS)
- 秘密- 与 HMAC-SHA 算法一起使用的秘密。
- 秘密 Base64 编码- 如果秘密以 base-64 格式编码。
- 私钥- 用于为 RS、ES 和 PS 算法签署令牌的私钥。选择选择文件以上传 PKCS #8 格式的私钥。
- 负载- 以 JSON 格式输入 JWT 令牌的负载数据。
在高级配置部分,您还可以配置以下项目。如果您不配置它们,它们会自动生成。
- 标头前缀- 在标头开头使用的可选前缀。此标头前缀是请求的一部分,而不是 JWT 的一部分。
- 标头- 您还希望在 JWT 令牌中发送的任何自定义标头。与所选算法相关的标头会自动添加。
基本授权
基本身份验证涉及在您的请求中发送经过验证的用户名和密码。在请求授权选项卡中,从类型下拉列表中选择基本身份验证。
在用户名和密码字段中输入您的 API 用户名和密码。为了额外的安全性,将它们存储在变量中。
在请求标头中,授权标头向 API 传递一个 Base64 编码的字符串,表示您的用户名和密码值,附加到文本中,Basic如下所示:
Basic <Base64 encoded username and password>
摘要认证
使用 Digest auth,客户端向 API 发送第一个请求,服务器以一些详细信息作为响应,包括只能使用一次的数字(随机数)、领域值和401未经授权的响应。然后,您发送回一个加密的数据数组,其中包括用户名和密码,以及在第一个请求中从服务器接收到的数据。服务器使用传递的数据生成加密字符串并将其与您发送的内容进行比较以验证您的请求。
在请求的Authorization选项卡中,从Type下拉列表中选择Digest Auth。Postman 将为身份验证请求的两个阶段提供字段。它将使用第一个请求从服务器返回的数据自动完成高级部分中第二个请求的字段。要使 Postman 能够自动执行流程,请输入用户名和密码值(或变量),这些值将与第二个请求一起发送。
如果您不希望 Postman 自动提取数据,请在左侧栏中选择是,禁用重试请求。如果这样做,您将需要完成高级字段并手动运行每个请求。
在高级部分中设置字段是可选的。当您的第一个请求运行时,Postman 会自动填充它们。
- Realm - 服务器在WWW-Authenticate响应标头中指定的字符串。
- Nonce - 服务器在WWW-Authenticate响应标头中指定的唯一字符串。
- 算法- 一个字符串,指示用于生成摘要和校验和的一对算法。邮递员支持MD5和SHA算法。
- qop - 应用于消息的保护质量。该值必须是服务器在WWW-Authenticate响应标头中指定的选项之一。
- Nonce Count - 客户端使用此请求中的 nonce 值发送的请求数(包括当前请求)的十六进制计数。
- Client Nonce - 客户端提供的不透明引用字符串值,客户端和服务器都使用它来避免选择的明文攻击,提供相互身份验证,并提供一些消息完整性保护。
- 不透明- 由服务器在响应标头中指定的一串数据WWW-Authenticate,将与同一保护空间中的 URI 一起使用。
OAuth 1.0
OAuth 1.0 使客户端应用程序能够访问第三方 API 提供的数据。例如,作为服务的用户,您可以授予另一个应用程序访问您使用该服务的数据的权限,而无需暴露您的用户名和密码等详细信息。使用 OAuth 1.0 访问用户数据涉及客户端应用程序、用户和服务提供商之间的一些来回请求。
OAuth 1.0 有时被称为“两条腿”(仅在客户端和服务器之间进行身份验证)或“三条腿”(客户端为第三方服务的用户请求数据)。示例 OAuth 1.0 流程可以按如下方式运行:
- 要使用第三方服务请求用户数据,消费者(客户端应用程序)使用密钥和秘密等凭据请求访问令牌。
- 服务提供者发出初始令牌(不提供对用户数据的访问),消费者请求用户授权。
- 当用户授予身份验证时,消费者发出请求以将临时令牌交换为访问令牌,从而通过用户身份验证的验证。
- 服务提供者返回访问令牌,然后消费者可以向服务提供者请求访问用户的数据。
Postman 支持OAuth Core 1.0 Revision A。
要使用 OAuth 1.0,请执行以下操作:
- 在请求的授权选项卡中,从类型下拉列表中选择OAuth 1.0 。
- 从下拉列表中选择签名方法。这将决定哪些参数包含在您的请求中。Postman 支持HMAC-SHA1, HMAC-SHA256, HMAC-SHA512, RSA-SHA1, RSA-SHA256,RSA-SHA512和PLAINTEXT。如果您的服务器需要HMACorPLAINTEXT签名,Postman 将提供Consumer Key、Consumer Secret、Access Token和Token Secret字段。如果您使用RSA签名,Postman 将提供Consumer Key、Access Token和Private Key输入。
- 您可以选择设置高级详细信息——否则 Postman 将尝试自动完成这些。
- 您可以在请求标头或正文/URL 中包含身份验证详细信息。从“将授权添加到”下拉列表中选择一项。如果您想检查详细信息将如何包含在请求中,请打开“标题”或“正文”选项卡。
如果您在标头中发送 OAuth 1.0 数据,发送您的密钥和秘密值的授权标头将附加到字符串以及OAuth其他以逗号分隔的必需详细信息。
当您完成授权设置中的所有必填字段后,Postman 会将 OAuth 1.0 信息附加到请求标头。
如果您在正文和 URL 中发送 OAuth 1.0 数据,则数据将添加到请求正文或参数中,具体取决于请求方法。
如果请求方法是POST或PUT,并且请求正文类型是x-www-form-urlencoded,Postman 将在请求正文中添加授权参数。否则,例如在GET请求中,您的密钥和机密数据将在 URL 查询参数中传递。
OAuth 1.0 auth 参数值如下:
- 签名方法- 您的 API 用于验证请求的方法。
- Consumer Key - 用于向服务提供者标识消费者的值。
- 消费者秘密- 消费者用来建立密钥所有权的值。(对于HMAC和PLAINTEXT签名方法。)
- 访问令牌- 代表消费者访问用户数据的权限的值。
- Token Secret - 消费者用来建立给定令牌所有权的值。(对于HMAC和PLAINTEXT签名方法。)
- 私钥- 用于生成身份验证签名的私钥。(对于RSA签名方法。)
- 高级参数:回调 URL - URL 服务提供商将重定向到以下用户授权。(如果您的服务器使用 OAuth 1.0 修订版 A,则为必需。)Verifier - 用户授权后来自服务提供商的验证码。时间戳- 服务器用来防止时间窗口外的重播攻击的时间戳。Nonce - 客户端生成的随机字符串。版本- OAuth 身份验证协议的版本 (1.0)。Realm - 服务器在WWW-Authenticate响应标头中指定的字符串。包括主体散列-用于与 . 以外的 请求主体进行完整性检查的散列application/x-www-form-urlencoded。(当您使用回调 URL / 验证器时停用。)
如果您的 OAuth 1.0 服务器实现需要它,请选择Add empty parameters to signature。您还可以选中复选框以对请求的授权标头中的参数进行编码。
OAuth 2.0
使用 OAuth 2.0,您首先检索 API 的访问令牌,然后使用该令牌对未来的请求进行身份验证。使用 OAuth 2.0 访问数据在 API 服务提供商之间差异很大,但通常涉及客户端应用程序、用户和 API 之间的一些来回请求。
示例 OAuth 2.0 流程可以按如下方式运行:
- 客户端应用程序请求用户授权访问他们的数据。
- 如果用户授予访问权限,则应用程序会向服务提供商请求访问令牌,传递来自用户的访问权限和身份验证详细信息以识别客户端。
- 服务提供商验证这些详细信息并返回访问令牌。
- 客户端使用访问令牌向服务提供商请求用户数据。
要使用 OAuth 2.0,请执行以下操作:
- 在请求的授权选项卡中,从类型下拉列表中选择OAuth 2.0 。指定是否要在请求 URL 或标头中传递身份验证详细信息。默认情况下,Postman 会将访问令牌附加到Bearer您请求的授权标头中,但如果您的服务器实现需要不同的前缀,您可以在标头前缀字段中指定它。
- 要请求访问令牌,请填写Configure New Token部分中的字段,然后选择Get New Access Token。您可以保存令牌和详细信息以生成带有您的请求或集合的令牌。生成并添加令牌值后,它将出现在请求标头中。
- 输入您的客户端应用程序的详细信息,以及来自服务提供商的任何身份验证详细信息。这允许您在 Postman 中复制您的应用程序身份验证流程以测试经过身份验证的请求。 您可以通过选择可用令牌旁边的同步令牌图标与您的团队共享令牌凭据 。默认情况下,Postman 不会同步您的令牌,以防您不想共享它。
- Postman 将根据 OAuth 2.0授权类型提示您提供特定详细信息,可以是Authorization code、Implicit、Password credentials或Client credentials。
授权码
授权代码授予类型要求用户向提供者进行身份验证——然后将授权代码发送回客户端应用程序,提取并与提供者交换访问令牌以验证以后的请求。
要使用授权代码授予类型,请输入客户端应用程序的回调 URL(需要向 API 提供商注册),以及 API 服务提供的各种详细信息,包括Auth URL、Access Token URL、Client ID和Client Secret .
如果愿意,您可以在 Web 浏览器而不是 Postman 中输入您的授权详细信息,方法是选择Authorize using browser。
授权码(带 PKCE)
您可以将 PKCE(用于代码交换的证明密钥)与 OAuth 2.0 一起使用。当您选择Authorization Code (With PKCE)时,另外两个字段将可用于Code Challenge Method和Code Verifier。您可以选择使用SHA-256或Plain算法来生成代码挑战。验证器是一个可选的 43-128 字符的字符串,用于将授权请求连接到令牌请求。
建议使用授权码(使用 PKCE)授权类型与使用浏览器进行授权相结合,以防止授权码拦截攻击。
隐含的
隐式授权类型向客户端返回一个访问令牌,而不需要额外的授权代码步骤(因此安全性较低)。
要在 Postman 中对您的请求使用隐式授权类型,请输入您已向 API 提供商注册的回调 URL 、提供商Auth URL以及您已注册的应用程序的客户端 ID 。
如果愿意,您可以在 Web 浏览器而不是 Postman 中输入您的授权详细信息,方法是选择Authorize using browser。
密码凭据
OAuth 2.0 密码授予类型涉及直接从客户端发送用户名和密码,因此如果您正在处理第三方数据,则不推荐使用。
要使用密码授予类型,请输入您的 API 提供商的访问令牌 URL以及用户名和密码。在某些情况下,您还需要提供客户端 ID 和密码。
客户端凭据
客户端凭据授权类型通常不用于访问用户数据,而是用于与客户端应用程序关联的数据。
输入提供商的Access Token URL,以及您注册的应用程序的Client ID和Client Secret。
请求 OAuth 2.0 令牌
请求新访问令牌的完整参数列表如下,具体取决于您的授权类型。
在配置选项选项卡上:
- 令牌名称- 您要用于令牌的名称。
- 授权类型- 选项的下拉列表。这将取决于 API 服务提供商的要求。
- 回调 URL - 验证后重定向到的客户端应用程序回调 URL。这必须向 API 提供商注册。如果未提供,Postman 将使用默认的空 URL 并尝试从中提取代码或访问令牌。如果这对您的 API 不起作用,您可以使用以下 URL:https://oauth.pstmn.io/v1/browser-callback使用浏览器授权- 您可以在 Web 浏览器中输入您的凭据,而不是在使用授权代码或隐式授权类型时默认出现在 Postman 中的弹出窗口。选中此复选框以设置回调 URL以返回到 Postman。如果您选择使用浏览器授权,请确保回调 URL 的弹出窗口已停用,否则将无法使用。
- Auth URL - API 提供者授权服务器的端点,用于检索授权代码。
- 访问令牌 URL - 提供商的身份验证服务器,用于交换访问令牌的授权代码。
- 客户端 ID - 在 API 提供商处注册的客户端应用程序的 ID。
- 客户端密码- API 提供者提供给您的客户端密码。
- 范围- 您请求的访问范围,可能包括多个以空格分隔的值。
- State - 防止跨站点请求伪造的不透明值。
- 客户端身份验证- 在标头中发送基本身份验证请求,或在请求正文中发送客户端凭据。升级到新版本后,更改此处的值以避免客户端身份验证出现问题。
在高级选项选项卡上:
- 资源- 指示要使用令牌的资源或目标服务的 URI。
- 受众- 一个 URI,指示目标受众或服务将在其中使用令牌。
配置完成后,选择Get New Access Token。
当您使用授权代码或隐式授权类型时,系统将提示您提供凭据以检索访问令牌以在以后的请求中使用。默认情况下,当您选择Request Token时,Postman 将显示一个弹出式浏览器。您可以改为选择使用系统的默认 Web 浏览器进行身份验证。选择使用浏览器授权,当您在浏览器中完成身份验证时,回调 URL 将自动填充以返回给 Postman,以便您的请求可以使用身份验证成功后返回的令牌。
来自 API 的令牌包括其详细信息、到期时间和可选的刷新令牌,您可以在当前令牌到期时使用它来检索新的访问令牌。选择使用令牌以选择返回值。
任何成功检索到的令牌都将列在请求可用令牌下拉列表中。选择一个与您的请求一起发送。在下拉列表中选择管理令牌以查看更多详细信息或删除您的令牌。
如果身份验证失败或超时,Postman 将显示一条错误消息。您可以在控制台中检查错误详细信息,重试以再次尝试身份验证,或者在继续之前编辑您的身份验证详细信息。
在 Postman 中删除令牌不会撤销访问权限。只有颁发令牌的服务器才能撤销它。
刷新 OAuth 2.0 令牌
在 Postman 中生成的 OAuth 2.0 令牌过期之前,Postman 会在您发送使用它的请求之前自动在后台刷新它。刷新的访问令牌在使用它的任何请求中更新。自动刷新是默认行为。
要关闭或打开此功能,请选择自动刷新访问令牌。要手动刷新令牌,请选择Refresh。如果令牌在第二天到期,则会显示令牌的到期时间。
存在刷新令牌时可以使用自动刷新。如果不存在刷新令牌,则自动刷新访问令牌切换和手动刷新选项不可用。要检查是否存在刷新令牌,请在令牌下拉列表中选择管理令牌。如果不存在刷新令牌,请检查授权服务。没有刷新令牌,邮递员无法刷新访问令牌。
您可以在手动发送请求时使用自动刷新。自动刷新不用于同一集合的计划运行或监视器。
共享 OAuth 2.0 访问令牌
要使其他 Postman 用户能够查看和使用 OAuth 2.0 访问令牌,请选择共享访问令牌。
要撤销其他用户对同步令牌的访问权限,请执行以下操作:
- 关闭共享访问令牌。
- 选择删除同步令牌。
在您撤销访问权限后,有权访问该请求的其他用户将无法查看或使用该令牌。
更改 OAuth 2.0 令牌类型
Postman 支持使用访问令牌或 ID 令牌进行 OAuth 2.0 授权。访问令牌使 OAuth 客户端能够调用 API。ID令牌包含有关经过身份验证的用户的信息。OAuth 客户端可以使用此信息来定制他们的体验。
如果存在 ID 令牌,您可以在使用令牌类型下拉列表中选择令牌类型(访问令牌或ID 令牌)。如果不存在 ID 令牌,则此下拉列表不可用。要检查 ID 令牌是否存在,请在令牌下拉列表中选择管理令牌。
霍克认证
Hawk 身份验证使您能够使用部分加密验证来授权请求。
要使用 Hawk 身份验证,请执行以下操作:
- 在请求的授权选项卡中,从类型下拉列表中选择Hawk 身份验证。
- 在Hawk Auth ID、Hawk Auth Key和Algorithm字段中输入您的详细信息。您可以选择设置高级详细信息,但 Postman 会在必要时尝试为它们生成值。
当您的请求的Authorization选项卡中的所需详细信息完成后,Postman 会将它们添加到 Headers中。
Hawk认证参数如下:
- Hawk Auth ID - 您的 API 身份验证 ID 值。
- Hawk Auth Key - 您的 API 身份验证密钥值。
- 算法- 用于创建消息验证代码 (MAC) 的哈希算法。
- 高级参数:用户- 用户名。Nonce - 客户端生成的随机字符串。ext - 与请求一起发送的任何特定于应用程序的信息。app - 凭据和应用程序之间的绑定,以防止攻击者使用颁发给其他人的凭据。dlg - 凭据颁发给的应用程序的 ID。时间戳- 服务器用来防止时间窗口外的重放攻击的时间戳。
AWS 签名
AWS 是 Amazon Web Services 请求的授权工作流程。AWS 使用基于键控 HMAC(哈希消息身份验证代码)的自定义 HTTP 方案进行身份验证。
官方 AWS 签名文档提供了更多详细信息:
要使用 AWS 签名,请执行以下操作:
- 在请求的授权选项卡中,从类型下拉列表中选择AWS 签名。
- 使用Add authorization data to下拉列表,选择请求标头或 URL,选择 Postman 将附加您的 AWS 身份验证详细信息的位置。如果您选择Request Headers ,Postman 将在Headers选项卡中添加Authorization和X-Amz-前缀字段。如果您选择Request URL ,Postman 将在Params中添加 auth 详细信息,并以 keys 为前缀X-Amz-。
- 直接在字段中输入您的访问密钥和秘密值。为了额外的安全性,您可以为这些值使用秘密变量。
- 您可以选择设置高级字段,但 Postman 会在必要时自动生成这些字段。
AWS 签名参数如下:
- AWS 区域- 接收请求的区域(默认为us-east-1)。
- 服务名称- 接收请求的服务。
- 会话令牌- 仅在使用临时安全凭证时需要。
NTLM 身份验证
Windows 质询/响应 (NTLM) 是 Windows 操作系统和独立系统的授权流程。
要使用 NTLM 身份验证,请执行以下操作:
- 在请求的授权选项卡中,从类型下拉列表中选择NTLM 身份验证。
- 输入用于 NTLM 访问的用户名和密码(使用变量以避免直接输入值)。您可以选择指定高级参数,但 Postman 会在必要时尝试自动完成这些参数。默认情况下,您的请求将在提取第一次收到的数据后运行第二次。您可以通过选中复选框来关闭此行为。
NTLM auth 的高级参数如下:
- 域- 要进行身份验证的域或主机。
- 工作站- PC 的主机名。
Akamai EdgeGrid
Akamai EdgeGrid 是 Akamai 开发和使用的授权助手。
要使用 Akamai EdgeGrid,请执行以下操作:
- 在请求的授权选项卡中,从类型下拉列表中选择Akamai EdgeGrid 。
- 输入您的Access Token、Client Token和Client Secret,使用变量以提高安全性——当您向 Akamai 注册客户端应用程序时,您将收到这些详细信息。
当您的请求的Authorization选项卡中的所需详细信息完成后,Postman 会将它们添加到 Headers中。
有关获取凭据的信息,请参阅Akamai 开发人员 - 授权您的客户端。
同步 cookie
如果您的浏览器中有会话 cookie,您可以使用拦截器将它们同步到 Postman。有关详细信息,请参阅拦截器扩展和Cookie 。
故障排除
如果您在获取请求以进行身份验证并成功运行时遇到问题,请查看API 请求故障排除中的提示。如果您仍然有身份验证问题,请查看Postman 论坛上的身份验证标签。