我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

此版本的 GitHub Enterprise 将停止服务 此版本的 GitHub Enterprise 已停止服务 2020-08-20. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

文章版本: Enterprise Server 2.18

使用 GitHub 应用程序进行身份验证

You can authenticate as a GitHub 应用程序 or as an installation.

本文内容

Note: To access the API with your GitHub App, you must provide a custom media type in the Accept Header for your requests.

application/vnd.github.machine-man-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact 您的 GitHub Enterprise 站点管理员.

生成私钥

创建 GitHub 应用程序 后,您需要生成一个或多个私钥。 私钥可用于签署访问令牌请求。

您可以创建多个私钥,然后轮流使用,以防某个私钥被盗或丢失造成停工。 要验证私钥是否与公钥匹配,请参阅验证私钥

要生成私钥:

  1. 在任何页面的右上角,单击您的个人资料照片,然后单击 Settings(设置)
    用户栏中的 Settings 图标
  2. 在左侧边栏中,单击 Developer settings
    Developer settings 部分
  3. In the left sidebar, click GitHub Apps.
    GitHub Apps 部分
  4. Select the GitHub App you want to modify.
    App selection
  5. 在“Private keys(私钥)”中,单击 Generate a private key(生成私钥)
    生成私钥
  6. 您将看到一个以 PEM 格式下载至您的计算机的私钥。 确保将此文件存储下来,因为 GitHub 仅存储密钥的公共部分。

注:如果您使用的库需要特定文件格式,您下载的 PEM 文件将呈现为 PKCS#1 RSAPrivateKey 格式。

验证私钥

GitHub Enterprise 使用 SHA-1 哈希函数为每对私钥和公钥生成指纹。 您可以生成私钥指纹,然后与 GitHub Enterprise 显示的指纹相比较,以验证私钥是否与 GitHub Enterprise 上存储的公钥匹配。

要验证私钥:

  1. 在 GitHub 应用程序 开发者设置页面的“私钥”部分,查找要验证的私钥和公钥对的指纹。 更多信息请参阅生成私钥
    私钥指纹
  2. Generate the fingerprint of your private key (PEM) locally by using the following command:
    $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha1 -c
  3. 比较本地生成的指纹结果与 GitHub Enterprise 中显示的指纹。

删除私钥

您可以通过删除功能删除丢失或被盗的私钥,但至少必须有一个私钥。 如果只有一个密钥,需要生成一个新钥,然后才能删除旧钥。 删除最后一个私钥

验证为 GitHub 应用程序

通过验证为 GitHub 应用程序,您可以执行以下操作:

  • 检索关于您的 GitHub 应用程序 的高级管理信息。
  • 为应用程序安装申请访问令牌。

要验证为 GitHub 应用程序,请以 PEM 格式生成私钥,并将其下载到本地机器上。 您可以使用此密钥签署 JSON Web 令牌 (JWT),然后用 RS256 算法为它编码。 GitHub Enterprise 将使用应用程序存储的公钥验证令牌,以检查请求是否已通过身份验证。

下面是一段快速 Ruby 脚本,可用于生成 JWT。 请注意,您必须先运行 gem install jwt,然后才能使用。

require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt

# Private key contents
private_pem = File.read(YOUR_PATH_TO_PEM)
private_key = OpenSSL::PKey::RSA.new(private_pem)

# Generate the JWT
payload = {
  # issued at time
  iat: Time.now.to_i,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub 应用程序's identifier
  iss: YOUR_APP_ID
}

jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

YOUR_PATH_TO_PEMYOUR_APP_ID 是必须替换的值。

使用 GitHub 应用程序 的标识符 (YOUR_APP_ID) 作为 JWT iss(签发者)申请的值。 您可以在创建应用程序后通过初始 web 挂钩,或随时从 GitHub.com UI 的应用程序设置页面获取 GitHub 应用程序 标识符。

创建 JWT 后,在 API 请求的 Header 中对它进行设置。

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github.machine-man-preview+json" http(s)://[hostname]/api/v3/app

YOUR_JWT 是必须替换的值。

上述示例所用的最大到期时间为 10 分钟,到期后,API 将开始返回 401 错误。

{
  "message": "'Expiration' claim ('exp') must be a numeric value representing the future time at which the assertion expires.",
  "documentation_url": "https://developer.github.com/enterprise/2.18/v3"
}

到期后,您需要创建新 JWT。

作为 GitHub 应用程序 访问 API 端点

有关获取关于 GitHub 应用程序 的高级信息所用的 REST API 端点列表,请参阅“GitHub 应用程序。”

验证为安装

通过验证为安装,您可以在 API 中为此安装执行操作。 验证为安装之前,必须创建安装访问令牌。 这些安装访问令牌由 GitHub 应用程序 用于进行身份验证。

默认情况下,安装访问令牌的作用域为安装可访问的所有仓库。 您可以使用 repository_ids 参数将安装访问令牌的作用域限定于特定仓库。 See the Create an installation access token for an app endpoint for more details. 安装访问令牌具有由 GitHub 应用程序 配置的权限,一个小时后到期。

要创建安装访问令牌,请在 API 请求的“授权”标头中加入上文生成的 JWT:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
http(s)://[hostname]/api/v3/app/installations/:installation_id/access_tokens

响应将包括您的安装访问令牌、到期日期、令牌权限及令牌可访问的仓库。 For more information about the response format, see the Create an installation access token for an app endpoint.

要使用安装访问令牌进行身份验证,请将其加入 API 请求的“授权”标头中。

$ curl -i \
-H "Authorization: token YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
http(s)://[hostname]/api/v3/installation/repositories

YOUR_INSTALLATION_ACCESS_TOKEN 是必须替换的值。

作为安装访问 API 端点

有关适用于使用安装访问令牌的 GitHub 应用程序 的 REST API 端点列表,请参阅“可用端点。”

有关与安装相关的端点的列表,请参阅“安装。”

由安装验证基于 HTTP 的 Git 访问权限

在仓库的 contents 上拥有权限的安装可以使用其安装访问令牌对 Git 访问权限进行身份验证。 使用安装访问令牌作为 HTTP 密码:

git clone https://x-access-token:<token>@github.com/owner/repo.git

问问别人

找不到要找的内容?

联系我们