Skip to main content

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

您可以验证为 GitHub App 或安装。

生成私钥

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

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

要生成私钥:

  1. 在任何页面的右上角,单击个人资料照片,然后单击“设置”。

    用户栏中的 Settings 图标

  2. 在左侧边栏中,单击“ 开发人员设置”。

  3. 在左侧边栏中,单击“GitHub 应用”。 GitHub 应用部分 1. 在要修改的 GitHub App 右边,单击“编辑”。 应用程序选择

  4. 在“私钥”中,单击“生成私钥”。 生成私钥

  5. 您将看到一个以 PEM 格式下载至您的计算机的私钥。 确保将此文件存储下来,因为 GitHub 仅存储密钥的公共部分。

注意:如果你使用的库需要特定文件格式,你下载的 PEM 文件将采用 PKCS#1 RSAPrivateKey 格式。

验证私钥

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

要验证私钥:

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

删除私钥

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

验证为 GitHub App

通过验证为 GitHub App,您可以执行以下操作:

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

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

生成 Json Web 令牌 (JWT)

使用 Ruby

下面是一段 Ruby 脚本,可用于生成 JWT。 请注意,必须先运行 gem install jwt,然后才能使用。 必须替换 YOUR_PATH_TO_PEMYOUR_APP_ID 值。 请确保以双引号括住值。

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, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub App's identifier
  iss: "YOUR_APP_ID"
}

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

使用 Python

下面是在 Python 中生成 JWT 的类似脚本。 请注意,你必须使用 pip install jwt 才能使用此脚本。 此脚本将提示输入 PEM 文件的位置和你的应用 ID,你也可以在执行脚本时将其作为内联参数传递。

python
#!/usr/bin/env python3
import jwt
import time 
import sys

# Get PEM file path
if len(sys.argv) > 1:
    pem = sys.argv[1]
else:
    pem = input("Enter path of private PEM file: ")    

# Get the App ID
if len(sys.argv) > 2:
    app_id = sys.argv[2]
else:
    app_id = input("Enter your APP ID: ") 

# Open PEM
with open(pem, 'rb') as pem_file:
    signing_key = jwt.jwk_from_pem(pem_file.read())
    
payload = {
    # Issued at time
    'iat': int(time.time()),
    # JWT expiration time (10 minutes maximum)
    'exp': int(time.time()) + 600, 
    # GitHub App's identifier
    'iss': app_id 
}
    
# Create JWT
jwt_instance = jwt.JWT()
encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256')
     
print(f"JWT:  ", encoded_jwt)

将 GitHub App 的标识符 (YOUR_APP_ID) 用作 JWT iss(颁发者)声明的值。 可在创建应用后通过初始 Webhook ping 获取 GitHub App 标识符,也可随时从 GitHub.com UI 的应用设置页面获取。

创建 JWT 后,在 API 请求的 Header 中设置它:

$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github+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/3.7/rest"
}

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

作为 GitHub App 访问 API 端点

有关可用于获取关于 GitHub App 的高级信息的 REST API 终结点列表,请参阅“GitHub 应用”。

验证为安装

通过验证为安装,您可以在 API 中为此安装执行操作。 验证为安装之前,必须创建安装访问令牌。 确保您已将 GitHub 应用安装到至少一个仓库;如果没有单个安装,就无法创建安装令牌。 这些安装访问令牌由 GitHub Apps 用于进行身份验证。 有关详细信息,请参阅“安装 GitHub Apps”。

默认情况下,安装访问令牌的作用域为安装可访问的所有仓库。 可使用 repository_ids 参数将安装访问令牌的范围限定于特定存储库。 有关更多详细信息,请参阅为应用创建安装访问令牌终结点。 安装访问令牌具有由 GitHub App 配置的权限,一个小时后到期。

要列出经过身份验证的应用的安装,请在 API 请求的授权标头中包含上面生成的 JWT:

$ curl -i -X GET \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github+json" \
http(s)://HOSTNAME/api/v3/app/installations

响应将包括一个安装列表,其中每个安装的 id 可用来创建一个安装访问令牌。 有关响应格式的详细信息,请参阅“列出经过身份验证的应用的安装”。

要创建安装访问令牌,请在 API 请求的授权标头中包含上面生成的 JWT,并将 :installation_id 替换为安装的 id

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

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

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

$ curl -i \
-H "Authorization: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github+json" \
http(s)://HOSTNAME/api/v3/installation/repositories

YOUR_INSTALLATION_ACCESS_TOKEN 值必须替换。

注意:在大多数情况下,可以使用 Authorization: BearerAuthorization: token 传递令牌。 但是,如果要传递 JSON Web 令牌 (JWT),则必须使用 Authorization: Bearer

作为安装访问 API 端点

有关使用安装访问令牌的 GitHub Apps 可用的 REST API 终结点列表,请参阅“可用终结点”。

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

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

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

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