Skip to content

Commit 6c5b005

Browse files
hubwriterSarah EdwardsSteve Wintonrunleonarun
authored
Explain why some GitHub Apps ask to "act on your behalf" (github#20250)
* Add screenshots for GH Apps auth article * Tidy up links to authorising OAuth article * Update content/developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps.md Co-authored-by: Sarah Edwards <skedwards88@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Sarah Edwards <skedwards88@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update data/glossaries/external.yml Co-authored-by: Steve Winton <swinton@github.com> * Update data/glossaries/external.yml Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md * Delete PNGs removed during PR review * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> * Update content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md Co-authored-by: Steve Winton <swinton@github.com> Co-authored-by: Sarah Edwards <skedwards88@github.com> Co-authored-by: Steve Winton <swinton@github.com> Co-authored-by: Leona B. Campbell <3880403+runleonarun@users.noreply.github.com>
1 parent ff11ca3 commit 6c5b005

9 files changed

Lines changed: 67 additions & 5 deletions

File tree

‎assets/images/help/apps/github-apps-new-issue.png‎

101 KB
Loading

‎content/developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,4 +100,4 @@ Once your GitHub App has been installed on a repository, you should remove any u
100100

101101
### Encourage users to revoke access to your OAuth app
102102

103-
As your GitHub App installation base grows, consider encouraging your users to [revoke access](/articles/authorizing-oauth-apps/) to the legacy OAuth integration.
103+
As your GitHub App installation base grows, consider encouraging your users to revoke access to the legacy OAuth integration. For more information, see [Authorizing OAuth Apps](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps)

‎content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Authorizing GitHub Apps
3+
intro: 'You can authorize a {% data variables.product.prodname_github_app %} to allow an application to retrieve information about your {% data variables.product.prodname_dotcom %} account and, in some circumstances, to make changes on {% data variables.product.prodname_dotcom %} on your behalf.'
4+
versions:
5+
fpt: '*'
6+
ghes: '*'
7+
ghae: '*'
8+
topics:
9+
- Identity
10+
- Access management
11+
---
12+
13+
Third-party applications that need to verify your {% data variables.product.prodname_dotcom %} identity, or interact with the data on {% data variables.product.prodname_dotcom %} on your behalf, can ask you to authorize the {% data variables.product.prodname_github_app %} to do so.
14+
15+
When authorizing the {% data variables.product.prodname_github_app %}, you should ensure you trust the application, review who it's developed by, and review the kinds of information the application wants to access.
16+
17+
During authorization, you'll be prompted to grant the {% data variables.product.prodname_github_app %} permission to:
18+
* **Verify your {% data variables.product.prodname_dotcom %} identity**<br/>
19+
When authorized, the {% data variables.product.prodname_github_app %} will be able to programmatically retrieve your public GitHub profile, as well as some private details (such as your email address), depending on the level of access requested.
20+
* **Know which resources you can access**<br/>
21+
When authorized, the {% data variables.product.prodname_github_app %} will be able to programmatically read the _private_ {% data variables.product.prodname_dotcom %} resources that you can access (such as private {% data variables.product.prodname_dotcom %} repositories) _where_ an installation of the {% data variables.product.prodname_github_app %} is also present. The application may use this, for example, so that it can show you an appropriate list of repositories.
22+
* **Act on your behalf**<br/>
23+
The application may need to perform tasks on {% data variables.product.prodname_dotcom %}, as you. This might include creating an issue, or commenting on a pull request. This ability to act on your behalf is limited to the {% data variables.product.prodname_dotcom %} resources where _both_ you and the {% data variables.product.prodname_github_app %} have access. In some cases, however, the application may never make any changes on your behalf.
24+
25+
## When does a {% data variables.product.prodname_github_app %} act on your behalf?
26+
27+
The situations in which a {% data variables.product.prodname_github_app %} acts on your behalf vary according to the purpose of the {% data variables.product.prodname_github_app %} and the context in which it is being used.
28+
29+
For example, an integrated development environment (IDE) may use a {% data variables.product.prodname_github_app %} to interact on your behalf in order to push changes you have authored through the IDE back to repositories on {% data variables.product.prodname_dotcom %}. The {% data variables.product.prodname_github_app %} will achieve this through a [user-to-server request](/get-started/quickstart/github-glossary#user-to-server-request).
30+
31+
When a {% data variables.product.prodname_github_app %} acts on your behalf in this way, this is identified on GitHub via a special icon that shows a small avatar for the {% data variables.product.prodname_github_app %} overlaid onto your own avatar, similar to the one shown below.
32+
33+
![An issue created by a "user-to-server" request from a {% data variables.product.prodname_github_app %}](/assets/images/help/apps/github-apps-new-issue.png)
34+
35+
## To what extent can a {% data variables.product.prodname_github_app %} know which resources you can access and act on your behalf?
36+
37+
The extent to which a {% data variables.product.prodname_github_app %} can know which resources you can access and act on your behalf, after you have authorized it, is limited by:
38+
39+
* The organizations or repositories on which the app is installed
40+
* The permissions the app has requested
41+
* Your access to {% data variables.product.prodname_dotcom %} resources
42+
43+
Let's use an example to explain this.
44+
45+
{% data variables.product.prodname_dotcom %} user Alice logs into a third-party web application, ExampleApp, using their {% data variables.product.prodname_dotcom %} identity. During this process, Alice authorizes ExampleApp to perform actions on their behalf.
46+
47+
However, the activity ExampleApp is able to perform on Alice's behalf in {% data variables.product.prodname_dotcom %} is constrained by: the repositories on which ExampleApp is installed, the permissions ExampleApp has requested, and Alice's access to {% data variables.product.prodname_dotcom %} resources.
48+
49+
This means that, in order for ExampleApp to create an issue on Alice's behalf, in a repository called Repo A, all of the following must be true:
50+
51+
* ExampleApp's {% data variables.product.prodname_github_app %} requests write access to issues.
52+
* A user having admin access for Repo A must have installed ExampleApp's {% data variables.product.prodname_github_app %} on Repo<code>&nbsp;</code>A.
53+
* Alice must have read permission for Repo A. For information about which permissions are required to perform various activities, see "[Repository permission levels for an organization](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-access-for-each-permission-level)."

‎content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ If you belong to any organizations that enforce SAML single sign-on, you must ha
8686
## Further reading
8787

8888
- "[About {% data variables.product.prodname_oauth_app %} access restrictions](/articles/about-oauth-app-access-restrictions)"
89+
- "[Authorizing GitHub Apps](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps)"
8990
- "[{% data variables.product.prodname_marketplace %} support](/articles/github-marketplace-support)"
9091

9192
{% endif %}

‎content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ children:
1818
- /reviewing-your-ssh-keys
1919
- /reviewing-your-deploy-keys
2020
- /authorizing-oauth-apps
21+
- /authorizing-github-apps
2122
- /reviewing-your-authorized-integrations
2223
- /connecting-with-third-party-applications
2324
- /reviewing-your-authorized-applications-oauth

‎content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ The events listed in your security log are triggered by your actions. Actions ar
4949
| [`codespaces`](#codespaces-category-actions) | Contains all activities related to {% data variables.product.prodname_codespaces %}. For more information, see "[About {% data variables.product.prodname_codespaces %}](/github/developing-online-with-codespaces/about-codespaces)."
5050
| [`marketplace_agreement_signature`](#marketplace_agreement_signature-category-actions) | Contains all activities related to signing the {% data variables.product.prodname_marketplace %} Developer Agreement.
5151
| [`marketplace_listing`](#marketplace_listing-category-actions) | Contains all activities related to listing apps in {% data variables.product.prodname_marketplace %}.{% endif %}
52-
| [`oauth_access`](#oauth_access-category-actions) | Contains all activities related to [{% data variables.product.prodname_oauth_app %}s](/articles/authorizing-oauth-apps) you've connected with.{% ifversion fpt %}
52+
| [`oauth_access`](#oauth_access-category-actions) | Contains all activities related to [{% data variables.product.prodname_oauth_app %}s](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps) you've connected with.{% ifversion fpt %}
5353
| [`payment_method`](#payment_method-category-actions) | Contains all activities related to paying for your {% data variables.product.prodname_dotcom %} subscription.{% endif %}
5454
| [`profile_picture`](#profile_picture-category-actions) | Contains all activities related to your profile picture.
5555
| [`project`](#project-category-actions) | Contains all activities related to project boards.
@@ -122,7 +122,7 @@ An overview of some of the most common actions that are recorded as events in th
122122

123123
| Action | Description
124124
|------------------|-------------------
125-
| `create` | Triggered when you [grant access to an {% data variables.product.prodname_oauth_app %}](/articles/authorizing-oauth-apps).
125+
| `create` | Triggered when you [grant access to an {% data variables.product.prodname_oauth_app %}](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps).
126126
| `destroy` | Triggered when you [revoke an {% data variables.product.prodname_oauth_app %}'s access to your account](/articles/reviewing-your-authorized-integrations).
127127

128128
{% ifversion fpt %}

‎content/github/customizing-your-github-workflow/exploring-integrations/about-integrations.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ For more information, see:
1919
- "[Differences between {% data variables.product.prodname_github_app %}s and {% data variables.product.prodname_oauth_app %}s](/apps/differences-between-apps/)"
2020
- "[About apps](/apps/about-apps/)"
2121
- "[User-level permissions](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-level-permissions)"
22-
- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/articles/authorizing-oauth-apps/)"
22+
- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps)"
23+
- "[Authorizing {% data variables.product.prodname_github_apps %}](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps)"
2324
- "[Reviewing your authorized integrations](/articles/reviewing-your-authorized-integrations/)"
2425

2526
You can install a preconfigured {% data variables.product.prodname_github_app %}, if the integrators or app creators have created their app with the {% data variables.product.prodname_github_app %} manifest flow. For information about how to run your {% data variables.product.prodname_github_app %} with automated configuration, contact the integrator or app creator.

‎content/organizations/restricting-access-to-your-organizations-data/about-oauth-app-access-restrictions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,4 +58,4 @@ If an organization disables {% data variables.product.prodname_oauth_app %} acce
5858
- "[Denying access to a previously approved {% data variables.product.prodname_oauth_app %} for your organization](/articles/denying-access-to-a-previously-approved-oauth-app-for-your-organization)"
5959
- "[Disabling {% data variables.product.prodname_oauth_app %} access restrictions for your organization](/articles/disabling-oauth-app-access-restrictions-for-your-organization)"
6060
- "[Requesting organization approval for {% data variables.product.prodname_oauth_app %}s](/articles/requesting-organization-approval-for-oauth-apps)"
61-
- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/articles/authorizing-oauth-apps)"
61+
- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps)"

‎data/glossaries/external.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -678,6 +678,9 @@
678678
description: >-
679679
A log that lists the last 50 actions or those performed within the last 90
680680
days.
681+
- term: server-to-server request
682+
description: >-
683+
An API request used by an application that acts as a bot, independently of any particular user. For example, an application that runs on a scheduled basis and closes issues where there has been no activity for a long time. Applications that use this type of authentication don't use a licensed GitHub account so, in an enterprise with a billing plan that allows a certain number of licenses to be used, a server-to-server bot is not consuming one of your GitHub licenses. The token used in a server-to-server request is acquired programmatically, via [the GitHub API](https://docs.github.com/en/rest/reference/apps#create-an-installation-access-token-for-an-app). See also, "[user-to-server request](#user-to-server-request)."
681684
- term: service hook
682685
description: >-
683686
Also called "webhook." Webhooks provide a way for notifications to be
@@ -764,6 +767,9 @@
764767
invited to join organizations or collaborate on another user's repository.
765768
- term: username
766769
description: A user's handle on GitHub.
770+
- term: user-to-server request
771+
description: >-
772+
An API request used by an application that performs a task on behalf of a particular user. Where a task is carried out with user-to-server authentication it's shown on GitHub as having been done by a user via an application. For example, you might choose to create an issue from within a third-party application, and the application would do this on your behalf on GitHub. The scope of tasks an application can perform using a user-to-server request is restricted by both the app's and the user's permissions and access. The token used in a user-to-server request is acquired via OAuth. For more information, see "[Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps)." See also, "[server-to-server request](#server-to-server-request)."
767773
- term: visible team
768774
description: A team that can be viewed and @mentioned by every organization member.
769775
- term: watch

0 commit comments

Comments
 (0)