GitHub Enterprise Server 的 OAuth 实现支持标准授权代码授予类型。
如果您想要跳过以标准方式授权应用程序,例如测试应用程序时, 您可以使用非 web 应用程序流程。
对于在浏览器中运行的标准应用程序,请使用 web 应用程序流程获取授权代码并将其更换为令牌。 (不支持隐式授予类型。)
Web 应用程序流程
注:如果您要构建 GitHub 应用程序,依然可以使用 OAuth web 应用程序流程,但设置方面有一些重要差异。 更多信息请参阅“识别和授权 GitHub 应用程序用户”。
授权应用程序用户的 web 应用程序流程是:
- 用户被重定向,以请求他们的 GitHub 身份
- 用户被 GitHub 重定向回您的站点
- 您的应用程序使用用户的访问令牌访问 API
1. 请求用户的 GitHub 身份
GET http(s)://[hostname]/login/oauth/authorize
当您的 GitHub 应用程序指定 login
参数后,它将提示拥有特定账户的用户可以用来登录和授权您的应用程序。
参数
名称 | 类型 | 描述 |
---|---|---|
client_id | 字符串 | 必填。 您注册 时从 GitHub 收到的客户端 ID。 |
redirect_uri | 字符串 | 用户获得授权后被发送到的应用程序中的 URL。 有关重定向 url,请参阅下方的详细信息。 |
login | 字符串 | 提供用于登录和授权应用程序的特定账户。 |
作用域 | 字符串 | 用空格分隔的作用域列表。 如果未提供,对于未向应用程序授权任何作用域的用户,scope 将默认为空白列表。 对于已向应用程序授权作用域的用户,不会显示含作用域列表的 OAuth 授权页面。 相反,通过用户向应用程序授权的作用域集,此流程步骤将自动完成。 例如,如果用户已执行两次 web 流程,且授权了一个拥有 user 作用域的令牌和一个拥有 repo 作用域的令牌,未提供 scope 的第三次 web 流程将收到拥有 user 和 repo 作用域的令牌。 |
state | 字符串 | 不可猜测的随机字符串。 它用于防止跨站请求伪造攻击。 |
allow_signup | 字符串 | 在 OAuth 流程中,是否向经过验证的用户提供注册 GitHub 的选项。 默认值为 true 。 如有政策禁止注册,请使用 false 。 |
2. 用户被 GitHub 重定向回您的站点
如果用户接受您的请求,GitHub Enterprise Server 将重定向回您的站点,其中,代码参数为临时 code
,state
参数为您在上一步提供的状态。 临时代码将在 10 分钟后到期。 如果状态不匹配,然后第三方创建了请求,您应该中止此过程。
用此 code
换访问令牌:
POST http(s)://[hostname]/login/oauth/access_token
参数
名称 | 类型 | 描述 |
---|---|---|
client_id | 字符串 | 必填。您从 GitHub Enterprise Server 收到的 OAuth 应用程序 的客户端 ID。 |
client_secret | 字符串 | 必填。您从 GitHub Enterprise Server 收到的 OAuth 应用程序 的客户端密钥。 |
代码 | 字符串 | 必填。您收到的响应第 1 步的代码。 |
redirect_uri | 字符串 | 用户获得授权后被发送到的应用程序中的 URL。 |
响应
默认情况下,响应采用以下形式:
access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer
您也可以根据“接受”标头接收不同格式的内容:
Accept: application/json
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "scope":"repo,gist", "token_type":"bearer"}
Accept: application/xml
<OAuth>
<token_type>bearer</token_type>
<scope>repo,gist</scope>
<access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
</OAuth>
3. 使用访问令牌访问 API
访问令牌可用于代表用户向 API 提出请求。
Authorization: token OAUTH-TOKEN
GET http(s)://[hostname]/api/v3/user
例如,您可以像以下这样在 curl 中设置“授权”标头:
curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3/user
非 Web 应用程序流程
非 web 身份验证适用于测试等有限的情况。 如果您需要,可以使用基本验证,通过个人访问令牌设置页面创建个人访问令牌。 此方法支持用户随时撤销访问权限。
注:使用非 web 应用流程创建 OAuth2 令牌时,如果您或您的用户已启用双重身份验证,请确保明白如何使用双重身份验证。
重定向 URL
redirect_uri
参数是可选参数。 如果遗漏,GitHub 则将用户重定向到 OAuth 应用程序设置中配置的回调 URL。 如果提供,重定向 URL 的主机和端口必须完全匹配回调 URL。 重定向 URL 的路径必须引用回调 URL 的子目录。
CALLBACK: http://example.com/path
GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
BAD: http://example.com/bar
BAD: http://example.com/
BAD: http://example.com:8080/path
BAD: http://oauth.example.com:8080/path
BAD: http://example.org
本地主机重定向 URL
可选的 redirect_uri
参数也可用于本地主机 URL。 如果应用程序指定 URL 和端口,授权后,应用程序用户将被重定向到提供的 URL 和端口。 redirect_uri
不需要匹配应用程序回调 url 中指定的端口。
对于 http://localhost/path
回调 URL,您可以使用此 redirect_uri
:
http://localhost:1234/path
为 OAuth 应用程序创建多个令牌
您可以为用户/应用程序/作用域组合创建多个令牌,以便为特定用例创建令牌。
如果您的 OAuth 应用程序支持一个使用 GitHub 登录且只需基本用户信息的工作流程,此方法将非常有用。 另一个工作流程可能需要访问用户的私有仓库。 您的 OAuth 应用程序可以使用多个令牌为每个用例执行 web 流程,只需要所需的作用域。 如果用户仅使用您的应用程序登录,则无需向他们的私有仓库授予您的 OAuth 应用程序访问权限。
每个用户/应用程序/作用域组合签发的令牌数量有限。 如果应用程序请求足够的令牌超越其中一个限制,所请求的作用域相同的旧令牌将停止工作。
警告: 从 OAuth 应用程序 撤销所有权限将会删除应用程序代表用户生成的 SSH 密钥,包括部署密钥。
指示用户审查其访问权限
您可以链接至 OAuth 应用程序的授权信息,以便用户审查和撤销其应用程序授权。
要构建此链接,需要使用注册应用程序时从 GitHub 收到的 OAuth 应用程序 client_id
。
http(s)://[hostname]/settings/connections/applications/:client_id
提示:要详细了解您的 OAuth 应用程序可以为用户访问的资源,请参阅“为用户发现资源。”