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

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

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

您可以验证为 GitHub 应用程序 或安装。

本文内容

注:要使用 GitHub 应用程序访问 API,您必须在请求的 Accept 标头中提供自定义媒体类型

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

警告: 在预览期间,API 可能会更改,恕不另行通知。 预览功能不支持用于生产。 如果遇到任何问题,请联系 您的站点管理员。

生成私钥

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

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

要生成私钥:

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

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

验证私钥

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

要验证私钥:

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

删除私钥

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

验证为 GitHub 应用程序

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

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

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

下面是一段快速 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://docs.github.com/enterprise/2.20/rest"
}

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

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

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

验证为安装

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

默认情况下,安装访问令牌的作用域为安装可访问的所有仓库。 您可以使用 repository_ids 参数将安装访问令牌的作用域限定于特定仓库。 请参阅创建应用程序的安装访问令牌端点了解更多详细信息。 安装访问令牌具有由 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

响应将包括您的安装访问令牌、到期日期、令牌权限及令牌可访问的仓库。 有关响应格式的更多信息,请参阅创建应用程序的安装访问令牌端点。

要使用安装访问令牌进行身份验证,请将其加入 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