Identifying and authorizing users for GitHub Apps

本文内容

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 小时后过期的访问令牌，以及可交换新访问令牌的刷新令牌。有关详细信息，请参阅“刷新用户到服务器访问令牌”。

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 application flow

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

Users are redirected to request their GitHub identity
Users are redirected back to your site by GitHub
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. Request a user's GitHub identity

Direct the user to the following URL in their browser:

GET http(s)://HOSTNAME/login/oauth/authorize

When your GitHub App specifies a login parameter, it prompts users with a specific account they can use for signing in and authorizing your app.

Parameters

Name	Type	Description
`client_id`	`string`	Required. The client ID for your GitHub App. You can find this in your GitHub App settings when you select your app. Note: The app ID and client ID are not the same, and are not interchangeable.
`redirect_uri`	`string`	The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a Callback URL when setting up your GitHub App and can't contain any additional parameters.
`state`	`string`	This should contain a random string to protect against forgery attacks and could contain any other arbitrary data.
`login`	`string`	Suggests a specific account to use for signing in and authorizing the app.
`allow_signup`	`string`	Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups.

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. Users are redirected back to your site by 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 an optional feature and subject to change. To opt-in to the user-to-server token expiration feature, see "Activating optional features for apps."

Make a request to the following endpoint to receive an access token:

POST http(s)://HOSTNAME/login/oauth/access_token

Parameters

Name	Type	Description
`client_id`	`string`	Required. The client ID for your GitHub App.
`client_secret`	`string`	Required. The client secret for your GitHub App.
`code`	`string`	Required. The code you received as a response to Step 1.
`redirect_uri`	`string`	The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a Callback URL when setting up your GitHub App and can't contain any additional parameters.
`state`	`string`	The unguessable random string you provided in Step 1.

Response

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 expiring user-to-server access tokens.

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "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: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user

Device flow

Note: The device flow is in public beta and subject to change.

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: Bearer OAUTH-TOKEN
GET /user/installations

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

Authorization: Bearer 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 personal 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 or REST endpoints.

Identifying and authorizing users for GitHub Apps

本文内容

Identifying users on your site

Web application flow

1. Request a user's GitHub identity

Parameters

2. Users are redirected back to your site by GitHub

Parameters

Response

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

Device flow

Check which installation's resources a user can access

Handling a revoked GitHub App authorization

User-level permissions

User-to-server requests

Supported endpoints

Check Runs

Check Suites

Codes Of Conduct

Deployment Statuses

Deployments

Events

Feeds

Git Blobs

Git Commits

Git Refs

Git Tags

Git Trees

Gitignore Templates

Installations

Issue Assignees

Issue Comments

Issue Events

Issue Timeline

Issues

Labels

Licenses

Markdown

Meta

Milestones

Organization Hooks

Organization Members

Organization Outside Collaborators

Organization Pre Receive Hooks

Organization Team Projects

Organization Team Repositories

Organization Teams

Organizations

Project Collaborators

Projects

Pull Comments

Pull Request Review Events

Pull Request Review Requests

Pull Request Reviews

Pulls

Reactions

Repositories

Repository Activity

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 Pre Receive Hooks

Repository Releases

Repository Stats

Root

Search

Statuses

Team Discussions

Topics

User Emails

User Followers

User Gpg Keys