对 REST API 进行身份验证

关于身份验证

许多 REST API 终结点需要身份验证或是在进行身份验证后返回其他信息。此外，进行身份验证后，每小时可以发出更多请求。

要对请求进行身份验证，需要提供具有所需作用域或权限的身份验证令牌。有几种不同方式获取令牌：可以创建 personal access token，生成包含 GitHub App 的令牌，或使用 GitHub Actions 工作流中内置的 GITHUB_TOKEN。

创建令牌后，可以通过在请求的 Authorization 标头中发送令牌来对请求进行身份验证。例如，在以下请求中，请将 YOUR-TOKEN 替换为对你的令牌的引用：

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Note

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

如果尝试在没有令牌或令牌权限不足的情况下使用 REST API 终结点，你将收到 404 Not Found 或 403 Forbidden 响应。使用无效凭据进行身份验证最初将返回 401 Unauthorized 响应。

在短时间内检测到多个使用无效凭据的请求后，API 将暂时拒绝该用户的所有身份验证尝试（包括使用有效凭据的尝试），并返回 403 Forbidden 响应：有关详细信息，请参阅“REST API 的速率限制”。

使用 personal access token

进行身份验证

如果要将 GitHub REST API 用于个人用途，可以创建 personal access token。如果可能，GitHub 建议使用 fine-grained personal access token 而不是 personal access token (classic)。有关创建 personal access token 的详细信息，请参阅“管理个人访问令牌”。

如果使用的是 fine-grained personal access token，则 fine-grained personal access token 需要特定权限才能访问每个 REST API 终结点。每个终结点的 REST API 参考文档都说明终结点是否适用于 fine-grained personal access token，并说明令牌使用终结点所需的权限。某些终结点可能需要多个权限，而某些终结点可能需要多个权限之一。有关 fine-grained personal access token 可通过各种权限访问哪些 REST API 终结点的概述，请参阅“细粒度个人访问令牌所需的权限”。

如果使用的是 personal access token (classic)，则需要特定范围才能访问每个 REST API 终结点。有关要选择的范围的通用指南，请参阅 OAuth 应用的范围。

Personal access tokens and SAML SSO

如果使用 personal access token (classic) 访问强制实施 SAML 单一登录 (SSO) 进行身份验证的组织，则需要在创建后授权令牌。在授予组织访问权限之前，Fine-grained personal access tokens 在令牌创建期间获得授权。有关详细信息，请参阅“授权用于 SAML 单点登录的个人访问令牌”。

如果在没有授权 SAML SSO 的 personal access token (classic) 之前就尝试使用它来访问强制执行 SAML SSO 的组织，你可能会收到 404 Not Found 或 403 Forbidden 错误。如果收到 403 Forbidden 错误，可以参考 X-GitHub-SSO 标头中的 URL 来对令牌进行授权。 URL 将在一小时后过期。

如果在没有授权 SAML SSO 的 personal access token (classic) 之前就尝试使用它来访问多个组织，则 API 不会返回需要 SAML SSO 的组织的结果，标头 X-GitHub-SSO 会指示需要 personal access token (classic) SAML SSO 授权的组织 ID。例如：X-GitHub-SSO: partial-results; organizations=21955855,20582480。

使用应用生成的令牌进行身份验证

如果要为组织或代表其他用户使用 API，GitHub 建议使用 GitHub App。有关详细信息，请参阅“关于使用 GitHub 应用进行身份验证”。

每个终结点的 REST API 参考文档都说明终结点是否适用于 GitHub Apps，并说明应用使用终结点所需的权限。某些终结点可能需要多个权限，而某些终结点可能需要多个权限之一。有关 GitHub App 可通过各种权限访问哪些 REST API 终结点的概述，请参阅“GitHub 应用程序所需的权限”。

你还可以使用 OAuth app 创建 OAuth 标记以访问 REST API。但 GitHub 建议改用 GitHub App。使用 GitHub Apps 可以更好地控制应用拥有的访问权限和权限。

对于 SAML SSO，应用创建的访问令牌会自动获得授权。

使用基本身份验证

GitHub Apps 和 OAuth apps 的一些 REST API 终结点要求使用基本身份验证来访问终结点。你将使用应用的客户端 ID 作为用户名，使用应用的客户端密码作为密码。

例如：

curl --request POST \
--url "https://api.github.com/applications/YOUR_CLIENT_ID/token" \
--user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--data '{
  "access_token": "ACCESS_TOKEN_TO_CHECK"
}'

客户端 ID 和客户端密码与应用相关联，而不是与应用所有者或授权应用的用户相关联。它们用于代表应用执行操作，例如创建访问令牌。

如果你是 GitHub App 或 OAuth app 的所有者，或者你是 GitHub App 的应用管理者，则可在应用的设置页上找到客户端 ID 并生成客户端密码。导航到应用的设置页：

在 GitHub 上任意页的右上角，单击你的个人资料照片。
导航到你的帐户设置。
- 对于由个人帐户拥有的应用，请单击“设置”****。
- 对于组织拥有的应用：
  1. 单击“你的组织”。
  2. 在组织右侧，单击“设置”。
在左侧边栏中，单击“ 开发人员设置”。
在左侧栏中，单击 GitHub Apps 或 OAuth apps。
对于 GitHub Apps，在要访问的 GitHub App 的右侧，单击“编辑****”。对于 OAuth apps，请单击要访问的应用。
在“客户端 ID”旁边****，你将看到应用的客户端 ID。
在“客户端密码”旁边****，单击“生成新客户端密码”，为应用生成客户端密码****。

在 GitHub Actions 工作流中进行身份验证

如果要在 GitHub Actions 工作流中使用 API，则 GitHub 建议使用内置 GITHUB_TOKEN 进行身份验证，而不是创建令牌。可以使用 permissions 密钥向 GITHUB_TOKEN 授予权限。有关详细信息，请参阅“自动令牌身份验证”。

如果无法执行此操作，可以将令牌存储为机密，并在 GitHub Actions 工作流中使用该机密的名称。有关机密的详细信息，请参阅“在 GitHub Actions 中使用机密”。

在 GitHub Actions 工作流中使用 GitHub CLI 进行身份验证

要使用 GitHub CLI 在 GitHub Actions 工作流中向 API 发出经过身份验证的请求，可以将值 GITHUB_TOKEN 存储为环境变量，并使用 run 关键字执行 GitHub CLI api 子命令。要详细了解 run 密钥，请参阅“GitHub Actions 的工作流语法”。

在以下示例工作流中，将 PATH 替换为终结点的路径。有关路径的详细信息，请参阅“REST API 入门”。

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /PATH

在 GitHub Actions 工作流中使用 `curl` 进行身份验证

要使用 curl 向 GitHub Actions 工作流中的 API 发出经过身份验证的请求，可以将值 GITHUB_TOKEN 存储为环境变量，并使用 run 关键字对 API 执行 curl 请求。要详细了解 run 密钥，请参阅“GitHub Actions 的工作流语法”。

在以下示例工作流中，将 PATH 替换为终结点的路径。有关路径的详细信息，请参阅“REST API 入门”。

YAML

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/PATH" \
          --header "Authorization: Bearer $GH_TOKEN"

"确保 API 凭据安全"
“REST API 入门”

对 REST API 进行身份验证

本文内容