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

Identifying and authorizing users for GitHub Apps

GitHub 应用程序可以代表用户执行操作,例如创建议题、创建部署和使用其他受支持的端点。

本文内容

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。

注:过期用户令牌目前是用户到服务器令牌过期的一部分,可能会更改。 要选择加入用户到服务器令牌过期测试版功能,请参阅“激活应用程序的测试版功能”。 更多信息请参阅“GitHub 应用程序过期用户到服务器访问令牌”。

When your GitHub App acts on behalf of a user, it performs user-to-server requests. These requests must be authorized with a user's access token. User-to-server requests include requesting data for a user, like determining which repositories to display to a particular user. These requests also include actions triggered by a user, like running a build.

为使用户到服务器的访问令牌更安全,您可以使用将在 8 小时后过期的访问令牌,以及可交换新访问令牌的刷新令牌。 For more information, see "Refreshing user-to-server access tokens."

Identifying users on your site

To authorize users for standard apps that run in the browser, use the web application flow.

To authorize users for headless apps without direct access to the browser, such as CLI tools or Git credential managers, use the device flow. The device flow uses the OAuth 2.0 Device Authorization Grant.

Web 应用程序流程

Using the web application flow, the process to identify users on your site is:

  1. 用户被重定向,以请求他们的 GitHub 身份
  2. 用户被 GitHub 重定向回您的站点
  3. Your GitHub App accesses the API with the user's access token

If you select Request user authorization (OAuth) during installation when creating or modifying your app, step 1 will be completed during app installation. For more information, see "Authorizing users during installation."

1. 请求用户的 GitHub 身份

GET https://github.com/login/oauth/authorize

当您的 GitHub 应用程序指定 login 参数后,它将提示拥有特定账户的用户可以用来登录和授权您的应用程序。

参数
名称类型描述
client_id字符串Required. The client ID for your GitHub App. You can find this in your GitHub App settings when you select your app.
redirect_uri字符串用户获得授权后被发送到的应用程序中的 URL。 This must be an exact match to the URL you provided in the User authorization callback URL field when setting up your GitHub App and can't contain any additional parameters.
state字符串This should contain a random string to protect against forgery attacks and could contain any other arbitrary data.
login字符串提供用于登录和授权应用程序的特定账户。

Note: You don't need to provide scopes in your authorization request. Unlike traditional OAuth, the authorization token is limited to the permissions associated with your GitHub App and those of the user.

2. 用户被 GitHub 重定向回您的站点

If the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don't match, the request was created by a third party and the process should be aborted.

Note: If you select Request user authorization (OAuth) during installation when creating or modifying your app, GitHub returns a temporary code that you will need to exchange for an access token. The state parameter is not returned when GitHub initiates the OAuth flow during app installation.

Exchange this code for an access token. When expiring tokens are enabled, the access token expires in 8 hours and the refresh token expires in 6 months. Every time you refresh the token, you get a new refresh token. For more information, see "Refreshing user-to-server access tokens."

Expiring user tokens are currently part of the user-to-server token expiration beta and subject to change. To opt-in to the user-to-server token expiration beta feature, see "Activating beta features for apps."

POST https://github.com/login/oauth/access_token
参数
名称类型描述
client_id字符串Required. The client ID for your GitHub App.
client_secret字符串Required. The client secret for your GitHub App.
代码字符串必填。您收到的响应第 1 步的代码。
redirect_uri字符串用户获得授权后被发送到的应用程序中的 URL。
state字符串您在第 1 步提供的不可猜测的随机字符串。
响应

By default, the response takes the following form. The response parameters expires_in, refresh_token, and refresh_token_expires_in are only returned when you enable the beta for expiring user-to-server access tokens.

{
  "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a",
  "expires_in": "28800",
  "refresh_token": "r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692",
  "refresh_token_expires_in": "15811200",
  "scope": "",
  "token_type": "bearer"
}

3. Your GitHub App accesses the API with the user's access token

The user's access token allows the GitHub App to make requests to the API on behalf of a user.

Authorization: token OAUTH-TOKEN
GET https://api.github.com/user

例如,您可以像以下这样在 curl 中设置“授权”标头:

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/user

Device flow

Note: The device flow is in public beta and subject to change. To enable this beta feature, see "Activating beta features for apps."

The device flow allows you to authorize users for a headless app, such as a CLI tool or Git credential manager.

For more information about authorizing users using the device flow, see "Authorizing OAuth Apps".

Check which installation's resources a user can access

Once you have an OAuth token for a user, you can check which installations that user can access.

Authorization: token OAUTH-TOKEN
GET /user/installations

You can also check which repositories are accessible to a user for an installation.

Authorization: token OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

More details can be found in: List app installations accessible to the user access token and List repositories accessible to the user access token.

Handling a revoked GitHub App authorization

If a user revokes their authorization of a GitHub App, the app will receive the github_app_authorization webhook by default. GitHub Apps cannot unsubscribe from this event. 任何人都可以从 GitHub 帐户设置页面撤销他们对 GitHub 应用程序的授权。 撤销对 GitHub 应用程序的授权不会卸载 GitHub 应用程序。 您应该编程 GitHub 应用程序,使其在收到此 web 挂钩后,不再代表已撤销令牌的人调用 API。 如果 GitHub 应用程序继续使用已撤销的访问令牌,它将收到 401 Bad Credentials 错误。

User-level permissions

You can add user-level permissions to your GitHub App to access user resources, such as user emails, that are granted by individual users as part of the user authorization flow. User-level permissions differ from repository and organization-level permissions, which are granted at the time of installation on an organization or user account.

You can select user-level permissions from within your GitHub App's settings in the User permissions section of the Permissions & webhooks page. For more information on selecting permissions, see "Editing a GitHub App's permissions."

When a user installs your app on their account, the installation prompt will list the user-level permissions your app is requesting and explain that the app can ask individual users for these permissions.

Because user-level permissions are granted on an individual user basis, you can add them to your existing app without prompting users to upgrade. You will, however, need to send existing users through the user authorization flow to authorize the new permission and get a new user-to-server token for these requests.

User-to-server requests

While most of your API interaction should occur using your server-to-server installation access tokens, certain endpoints allow you to perform actions via the API using a user access token. Your app can make the following requests using GraphQL v4 or REST v3 endpoints.

Supported endpoints

Actions Runners
Actions Secrets
构件
检查运行
检查套件
Codes Of Conduct
Deployment Statuses
部署
事件
馈送
Git Blobs
Git Commits
Git Refs
Git Tags
Git Trees
Gitignore Templates
安装设施
Interaction Limits
Issue Assignees
Issue Comments
Issue Events
Issue Timeline
议题
Jobs
标签
许可
Markdown
元数据
里程碑
Organization Hooks
Organization Invitations
Organization Members
Organization Outside Collaborators
Organization Team Projects
Organization Team Repositories
Organization Team Sync
Organization Teams
组织
Organizations Credential Authorizations
Organizations Scim
Source Imports
Project Collaborators
项目
Pull Comments
Pull Request Review Events
Pull Request Review Requests
Pull Request Reviews
拉取
反应
仓库
Repository Activity
Repository Automated Security Fixes
Repository Branches
Repository Collaborators
Repository Commit Comments
Repository Commits
Repository Community
Repository Contents
Repository Event Dispatches
Repository Hooks
Repository Invitations
Repository Keys
Repository Pages
Repository Releases
Repository Stats
仓库漏洞警报
搜索
状态
Team Discussions
主题
流量
User Blocking
User Emails
User Followers
User Gpg Keys
User Public Keys
用户
Workflow Runs
工作流程

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。