title | intro | redirect_from | versions | topics | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
使用 GitHub 应用程序进行身份验证 |
{% data reusables.shortdesc.authenticating_with_github_apps %} |
|
|
|
{% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.22" %} {% data reusables.pre-release-program.machine-man-preview %} {% data reusables.pre-release-program.api-preview-warning %} {% endif %}
创建 GitHub 应用程序 后,您需要生成一个或多个私钥。 私钥可用于签署访问令牌请求。
您可以创建多个私钥,然后轮流使用,以防某个私钥被盗或丢失造成停工。 要验证私钥是否与公钥匹配,请参阅验证私钥。
要生成私钥:
{% data reusables.user-settings.access_settings %} {% data reusables.user-settings.developer_settings %} {% data reusables.user-settings.github_apps %} {% data reusables.user-settings.modify_github_app %} 5. 在“Private keys(私钥)”中,单击 Generate a private key(生成私钥)。 6. 您将看到一个以 PEM 格式下载至您的计算机的私钥。 确保将此文件存储下来,因为 GitHub 仅存储密钥的公共部分。
{% note %}
**注:**如果您使用的库需要特定文件格式,您下载的 PEM 文件将呈现为 PKCS#1 RSAPrivateKey
格式。
{% endnote %}
{% data variables.product.product_name %} 使用 {% if currentVersion ver_lt "enterprise-server@2.23" %}SHA-1{% else %}SHA-256{% endif %} 哈希函数为每对私钥和公钥生成指纹。 您可以生成私钥指纹,然后与 {% data variables.product.product_name %} 显示的指纹相比较,以验证私钥是否与 {% data variables.product.product_name %} 上存储的公钥匹配。
要验证私钥:
- 在 {% data variables.product.prodname_github_app %} 开发者设置页面的“私钥”部分,查找要验证的私钥和公钥对的指纹。 更多信息请参阅生成私钥。
- 使用以下命令在本地生成私钥指纹 (PEM):
$ openssl rsa -in <em>PATH_TO_PEM_FILE</em> -pubout -outform DER | openssl {% if currentVersion ver_lt "enterprise-server@2.23" %}sha1 -c{% else %}sha256 -binary | openssl base64{% endif %}
- 比较本地生成的指纹结果与 {% data variables.product.product_name %} 中显示的指纹。
您可以通过删除功能删除丢失或被盗的私钥,但至少必须有一个私钥。 如果只有一个密钥,需要生成一个新钥,然后才能删除旧钥。
通过验证为 {% data variables.product.prodname_github_app %},您可以执行以下操作:
- 检索关于您的 {% data variables.product.prodname_github_app %} 的高级管理信息。
- 为应用程序安装申请访问令牌。
要验证为 {% data variables.product.prodname_github_app %},请以 PEM 格式生成私钥,并将其下载到本地机器上。 您可以使用此密钥签署 JSON Web 令牌 (JWT),然后用 RS256
算法为它编码。 {% data variables.product.product_name %} 将使用应用程序存储的公钥验证令牌,以检查请求是否已通过身份验证。
下面是一段快速 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, 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),
# {% data variables.product.prodname_github_app %}'s identifier
iss: YOUR_APP_ID
}
jwt = JWT.encode(payload, private_key, "RS256")
puts jwt
YOUR_PATH_TO_PEM
和 YOUR_APP_ID
是必须替换的值。
使用 {% data variables.product.prodname_github_app %} 的标识符 (YOUR_APP_ID
) 作为 JWT iss(签发者)申请的值。 您可以在创建应用程序后通过初始 web 挂钩,或随时从 GitHub.com UI 的应用程序设置页面获取 {% data variables.product.prodname_github_app %} 标识符。
创建 JWT 后,在 API 请求的 Header
中对它进行设置。
{% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.22" %}
$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github.machine-man-preview+json" {% data variables.product.api_url_pre %}/app
{% else %}
$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github.v3+json" {% data variables.product.api_url_pre %}/app
{% endif %}
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": "{% data variables.product.doc_url_pre %}"
}
到期后,您需要创建新 JWT。
有关获取关于 {% data variables.product.prodname_github_app %} 的高级信息所用的 REST API 端点列表,请参阅“GitHub 应用程序。”
通过验证为安装,您可以在 API 中为此安装执行操作。 验证为安装之前,必须创建安装访问令牌。 这些安装访问令牌由 {% data variables.product.prodname_github_app %} 用于进行身份验证。
默认情况下,安装访问令牌的作用域为安装可访问的所有仓库。 您可以使用 repository_ids
参数将安装访问令牌的作用域限定于特定仓库。 请参阅创建应用程序的安装访问令牌端点了解更多详细信息。 安装访问令牌具有由 {% data variables.product.prodname_github_app %} 配置的权限,一个小时后到期。
要创建安装访问令牌,请在 API 请求的“授权”标头中加入上文生成的 JWT:
{% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.22" %}
$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
{% data variables.product.api_url_pre %}/app/installations/:installation_id/access_tokens
{% else %}
$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.v3+json" \
{% data variables.product.api_url_pre %}/app/installations/:installation_id/access_tokens
{% endif %}
响应将包括您的安装访问令牌、到期日期、令牌权限及令牌可访问的仓库。 有关响应格式的更多信息,请参阅创建应用程序的安装访问令牌端点。
要使用安装访问令牌进行身份验证,请将其加入 API 请求的“授权”标头中。
{% if enterpriseServerVersions contains currentVersion and currentVersion ver_lt "enterprise-server@2.22" %}
$ curl -i \
-H "Authorization: token YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
{% data variables.product.api_url_pre %}/installation/repositories
{% else %}
$ curl -i \
-H "Authorization: token YOUR_INSTALLATION_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
{% data variables.product.api_url_pre %}/installation/repositories
{% endif %}
YOUR_INSTALLATION_ACCESS_TOKEN
是必须替换的值。
有关适用于使用安装访问令牌的 {% data variables.product.prodname_github_app %} 的 REST API 端点列表,请参阅“可用端点。”
有关与安装相关的端点的列表,请参阅“安装。”
在仓库的 contents
上拥有权限的安装可以使用其安装访问令牌对 Git 访问权限进行身份验证。 使用安装访问令牌作为 HTTP 密码:
git clone https://x-access-token:<token>@github.com/owner/repo.git