授权 OAuth 应用程序

GitHub Enterprise Server 的 OAuth 实现支持� �准授权代� �授予类型以及 OAuth 2.0 设备授权授予（针对� 法访问 web 浏览器的应用程序）。

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

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

• Web 应用程序流程：用于授权在浏览器中运行� �准 OAuth 应用程序的用户。 （不支持 隐含的授予类型。）

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://127.0.0.1/path 回调 URL，您可以使用此 redirect_uri：

http://127.0.0.1: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 向验证身份”