Skip to content

Commit

Permalink
Update article about app authorization (#36674)
Browse files Browse the repository at this point in the history 
Co-authored-by: James Martin <[email protected]>
Co-authored-by: Sarita Iyer <[email protected]>
  • Loading branch information
@skedwards88 @jamesmartin @saritai
3 people authored May 1, 2023
1 parent e738bfd commit 27aa43f
Showing 1 changed file with 20 additions and 27 deletions.
47 changes: 20 additions & 27 deletions content/apps/using-github-apps/authorizing-github-apps.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
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.'
intro: 'You can authorize a {% data variables.product.prodname_github_app %} to retrieve information about your {% data variables.product.company_short %} account and to make changes on your behalf.'
versions:
fpt: '*'
ghes: '*'
Expand All @@ -9,49 +9,42 @@ versions:
topics:
- Identity
- Access management
- GitHub Apps
redirect_from:
- /github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps
- /authentication/keeping-your-account-and-data-secure/authorizing-github-apps
---

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.
## About authorizing {% data variables.product.prodname_github_app %}s

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.
Third-party applications that need to verify your {% data variables.product.company_short %} identity or interact with {% data variables.product.company_short %} on your behalf can ask you to authorize a {% 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 owner and review the information that 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.
During authorization, you'll be prompted to grant the {% data variables.product.prodname_github_app %} permission to do all of the following:

## When does a {% data variables.product.prodname_github_app %} act on your behalf?
* Verify your {% data variables.product.company_short %} identity: When authorized, the {% data variables.product.prodname_github_app %} will be able to retrieve your public GitHub profile. The app may also be able to retrieve some private account information. During the authorization process, {% data variables.product.company_short %} will tell you which account information the {% data variables.product.prodname_github_app %} will be able to access.
* Know which resources you can access: When authorized, the {% data variables.product.prodname_github_app %} will be able to determine which resources you can access that the app can also access. The app may use this, for example, so that it can show you an appropriate list of repositories.
* Act on your behalf: When authorized, the application may perform tasks on {% data variables.product.company_short %} on your behalf. This might include creating an issue or commenting on a pull request. For more information, see "[About {% data variables.product.prodname_github_app %}s acting on your behalf](#about-github-apps-acting-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.
You can review and revoke your authorization at any time. For more information, see "[AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations)."

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 %}.
## Difference between authorization and installation

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.
When you install a {% data variables.product.prodname_github_app %} on your account or organization, you grant the app permission to access the organization and repository resources that it requested. You also specify which repositories the app can access.

![Screenshot of a comment that has the special avatar with an overlaid bot icon. The avatar is highlighted with an orange outline.](/assets/images/help/apps/github-app-acting-on-your-behalf.png)
When you authorize a {% data variables.product.prodname_github_app %} you grant the app access to your GitHub account, based on the account permissions the app requested. You also grant the app permission to act on your behalf.

## To what extent can a {% data variables.product.prodname_github_app %} know which resources you can access and act on your behalf?
You can install a {% data variables.product.prodname_github_app %} without authorizing the app. Similarly, you can authorize the app without installing the app.

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:
For more information about installation, see {% ifversion ghec or fpt %}"[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-personal-account)" and "[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-organization)."{% else %}"[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps)."{% endif %}

* 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
## About {% data variables.product.prodname_github_app %}s acting on your behalf

Let's use an example to explain this.
Once you authorize a {% data variables.product.prodname_github_app %}, the app can 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.company_short %}.

{% 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.
The {% data variables.product.prodname_github_app %} can only do things that both you and the app have permission to do. For example, if you have write access to a repository but the {% data variables.product.prodname_github_app %} only has read access, then the app can only read the contents of the repository even when it is acting on your behalf. Similarly, if you have access to repositories `A` and `B`, and the {% data variables.product.prodname_github_app %} has access to repositories `B` and `C`, then the app can only access repository `B` when acting on your 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.
When an app acts on your behalf, it will attribute the activity to you in conjunction with the app. For example, if the app posts a comment on your behalf, the {% data variables.product.company_short %} UI will show your avatar photo along with the app's identicon badge as the author of the issue.

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:
![Screenshot of a comment that has a user avatar with an overlaid app identicon badge. The avatar is highlighted with an orange outline.](/assets/images/help/apps/github-app-acting-on-your-behalf.png)

* 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 A.
* Alice must have read permission for Repo A. For information about which permissions are required to perform various activities, see "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization)."
Similarly, if the activity triggers a corresponding entry in the audit logs and security logs, the logs will list you as the actor but will state that the "programmatic_access_type" is "GitHub App user-to-server token".

0 comments on commit 27aa43f

Please sign in to comment.