diff --git a/assets/images/help/apps/github-apps-new-issue.png b/assets/images/help/apps/github-apps-new-issue.png new file mode 100644 index 0000000000..ff2d558761 Binary files /dev/null and b/assets/images/help/apps/github-apps-new-issue.png differ diff --git a/content/developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps.md b/content/developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps.md index 16dbb787e1..db988a455e 100644 --- a/content/developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps.md +++ b/content/developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps.md @@ -100,4 +100,4 @@ Once your GitHub App has been installed on a repository, you should remove any u ### Encourage users to revoke access to your OAuth app -As your GitHub App installation base grows, consider encouraging your users to [revoke access](/articles/authorizing-oauth-apps/) to the legacy OAuth integration. +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) diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md new file mode 100644 index 0000000000..aa1fdac706 --- /dev/null +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps.md @@ -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**
+ 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**
+ 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**
+ 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. + +![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) + +## 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 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)." diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps.md index e17d626f73..a482176f04 100644 --- a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps.md +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps.md @@ -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 %} diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md index bc769f4a57..aa75edef20 100644 --- a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/index.md @@ -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 diff --git a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md index 2a0e5f8359..99042955a9 100644 --- a/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md +++ b/content/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log.md @@ -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 %} diff --git a/content/github/customizing-your-github-workflow/exploring-integrations/about-integrations.md b/content/github/customizing-your-github-workflow/exploring-integrations/about-integrations.md index 834ab8f086..b3320317bb 100644 --- a/content/github/customizing-your-github-workflow/exploring-integrations/about-integrations.md +++ b/content/github/customizing-your-github-workflow/exploring-integrations/about-integrations.md @@ -19,7 +19,8 @@ For more information, see: - "[Differences between {% data variables.product.prodname_github_app %}s and {% data variables.product.prodname_oauth_app %}s](/apps/differences-between-apps/)" - "[About apps](/apps/about-apps/)" - "[User-level permissions](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-level-permissions)" -- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/articles/authorizing-oauth-apps/)" +- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps)" +- "[Authorizing {% data variables.product.prodname_github_apps %}](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps)" - "[Reviewing your authorized integrations](/articles/reviewing-your-authorized-integrations/)" 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. diff --git a/content/organizations/restricting-access-to-your-organizations-data/about-oauth-app-access-restrictions.md b/content/organizations/restricting-access-to-your-organizations-data/about-oauth-app-access-restrictions.md index 2b73f8aed8..6e9ef48f49 100644 --- a/content/organizations/restricting-access-to-your-organizations-data/about-oauth-app-access-restrictions.md +++ b/content/organizations/restricting-access-to-your-organizations-data/about-oauth-app-access-restrictions.md @@ -58,4 +58,4 @@ If an organization disables {% data variables.product.prodname_oauth_app %} acce - "[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)" - "[Disabling {% data variables.product.prodname_oauth_app %} access restrictions for your organization](/articles/disabling-oauth-app-access-restrictions-for-your-organization)" - "[Requesting organization approval for {% data variables.product.prodname_oauth_app %}s](/articles/requesting-organization-approval-for-oauth-apps)" -- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/articles/authorizing-oauth-apps)" +- "[Authorizing {% data variables.product.prodname_oauth_app %}s](/github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps)" diff --git a/data/glossaries/external.yml b/data/glossaries/external.yml index bf3b4c3900..72290b28f8 100644 --- a/data/glossaries/external.yml +++ b/data/glossaries/external.yml @@ -678,6 +678,9 @@ description: >- A log that lists the last 50 actions or those performed within the last 90 days. +- term: server-to-server request + description: >- + 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)." - term: service hook description: >- Also called "webhook." Webhooks provide a way for notifications to be @@ -764,6 +767,9 @@ invited to join organizations or collaborate on another user's repository. - term: username description: A user's handle on GitHub. +- term: user-to-server request + description: >- + 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)." - term: visible team description: A team that can be viewed and @mentioned by every organization member. - term: watch