要使用 Github 的 OAuth 2.0 服务登录第三方网站,你一般需要进行以下 3 步的操作配置:
- 在 Github 开发者后台创建一个应用,在应用里配置重定向地址(回调地址),以获取客户端 ID(Client ID) 和客户端密钥(Client Secret)。
- 根据客户端 ID、客户端密钥和回调地址构造登录页面,让用户授权,以获取访问令牌(Token)。
- 有了访问令牌就能够访问 Github 的开放资源。
在开始之前,我们先来了解一下什么是 OAuth 2.0?
什么是 OAuth 2.0?
OAuth 2.0 是一种开放标准的授权协议,用于授权第三方应用程序访问受保护的资源,而无需用户提供其用户名和密码。它允许用户通过授权代理向第三方应用程序颁发访问令牌(access token),以访问特定的资源。OAuth 2.0 的核心概念包括授权服务器(Authorization Server)、资源所有者(Resource Owner)、客户端(Client)、资源服务器(Resource Server)和访问令牌(Access Token)。OAuth 2.0 被广泛应用于 Web 和移动应用程序中,提供了安全的授权机制,同时保护用户的隐私。
OAuth 2.0 协议涉及以下角色:
- 资源所有者(Resource Owner):通常是用户,拥有受保护的资源,例如图片、个人资料等。
- 客户端(Client):第三方应用程序,想要访问资源所有者的受保护资源。
- 授权服务器(Authorization Server):负责认证资源所有者并授权客户端访问资源的服务器。
- 资源服务器(Resource Server):存储受保护资源的服务器,提供访问受保护资源的 API。
OAuth 2.0 协议通过授权流程(Authorization Flow)来实现授权。其中,常见的授权流程包括:
- 授权码授权流程(Authorization Code Grant):客户端重定向用户到授权服务器,用户登录并授权后,授权服务器返回授权码给客户端,客户端使用授权码与客户端凭证交换访问令牌。
- 授权码授权流程,带有 PKCE (Authorization Code Grant,With PKCE):与标准授权码模式相同,但客户端需要使用 PKCE(Proof Key for Code Exchange)来增强安全性。
- 密码授权流程(Resource Owner Password Credentials Grant):资源所有者直接将用户名和密码提供给客户端,客户端使用这些凭据向授权服务器请求访问令牌。
- 客户端凭证授权流程(Client Credentials Grant):客户端使用自己的凭据直接向授权服务器请求访问令牌,适用于客户端自身需要访问资源的情况。
- 隐式授权流程(Implicit Grant):用于在浏览器中直接从客户端获得访问令牌,通常用于 Web 前端应用。
Github 使用的 OAuth 2.0 授权流程就是“授权码授权流程(Authorization Code Grant)”,下面就来介绍一下怎么实现,并讲述如何在 Apifox 中调试。
步骤 1:创建应用,获取客户端 ID 和客户端密钥
要获取客户端 ID 和客户端密钥,我们首先要创建一个应用,点击这个链接在 Github 里创建一个:https://github.com/settings/applications/new
,然后在“Homepage URL”这里填写你的域名,如果是本地调试,可以填写你的本地服务,比如http://127.0.0.1:8000
。
在“Authorization callback URL”这里填写你的回调地址,可以是你的域名,也可以是你本地的回调地址,比如http://127.0.0.1:8000/callback
。相关配置填写之后,点击“Register application”创建即可。
应用创建完毕,会生成客户端 ID 和客户端密钥。客户端密钥需要单独生成,点击“Generate a new client secret”生成一个密钥即可。
步骤 2:获取访问令牌
当上文的第一步准备好以后,我们就可以去申请访问令牌(Token),获取访问令牌这一步,我们通过 Apifox 来演示,Apifox 是一款非常优秀的接口调试、管理工具,你可以在 Apifox 中直接获取到 Token 访问令牌。如果你还没有安装 Apifox,现在就去下载一个吧!
1.新建 HTTP 请求
在 Apifox 中新建一个 HTTP 项目后打开,然后在项目里新建一个请求,并选择【修改文档 -> Auth -> OAuth 2.0】选项。
2.配置客户端 ID、客户端密钥和重定向地址
Apifox 中 OAuth 2.0 页面默认选择的授权模式为 Authorization Code(授权码模式),因为 Github OAuth 2.0 用的也是 Authorization Code(授权码模式),所以这里你无需进行切换。
接着在页面下方找到 Client ID、Client Secret 和 Callback URL,将从 Github 的 OAuth 2.0 服务中获取到的客户端 ID(Client ID) 、客户端密钥(Client Secret)以及配置的回调地址(Callback URI)填进去即可,具体参数就是上文在“步骤 1”中的配置。
3.配置授权码的请求地址
根据 Github 官方文档的描述,在进行 OAuth 2.0 认证时,授权码的请求地址(Auth URL)是:
https://github.com/login/oauth/authorize
将这个授权码的请求地址填写到 Auth URL 里即可,这个地址我们可以把它理解为登录授权页面,在首次校验登录状态时会打开这个页面(在客户端是窗口),然后让你填写用户名和密码。
一般在手动构造登录授权页面的时候,这个授权地址的后面还需要携带一些参数,比如像下面这样的:
https://github.com/login/oauth/authorize?
client_id=${clientId}&
redirect_uri=http%3A%2F%2F127.0.0.1%3A8000%2Fcallback&
scope=user:email
注:正常情况下无需进行参数换行,http%3A%2F%2F127.0.0.1%3A8000%2Fcallback
是http://127.0.0.1:8000/callback
转换成 urlencode 格式的样子。
但是,在 Apifox 中,URL 后面的参数一般就不需要携带了,只要问号?
前面的路径就行,因为其它必填参数已单独在其它选项中配置,当然如果你想携带一些 Query 参数,你也可以加上,点击该输入框后面的图标即可添加:
我们也可以展开“更多”选项,将需要填写的参数值填写到对应的选项里,比如 “Scope” 里就可以填需要的权限,如read:user
、user:email
等,其它更多权限你可以访问 Github 帮助文档的权限模块查看。在“State”选项中填写state
,State 是为了防止跨站请求伪造。
4.配置访问令牌的请求地址
根据 Github 官方文档的描述,要申请到访问令牌,需要请求的 URL 为:
https://github.com/login/oauth/access_token
将上面这个地址填写到 Apifox 的 OAuth 2.0 页面的 Access Token URL 输入项内即可。
因为在默认情况下,Github 在返回访问令牌时,它的返回响应采用以下的格式:
access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer
这个格式目前在 Apifox 中不能自动解析,所以你需要在请求头中添加Accept: application/json
,这样子返回响应就是 JSON 格式了,如下图所示:
5.获取 Github OAuth 2.0 服务的访问令牌
上文的配置项都设置好以后,就可以点击“获取 Token”按钮来获取访问令牌了。点击后,如果是初次登录,会弹出一个窗口让你授权,填写你的 Github 账户的用户名以及密码即可。
填写完用户名密码后,会让你确认授权,或者进行两步验证,验证过后,点击确认即可。授权完成后,就会自动获取到访问令牌,并显示在页面上,同时,会将 Github 返回的其它信息也一并解析出来,如下图所示。这里显示“已过期”是因为 Github 没有给我们返回expires_in
这个属性,所以没法做判断,但是这个 Token 是能用的,我们下面就来发起一个请求。
注意,如果你开了代理,你需要到“设置”里把代理打开,不然有可能会连接失败。遇到其它错误,你可以检查一下是不是某些第三方平台需要的必填参数没有填写,修改错误后,点击“清除 Cookie”并重新获取 Token 即可。
步骤 3:根据 Token 访问开放资源
有了访问令牌(Token)之后,你就可以拿这个访问令牌调取 Github 的开放资源了,具体有什么样的开放资源,可以在 Github API 中查看。比如下面这个 API 就获取了用户的信息。如果你的接口没有返回,那么需要看看有没有权限,在“步骤 2”的第 3 小节有讲到,给它配置到 Scope 里就行了。
https://api.github.com/user
发送请求时 Apifox 会自动将 Token 附加到请求头的Authorization
中,添加至Bearer
后发送出去。如果你要将 Token 携带在 URL 上,你也可以在页面的配置项中修改 Token 的“添加位置”,将其选择为“Query Params”即可。
总结
OAuth 2.0 是一种授权框架,允许第三方应用获取访问令牌而无需用户提供用户名密码。GitHub 使用的授权流程是“授权码授权流程”,其授权过程可以在 Apifox 中调试配置。
使用 GitHub 的 OAuth 2.0 服务登录第三方网站一般需要以下三步操作配置:1. 在 GitHub 开发者后台创建应用,配置重定向地址以获取客户端 ID 和密钥。2. 根据 ID、密钥和重定向地址构造登录页面,用户授权后获取访问令牌。3. 有了令牌即可访问 GitHub 的开放资源。