使用 Apifox 配置 OAuth 2.0 并直接获取访问令牌

Apifox 2.5.15 及以上版本已支持根据 OAuth 2.0 协议规范直接获取访问令牌，无需在其它工具中生成后再粘贴过来。

Apifox 支持 OAuth 2.0 协议定义的五种常见授权模式，它们分别如下：

在众多授权模式中，最常见和最经典的授权模式是 Authorization Code（授权码模式），接下来，我们将以阿里云 OAuth 2.0 登录为例，在 Apifox 中详细介绍如何配置该模式。在正式开始实践之前，我们先来温习一下什么是 OAuth 2.0！

什么是 OAuth 2.0？

OAuth 2.0 是一种授权框架，它可以让第三方应用程序在得到你的授权后，有限度地访问一些开放的个人信息。

OAuth 2.0 的运行流程可以用下图表示，其中，客户端代表一方，用户为另一方，认证服务器与资源服务器统一作为一方。

在实际应用中，我们可以简化为 3 步来理解：

1. 获取授权码（code）：比如你在一个网站中使用微信扫码登录，这就是一种授权，这一步可以让客户端拿到授权码（code）
2. 根据授权码向第三方平台的 OAuth 2.0 服务申请访问令牌（Token）：客户端使用授权码向认证服务器申请访问令牌，这个令牌允许客户端在一段时间内访问用户的受保护资源。
3. 根据令牌（Token）获取第三方平台的开放资源：客户端使用获得的访问令牌去访问资源服务器，以获取用户授权范围内的受保护资源。

用一条公式来简化，可以简单表示为：授权码（code）+ 访问令牌（Token）= 开放资源。这个公式概括了整个 OAuth 2.0 的主流程，即通过授权码获取访问令牌，然后利用令牌去访问开放资源。

我们将通过一个阿里云 OAuth 2.0 登录的例子来进一步实践一下，并讲述如何在 Apifox 中调试。

授权码模式的鉴权：以阿里云 OAuth 2.0 登录为例

步骤 1：获取客户端 ID 和客户端密钥

我们首先需要到 OAuth 2.0 服务提供者的后台获取到客户端 ID（Client ID）和客户端密钥（Client Secret），在阿里云中，你需要到 RAM控制台新建一个 OAuth 应用，里面的应用 ID 就是客户端 ID（Client ID）。

然后在应用中，创建一个密钥，创建时显示的AppSecretValue就是客户端密钥（Client Secret），只显示一次，记得保存好，忘记了需要重新生成。

当客户端 ID 和客户端密钥有了之后，我们可以在 Apifox 中先配置这两个信息。打开任一接口（或目录），选择「修改文档 -> Auth -> OAuth 2.0」选项。

Apifox 中 OAuth 2.0 默认选择的授权模式为 Authorization Code（授权码模式），本例就是用的这个模式，所以无需在页面配置项中进行更改。在下方找到 Client ID 和 Client Secret，将从阿里云中获取到的应用 ID 和密钥分别填进去即可。

步骤 2：配置授权码的请求地址

根据阿里云官方文档的描述，在进行 OAuth 2.0 认证时，授权码的请求地址（Auth URL）是：

https://signin.aliyun.com/oauth2/v1/auth

将这个授权码的请求地址填写到 Auth URL 里即可，这个地址我们可以把它理解为登录授权页面，在首次校验登录状态时会打开这个页面（在客户端是窗口），然后让你填写用户名和密码。

一般在手动构造登录授权页面的时候，这个授权地址的后面还需要携带一些参数，比如像这样的：

https://signin.aliyun.com/oauth2/v1/auth?
client_id=123****&
redirect_uri=https://example.com/authcallback/&
response_type=code&
scope=openid /acs/ccc&
access_type=offline&
state=123456****

注：正常情况下无需进行参数换行

但是，在 Apifox 中，后面的参数一般就不需要了，只要问号?前面的路径就行，因为其它必填参数已单独在其它选项中配置，当然如果你想携带一些 Query 参数，你也可以加上，点击该输入框后面的图标即可添加：

步骤 3：配置回调地址

回调地址（Callback URL）一般是自己的服务器的一个地址，这个地址需要配置到 OAuth 2.0 服务提供者的后台，开发时一般使用本地服务器（比如：http://127.0.0.1:8080/callback）。在阿里云中，点击“编辑基本信息”并填入回调地址即可。

我们需要“回调地址”的目的是为了获取到地址栏上的授权码（code），在上文的“步骤二”中，我们在登录页填写完用户名密码后，就会重定向到“回调地址”，并能在地址栏中获取授权码（code）。形如下面这个用手动的方式获取 code 值的地址栏：

OAuth 2.0 服务提供者后台里填写的回调地址是什么，我们在 Apifox 中就填上对应的回调地址（Callback URL）。

需要注意的是，如果你用的是 Apifox 的网页端，那么必须将 OAuth 2.0 服务提供者后台的回调地址指定为https://app.apifox.com/oauth2-browser-callback.html，同样该地址也需要在 Apifox 中填写，否则重定向会失败，就获取不到授权码（code）了。

步骤 4：配置访问令牌的请求地址

根据阿里云官方文档的描述，使用授权码（code）向阿里云 OAuth 2.0 服务申请访问令牌（Token）时，它的请求地址为：

https://oauth.aliyun.com/v1/token

将这个访问令牌的请求地址填写到 Access Token URL 里即可。

步骤 5：获取令牌与使用

最后，当客户端 ID（Client ID）、客户端密钥（Client Secret）、授权码的请求地址（Auth URL）、回调地址（Callback URL）和访问令牌的请求地址（Access Token URL）都配置完毕后，我们就可以点击“获取 Token”按钮来调试了，点击后会弹出一个授权登录框，你可以在这里填写用户名密码，或者通过手机扫码的方式来登录。

填写用户名密码后，点击登录，你会看到 Token 已成功获取。

获取 Token 成功后，界面上会展示 Token 内容及其有效期。

有了 Token 后就可以在接口中发送请求，已生成的 Token 会自动附加到请求头的Authorization 中，添加至Bearer 后发送出去。

如果你要将 Token 携带在 URL 上，你也可以在页面的配置项中修改 Token 的“添加位置”，将其选择为“Query Params”即可。

至此，我们通过“阿里云 OAuth 2.0 登录”的例子，从头跑了一遍流程，最终成功获取了 Token，一般必要的操作以及配置项就是上文所述步骤的内容，其它的可用配置项请见下文。

其它配置项

在 Token 返回后，Apifox 会自动解析 OAuth 2.0 服务返回的其它信息，比如阿里云的 OAuth 2.0 服务会返回以下的字段：

在 Apifox 中，会自动将这些返回的字段解析出来，你可以点击 Token 后面的小眼睛查看：

如果 OAuth 2.0 服务同时返回了Access Token和ID Token，Apifox 会默认使用Access Token。如果希望切换至ID Token，那么可以在“使用的 Token 类型”选项中切换至ID Token。

如果 OAuth 2.0 服务返回了 Refresh Token，将会出现「刷新 Token」按钮。当 Token 过期了，点击“刷新 Token” 按钮即可直接获取新的 Token，而不会弹出登录窗口。

OAuth 2.0 服务的登录页面会记录用户的登录状态，重新获取 Token 时默认会使用上一次登录的账号。若希望更换账号，则可以点击“清除 Cookies”按钮，再点击“获取 Token”。

你还可以点击“更多”选项添加更多加密设置。如果配置留空，它们会自动生成。

以下是各个配置项的解释：

注意事项

Apifox 现支持根据 OAuth 2.0 标准协议规范获取 Token，这意味着只有当第三方平台的 OAuth 2.0 认证也遵循标准的协议规范时，才能成功获取 Token，否则会失败。

目前国内许多平台提供的 OAuth 2.0 认证流程并未完全遵循协议规范，它们更注重只要能通过代码获取到 Token 就行，但是获取到 Token 之前需要践行的配置规范往往自成一派，所以你在 Apifox 中调试的时候会遇到报错。

针对这种情况，我们推荐你用手动的方式来构造登录页面，也就是配置“授权码的请求地址”，当请求地址在网页中成功重定向并获得授权码（code）后，再使用 Apifox 来发送获取 Token 的请求，这种方法虽然稍显繁琐，但能有效解决问题。具体操作方法，可参考这篇文章《如何使用 Apifox 调试 OAuth 2.0 鉴权的接口：以微信登录为例》，该文是在 Apifox 尚未直接支持 OAuth 2.0 调试功能时编写的。

总结

OAuth 2.0 鉴权流程归纳如下：

1. 获取客户端 ID 和客户端密钥：在 OAuth 2.0 服务提供者后台获取。
2. 配置授权码请求地址：填写 OAuth 2.0 服务提供者的授权码请求地址，如阿里云的https://signin.aliyun.com/oauth2/v1/auth。
3. 配置回调地址：设置回调地址，获取授权码。
4. 配置访问令牌请求地址：填写访问令牌的请求地址，如阿里云的https://oauth.aliyun.com/v1/token。
5. 获取令牌与使用：在 Apifox 中，点击“获取 Token”按钮，填写登录信息或扫码登录，获取 Token 后即可发送请求。
   额外配置项包括 Scope、State、Credentials 等，注意，Apifox 支持标准 OAuth 2.0 协议规范，若第三方平台 OAuth 2.0 认证未遵循规范，可能无法成功获取 Token。建议如遇问题，手动构造登录页面后再使用 Apifox 发送获取 Token 的请求。

学习更多 OAuth 2.0 知识：

• 非标准 OAuth 2.0 授权模式：如何使用钉钉的 OAuth 2.0 服务进行登录并获取 Token？图文教程
• OAuth 2.0 隐式模式（Implicit）：使用 Google 谷歌 OAuth 2.0 服务登录第三方网站，图文教程
  

参考链接：

• 阿里云官方文档：通过 OAuth 2.0 扮演登录用户访问阿里云 API
• RFC 6749：The OAuth 2.0 Authorization Framework

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！