授权 OAuth 应用程序

GitHub Enterprise Server's OAuth implementation supports the standard authorization code grant type and the OAuth 2.0 Device Authorization Grant for apps that don't have access to a web browser.

如果您想要跳过以标准方式授权应用程序，例如测试应用程序时， 您可以使用非 web 应用程序流程。

要授权您的 OAuth 应用程序，请考虑哪个授权流程最适合您的应用程序。

• Web 应用程序流程：用于授权在浏览器中运行标准 OAuth 应用程序的用户。 (The implicit grant type is not supported.)

Web 应用程序流程

授权应用程序用户的 web 应用程序流程是：

1. 用户被重定向，以请求他们的 GitHub 身份
2. 用户被 GitHub 重定向回您的站点
3. 您的应用程序使用用户的访问令牌访问 API

1. 请求用户的 GitHub 身份

GET http(s)://[hostname]/login/oauth/authorize

当您的 GitHub 应用程序指定 login 参数后，它将提示拥有特定账户的用户可以用来登录和授权您的应用程序。

参数

名称	类型	描述
client_id	字符串	必填。 您registered 时从 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&scope=repo%2Cgist&token_type=bearer

You can also receive the response in different formats if you provide the format in the Accept header. For example, Accept: application/json or Accept: application/xml:

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 身份验证适用于测试等有限的情况。 如果您需要，可以使用基本验证，通过个人访问令牌设置页面创建个人访问令牌。 此方法支持用户随时撤销访问权限。

重定向 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 应用程序访问权限。

每个用户/应用程序/作用域组合签发的令牌数量有限。 If an application creates more than 10 tokens for the same user and the same scopes, the oldest tokens with the same user/application/scope combination will be revoked.

指示用户审查其访问权限

您可以链接至 OAuth 应用程序的授权信息，以便用户审查和撤销其应用程序授权。

要构建此链接，需要使用注册应用程序时从 GitHub 收到的 OAuth 应用程序 client_id。

http(s)://[hostname]/settings/connections/applications/:client_id

疑难解答

• "对授权请求错误进行故障排除"
• "对 OAuth 应用程序访问令牌请求错误进行故障排除"

延伸阅读

• “关于 GitHub 向验证身份”