From 3a885d5a676bd026f8bf001c8f61834aff0981f9 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Thu, 30 Mar 2023 15:19:56 -0700 Subject: [PATCH] Choosing app permissions (#35636) Co-authored-by: Indigo Co-authored-by: Hirsch Singhal <1666363+hpsin@users.noreply.github.com> Co-authored-by: Jess Hosman <1183847+jhosman@users.noreply.github.com> --- ...enticating-as-a-github-app-installation.md | 8 ++- ...g-with-a-github-app-on-behalf-of-a-user.md | 2 +- .../choosing-permissions-for-a-github-app.md | 69 +++++++++++++++++++ .../creating-a-github-app.md | 2 +- .../creating-github-apps/index.md | 3 +- .../setting-permissions-for-github-apps.md | 19 ----- .../using-webhooks-with-github-apps.md | 2 +- .../editing-a-github-apps-permissions.md | 2 +- .../shortdesc/permissions_github_apps.md | 1 - 9 files changed, 80 insertions(+), 28 deletions(-) create mode 100644 content/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app.md delete mode 100644 content/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps.md delete mode 100644 data/reusables/shortdesc/permissions_github_apps.md diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md index 78b74ad77b..6e7c5cd3d6 100644 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md +++ b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md @@ -19,10 +19,12 @@ For example, if you want your app to change the `Status` field of an issue on a To make an API request as an installation, you must first generate an installation access token. Then, you will send the installation access token in the `Authorization` header of your subsequent API requests. You can also use {% data variables.product.company_short %}'s Octokit SDKs, which can generate an installation access token for you. -If a REST API endpoint works with a {% data variables.product.prodname_github_app %} installation access token, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." Additionally, your app must have the required permissions to use the endpoint. For more information about the permissions required for REST API endpoints, see "[Permissions required for GitHub Apps](/rest/overview/permissions-required-for-github-apps)." +If a REST API endpoint works with a {% data variables.product.prodname_github_app %} installation access token, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." Additionally, your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." App installations can also use the GraphQL API. Similar to the REST API, the app must have certain permissions to access objects in the GraphQL API. For GraphQL requests, you should test you app to ensure that your app has the required permissions for the GraphQL queries and mutations that you want to make. +You can also use an installation access token to authenticate for HTTP-based Git access. You app must have the "Contents" repository permission. You can then use the installation access token as the HTTP password. Replace `TOKEN` with the installation access token: `git clone https://x-access-token:TOKEN@github.com/owner/repo.git"`. + Requests made with an installation access token are sometimes called "server-to-server" requests. For more information about authenticating as an app on behalf of a user instead of as an app installation, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)". @@ -39,7 +41,7 @@ To authenticate as an installation with an installation access token, first use To authenticate with an installation access token, include it in the `Authorization` header of an API request. The access token will work with both the GraphQL API and the REST API. -Your app must have the required permissions to use the endpoint. For more information about the permissions required for REST API endpoints, see "[Permissions required for GitHub Apps](/rest/overview/permissions-required-for-github-apps)." For GraphQL requests, you should test your app to ensure that it has the required permissions for the GraphQL queries and mutations that you want to make. +Your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." In the following example, replace `INSTALLATION_ACCESS_TOKEN` with an installation access token: @@ -89,7 +91,7 @@ You must install and import `octokit` in order to use the Octokit.js library. Th 1. Use an `octokit` method to make a request to the API. - Your app must have the required permissions to use the endpoint. For more information about the permissions required for REST API endpoints, see "[Permissions required for GitHub Apps](/rest/overview/permissions-required-for-github-apps)." For GraphQL requests, you should test you app to ensure that your app has the required permissions for the GraphQL queries and mutations that you want to make. + Your app must have the required permissions to use the endpoint. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." For example, to make a request to the GraphQL API: diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user.md index 13a589b3bd..1a7db6dab2 100644 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user.md +++ b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user.md @@ -26,7 +26,7 @@ Similarly, if the request triggers a corresponding entry in the audit logs and s To make an API request on behalf of a user, the user must authorize your app. If an app is installed on an organization that includes multiple members, each member will need to authorize the app before the app can act on their behalf. An app does not need to be installed in order for a user to authorize the app. -When a user installs an app on their account or organization, they grant the app permission to access the organization and repository resources that it requested. During the installation process, they will also see a list of user permissions that the app can request for individual users. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the user permissions that the app requested. +When a user installs an app on their account or organization, they grant the app permission to access the organization and repository resources that it requested. During the installation process, they will also see a list of account permissions that the app can request for individual users. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the account permissions that the app requested. Once a user has authorized your app, you can generate a user access token, which is a type of OAuth token. You should send the user access token in the `Authorization` header of your subsequent API requests. For more information about prompting a user to authorize your app and generating a user access token, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)." diff --git a/content/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app.md b/content/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app.md new file mode 100644 index 0000000000..fbd2a74bf4 --- /dev/null +++ b/content/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app.md @@ -0,0 +1,69 @@ +--- +title: Choosing permissions for a GitHub App +shortTitle: Permissions +intro: "The permissions of a GitHub App determine what the app can do with {% data variables.product.company_short %}'s APIs and what webhooks the app can receive." +redirect_from: + - /apps/building-integrations/setting-up-and-registering-github-apps/about-permissions-for-github-apps + - /apps/building-github-apps/permissions-for-github-apps + - /apps/building-github-apps/setting-permissions-for-github-apps + - /developers/apps/setting-permissions-for-github-apps + - /developers/apps/building-github-apps/setting-permissions-for-github-apps + - /apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - GitHub Apps +--- + +## About {% data variables.product.prodname_github_app %} permissions + +{% data variables.product.prodname_github_app %}s don't have any permissions by default. When you create an app, you can select permissions for the app. The permissions that you select determine what the app can do with {% data variables.product.company_short %}'s APIs and what webhooks the app can subscribe to. You should select the minimum permissions required for the app. + +App permissions are classified as repository, organization, or account permissions. Repository permissions allow your app to access resources related to repositories that are owned by the account where the app is installed. Organization permissions allow your app to access resources related to the organization where the app is installed, if it is installed on an organization account. Account permissions allow your app to access resources related to a user if the user has also authorized your app. For more information about user authorization of apps, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)." + +When a user installs an app on their account or organization, they see and grant the repository and organization permissions that the app requested. They will also see a list of account permissions that the app can request for individual users. When a user authorizes an app to act on their behalf, they will see and grant the account permissions that the app requested. + +You can modify the permissions for your app at any time. When you modify the permissions, the owner of each account where the app was installed will be prompted to approve the new permissions. If the account owner does not approve the new permissions, their installation will continue to use the old permissions. + +Some webhooks and API access requires "Administration" permissions. If your app requires "Administration" permissions, consider explaining this requirement on your app's homepage. This will help users understand why your app needs a high level permission. + +For more information about specifying permissions during app creation, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)." For more information about modifying permissions, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)." + +## Choosing permissions for webhook access + +The webhook documentation indicates whether each webhook is available to {% data variables.product.prodname_github_app %}s. For each webhook that you want to subscribe to, refer to the webhook documentation to see what permissions a {% data variables.product.prodname_github_app %} needs to subscribe to that webhook. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)." + +For example, if you want your app to subscribe to `team` events, your app must have the "Members" organization permission. + +On your app settings page, the available webhook events will change as you change your app's permissions. If you did not select sufficient permissions for your app to subscribe to an event, the event will not appear as an option on your app settings page. + +## Choosing permissions for REST API access + +For more information about which REST API endpoints you can access with each permission, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps)." Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For more information, see the documentation for the endpoint. + +For example, to use the `GET /orgs/{org}/dependabot/secrets` endpoint, your app must have at least read-level permission for the "organization dependabot secrets" permission. + +The success of an API request with a user access token depends on the user's permissions as well as the app's permissions. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. The success of an API request with an installation access token only depends on the app's permissions. + +If your app makes a REST API request with insufficient permissions, the API will return a `403` response. + +## Choosing permissions for GraphQL API access + +For GraphQL requests, you should test your app to ensure that it has the required permissions for the GraphQL queries and mutations that you want to make. + +The success of an API request with a user access token depends on the user's permissions as well as the app's permissions. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. The success of an API request with an installation access token only depends on the app's permissions. + +If your app makes a GraphQL API query or mutation with insufficient permissions, the API will return a `401` response. + +## Choosing permissions for Git access + +If you want your app to use an installation access token to authenticate for HTTP-based Git access, you should request the "Contents" repository permission. + +You can then use the installation access token as the HTTP password. Replace `TOKEN` with the installation access token: + +``` +git clone https://x-access-token:TOKEN@github.com/owner/repo.git" +``` diff --git a/content/apps/creating-github-apps/creating-github-apps/creating-a-github-app.md b/content/apps/creating-github-apps/creating-github-apps/creating-a-github-app.md index 40a07f14d1..7b2479ccbd 100644 --- a/content/apps/creating-github-apps/creating-github-apps/creating-a-github-app.md +++ b/content/apps/creating-github-apps/creating-github-apps/creating-a-github-app.md @@ -52,7 +52,7 @@ You can create a {% data variables.product.prodname_github_app %} owned by your 1. If you selected **Active** in the previous step, under "Webhook URL", enter the URL that {% data variables.product.company_short %} should send webhook events to. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)." 1. Optionally, if you selected **Active** in the previous step, under "Webhook secret", enter a secret token to secure your webhooks. {% data variables.product.company_short %} highly recommends that you set a webhook secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)." 1. If you entered a webhook URL, under "SSL verification", select whether to enable SSL verification. {% data variables.product.company_short %} highly recommends that you enable SSL verification. -1. Under "Permissions", choose the permissions that your app needs. For each permission, select the dropdown menu and click **Read-only**, **Read & write**, or **No access**. You should select the minimum permissions necessary for your app. +1. Under "Permissions", choose the permissions that your app needs. For each permission, select the dropdown menu and click **Read-only**, **Read & write**, or **No access**. You should select the minimum permissions necessary for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." 1. If you selected **Active** in the earlier step to indicate that your app should receive webhook events, under "Subscribe to events", select the webhook events that you want your app to receive. The permissions that you selected in the previous step determine what webhook events are available. For more information about each webhook event, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)." 1. Under "Where can this GitHub App be installed?", select **Only on this account** or **Any account**. For more information on installation options, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private)." 1. Click **Create GitHub App**. diff --git a/content/apps/creating-github-apps/creating-github-apps/index.md b/content/apps/creating-github-apps/creating-github-apps/index.md index d67dcd0f70..c0e3c454c0 100644 --- a/content/apps/creating-github-apps/creating-github-apps/index.md +++ b/content/apps/creating-github-apps/creating-github-apps/index.md @@ -16,10 +16,11 @@ children: - /rate-limits-for-github-apps - /creating-a-github-app - /using-webhooks-with-github-apps - - /setting-permissions-for-github-apps + - /choosing-permissions-for-a-github-app - /making-a-github-app-public-or-private - /creating-a-github-app-from-a-manifest - /creating-a-github-app-using-url-parameters - /creating-a-custom-badge-for-your-github-app - /about-the-user-authorization-callback-url --- + diff --git a/content/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps.md b/content/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps.md deleted file mode 100644 index b9095b6bbb..0000000000 --- a/content/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Setting permissions for GitHub Apps -intro: '{% data reusables.shortdesc.permissions_github_apps %}' -redirect_from: - - /apps/building-integrations/setting-up-and-registering-github-apps/about-permissions-for-github-apps - - /apps/building-github-apps/permissions-for-github-apps - - /apps/building-github-apps/setting-permissions-for-github-apps - - /developers/apps/setting-permissions-for-github-apps - - /developers/apps/building-github-apps/setting-permissions-for-github-apps -versions: - fpt: '*' - ghes: '*' - ghae: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Set permissions ---- -GitHub Apps don't have any permissions by default. When you create a GitHub App, you can select the permissions it needs to access end user data. Permissions can also be added and removed. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)." diff --git a/content/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps.md b/content/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps.md index 1e13bbf7df..a48dd9d760 100644 --- a/content/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps.md +++ b/content/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps.md @@ -54,7 +54,7 @@ After creating a webhook secret for your app, you will need to configure your se ## Subscribing to webhook events -You can subscribe your {% data variables.product.prodname_github_app %} to receive webhook payloads for specific events. The specific webhook events that you can select in your app settings are determined by the type of permissions you selected for your app. You will first need to select the permissions you would like your app to have, and then you can subscribe your app to webhook events that are related to that set of permissions. +You can subscribe your {% data variables.product.prodname_github_app %} to receive webhook payloads for specific events. The specific webhook events that you can select in your app settings are determined by the type of permissions you selected for your app. You will first need to select the permissions you would like your app to have, and then you can subscribe your app to webhook events that are related to that set of permissions. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." For example, if you would like your app to receive a webhook event payload whenever a new issue is opened in your repository, you would first need to give your app permission to access "Issues" under "Repository permissions." Then under "Subscribe to events" you can select "Issues." diff --git a/content/apps/maintaining-github-apps/editing-a-github-apps-permissions.md b/content/apps/maintaining-github-apps/editing-a-github-apps-permissions.md index dce5bbff96..280cd3816f 100644 --- a/content/apps/maintaining-github-apps/editing-a-github-apps-permissions.md +++ b/content/apps/maintaining-github-apps/editing-a-github-apps-permissions.md @@ -26,7 +26,7 @@ shortTitle: Edit permissions {% data reusables.user-settings.github_apps %} {% data reusables.user-settings.modify_github_app %} 5. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**. -6. Under "Repository permissions", "Organization permissions", and "Account permissions" sections, modify the permissions you'd like to change. For each type of permission, select either "Read-only", "Read and write", or "No access" from the dropdown. +6. Under "Repository permissions", "Organization permissions", and "Account permissions" sections, modify the permissions you'd like to change. For each type of permission, select either "Read-only", "Read and write", or "No access" from the dropdown. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)." 7. Under "Subscribe to events", select any events to which you'd like to subscribe your app. 8. Optionally, under "Add a note to users", add a note telling your users why you are changing the permissions that your GitHub App requests. 9. Click **Save changes**. diff --git a/data/reusables/shortdesc/permissions_github_apps.md b/data/reusables/shortdesc/permissions_github_apps.md deleted file mode 100644 index fe03198b1a..0000000000 --- a/data/reusables/shortdesc/permissions_github_apps.md +++ /dev/null @@ -1 +0,0 @@ -When you create a GitHub App, you set the permissions that define the resources the app can access via the REST API.