Explain why some GitHub Apps ask to "act on your behalf" (#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>
This commit is contained in:
hubwriter
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Authorizing GitHub Apps
|
||||
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.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
topics:
|
||||
- Identity
|
||||
- Access management
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
During authorization, you'll be prompted to grant the {% data variables.product.prodname_github_app %} permission to:
|
||||
* **Verify your {% data variables.product.prodname_dotcom %} identity**<br/>
|
||||
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.
|
||||
* **Know which resources you can access**<br/>
|
||||
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.
|
||||
* **Act on your behalf**<br/>
|
||||
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.
|
||||
|
||||
## When does a {% data variables.product.prodname_github_app %} act on your behalf?
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## To what extent can a {% data variables.product.prodname_github_app %} know which resources you can access and act on your behalf?
|
||||
|
||||
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:
|
||||
|
||||
* The organizations or repositories on which the app is installed
|
||||
* The permissions the app has requested
|
||||
* Your access to {% data variables.product.prodname_dotcom %} resources
|
||||
|
||||
Let's use an example to explain this.
|
||||
|
||||
{% 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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
* ExampleApp's {% data variables.product.prodname_github_app %} requests write access to issues.
|
||||
* A user having admin access for Repo A must have installed ExampleApp's {% data variables.product.prodname_github_app %} on Repo<code> </code>A.
|
||||
* 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)."
|
||||
@@ -86,6 +86,7 @@ If you belong to any organizations that enforce SAML single sign-on, you must ha
|
||||
## Further reading
|
||||
|
||||
- "[About {% data variables.product.prodname_oauth_app %} access restrictions](/articles/about-oauth-app-access-restrictions)"
|
||||
- "[Authorizing GitHub Apps](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps)"
|
||||
- "[{% data variables.product.prodname_marketplace %} support](/articles/github-marketplace-support)"
|
||||
|
||||
{% endif %}
|
||||
|
||||
@@ -18,6 +18,7 @@ children:
|
||||
- /reviewing-your-ssh-keys
|
||||
- /reviewing-your-deploy-keys
|
||||
- /authorizing-oauth-apps
|
||||
- /authorizing-github-apps
|
||||
- /reviewing-your-authorized-integrations
|
||||
- /connecting-with-third-party-applications
|
||||
- /reviewing-your-authorized-applications-oauth
|
||||
|
||||
@@ -49,7 +49,7 @@ The events listed in your security log are triggered by your actions. Actions ar
|
||||
| [`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)."
|
||||
| [`marketplace_agreement_signature`](#marketplace_agreement_signature-category-actions) | Contains all activities related to signing the {% data variables.product.prodname_marketplace %} Developer Agreement.
|
||||
| [`marketplace_listing`](#marketplace_listing-category-actions) | Contains all activities related to listing apps in {% data variables.product.prodname_marketplace %}.{% endif %}
|
||||
| [`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 %}
|
||||
| [`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 %}
|
||||
| [`payment_method`](#payment_method-category-actions) | Contains all activities related to paying for your {% data variables.product.prodname_dotcom %} subscription.{% endif %}
|
||||
| [`profile_picture`](#profile_picture-category-actions) | Contains all activities related to your profile picture.
|
||||
| [`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
|
||||
|
||||
| Action | Description
|
||||
|------------------|-------------------
|
||||
| `create` | Triggered when you [grant access to an {% data variables.product.prodname_oauth_app %}](/articles/authorizing-oauth-apps).
|
||||
| `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).
|
||||
| `destroy` | Triggered when you [revoke an {% data variables.product.prodname_oauth_app %}'s access to your account](/articles/reviewing-your-authorized-integrations).
|
||||
|
||||
{% ifversion fpt %}
|
||||
|
||||
Reference in New Issue
Block a user