From 222be165822bda2bd03d166327f8f86e461f24f4 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Tue, 7 Mar 2023 10:18:44 -0800 Subject: [PATCH] Add App authentication overview article (#35271) Co-authored-by: Jess Hosman <1183847+jhosman@users.noreply.github.com> --- ...o-your-enterprise-with-an-ip-allow-list.md | 2 +- ...for-your-idps-conditional-access-policy.md | 2 +- .../about-authentication-with-a-github-app.md | 31 +++ .../authenticating-with-github-apps.md | 231 ------------------ .../authenticating-with-a-github-app/index.md | 5 +- ...nces-between-github-apps-and-oauth-apps.md | 2 +- .../making-a-github-app-public-or-private.md | 2 +- .../migrating-oauth-apps-to-github-apps.md | 4 +- ...ment-environment-to-create-a-github-app.md | 6 +- content/apps/index.md | 4 +- .../security-best-practices-for-apps.md | 2 +- ...ndpoints-for-the-github-marketplace-api.md | 2 +- .../managing-deploy-keys.md | 6 +- .../about-authentication-to-github.md | 4 +- .../guides/forming-calls-with-graphql.md | 2 +- .../automating-projects-using-actions.md | 2 +- .../using-the-api-to-manage-projects.md | 2 +- content/rest/apps/apps.md | 2 +- content/rest/apps/installations.md | 2 +- .../getting-started-with-the-rest-api.md | 2 +- ...ipting-with-the-rest-api-and-javascript.md | 4 +- .../endpoints-available-for-github-apps.md | 2 +- content/rest/quickstart.md | 6 +- content/rest/scim.md | 2 +- .../shortdesc/authenticating_github_app.md | 2 +- 25 files changed, 66 insertions(+), 265 deletions(-) create mode 100644 content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md delete mode 100644 content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps.md diff --git a/content/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list.md b/content/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list.md index 367551428d48..1212c281055d 100644 --- a/content/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list.md +++ b/content/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list.md @@ -52,7 +52,7 @@ Using your IdP's allow list deactivates the {% data variables.product.company_sh By default, your IdP runs the CAP on the initial interactive SAML or OIDC sign-in to {% data variables.product.company_short %} for any IP allow list configuration you choose. -The OIDC CAP only applies for requests to the API using a user-to-server token, such as a token for an {% data variables.product.prodname_oauth_app %} or a {% data variables.product.prodname_github_app %} acting on behalf of a user. The OIDC CAP does not apply when a {% data variables.product.prodname_github_app %} uses a server-to-server token. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation)" and "[AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy#github-apps-and-oauth-apps)." +The OIDC CAP only applies for requests to the API using a user-to-server token, such as a token for an {% data variables.product.prodname_oauth_app %} or a {% data variables.product.prodname_github_app %} acting on behalf of a user. The OIDC CAP does not apply when a {% data variables.product.prodname_github_app %} uses a server-to-server token. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)" and "[AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy#github-apps-and-oauth-apps)." To ensure seamless use of the OIDC CAP while still applying the policy to user-to-server tokens, you must copy all of the IP ranges from each {% data variables.product.prodname_github_app %} that your enterprise uses to your IdP policy. diff --git a/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy.md b/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy.md index c35087993ce7..c3a0f1853226 100644 --- a/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy.md +++ b/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy.md @@ -39,7 +39,7 @@ If you're unable to use a service account, another option for unblocking actions When {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} sign a user in and make requests on that user's behalf, also known as a [`user-to-server` request](/get-started/quickstart/github-glossary#user-to-server-request), {% data variables.product.prodname_dotcom %} will send the IP address of the app's server to your IdP for validation. If the IP address of the app's server is not validated by your IdP's CAP, the request will fail. -When {% data variables.product.prodname_github_apps %} call {% data variables.product.prodname_dotcom %} APIs acting either as the app itself or as an installation, these calls are not performed on behalf of a user - this is also known as a [`server-to-server` request](/get-started/quickstart/github-glossary#server-to-server-request). Since your IdP's CAP executes and applies policies to user accounts, these application requests cannot be validated against CAP and are always allowed through. For more information on {% data variables.product.prodname_github_apps %} authenticating as themselves, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app)". +When {% data variables.product.prodname_github_apps %} call {% data variables.product.prodname_dotcom %} APIs acting either as the app itself or as an installation, these calls are not performed on behalf of a user. Since your IdP's CAP executes and applies policies to user accounts, these application requests cannot be validated against CAP and are always allowed through. For more information on {% data variables.product.prodname_github_apps %} authenticating as themselves or as an installation, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)". You can contact the owners of the apps you want to use, ask for their IP ranges, and configure your IdP's CAP to allow access from those IP ranges. If you're unable to contact the owners, you can review your IdP sign-in logs to review the IP addresses seen in the requests, then allow-list those addresses. diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md new file mode 100644 index 000000000000..817c3b1ca6ca --- /dev/null +++ b/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md @@ -0,0 +1,31 @@ +--- +title: About authentication with a GitHub App +intro: 'Your {% data variables.product.prodname_github_app %} can authenticate as itself, as an app installation, or on behalf of a user.' +versions: + fpt: '*' + ghes: '*' + ghae: '*' + ghec: '*' +topics: + - GitHub Apps +shortTitle: Authentication overview +redirect_from: + - /apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps + - /apps/building-github-apps/authentication-options-for-github-apps + - /apps/building-github-apps/authenticating-with-github-apps + - /developers/apps/authenticating-with-github-apps + - /developers/apps/building-github-apps/authenticating-with-github-apps + - /apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps +--- + +## Authentication as a {% data variables.product.prodname_github_app %} + +Your app should authenticate as itself when it needs to generate an installation access token. An installation access token is required to authenticate as an app installation. Your app should also authenticate as itself when it needs to make API requests to manage resources related to the app. For example, when it needs to list the accounts where it is installed. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app)". + +## Authentication as an app installation + +Your app should authenticate as an app installation when you want to attribute app activity to the app. Authenticating as an app installation lets your app access resources that are owned by the user or organization that installed the app. Authenticating as an app installation is ideal for automation workflows that don't involve user input. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)." + +## Authentication on behalf of a user + +Your app should authenticate on behalf of a user when you want to attribute app activity to a user. Similar to authenticating as an app installation, your app can access resources that are owned by the user or organization that installed the app. Authenticating on behalf of a user is ideal when you want to ensure that your app only takes actions that could be performed by a specific user. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps.md deleted file mode 100644 index 045be77ecbdd..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: Authenticating with GitHub Apps -intro: '{% data reusables.shortdesc.authenticating_with_github_apps %}' -redirect_from: - - /apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps - - /apps/building-github-apps/authentication-options-for-github-apps - - /apps/building-github-apps/authenticating-with-github-apps - - /developers/apps/authenticating-with-github-apps - - /developers/apps/building-github-apps/authenticating-with-github-apps -versions: - fpt: '*' - ghes: '*' - ghae: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Authentication ---- - -## Authenticating as a {% data variables.product.prodname_github_app %} - -Authenticating as a {% data variables.product.prodname_github_app %} is required for [`server-to-server`](/get-started/quickstart/github-glossary#server-to-server-request) API calls, which let your {% data variables.product.prodname_github_app %} do a couple things: - -* Retrieve high-level management information about your {% data variables.product.prodname_github_app %}. -* Request access tokens for an installation of the app, allowing you to make API calls without a signed-in user. - -To authenticate as a {% data variables.product.prodname_github_app %}, [generate a private key](#generating-a-private-key) in PEM format and download it to your local machine. You'll use this key to [sign a JSON Web Token (JWT)](#jwt-payload) and encode it using the `RS256` algorithm. {% data variables.product.product_name %} validates your app's identity by verifying the token with the app's stored public key. You'll exchange this JWT for an installation token, used to authenticate your app as a specific installation. - -### Listing the installations for an app - -To list the installations for your app, include the JWT in the Authorization header in an API request to `GET /app/installations`. For more information about generating a JWT, see "[JWT payload](#jwt-payload)." - -```shell -$ curl -i -X GET \ --H "Authorization: Bearer YOUR_JWT" \ --H "Accept: application/vnd.github+json" \ -{% data variables.product.api_url_pre %}/app/installations -``` - -The response will include a list of installations where each installation's `id` can be used for creating an installation access token. For more information about the response format, see "[AUTOTITLE](/rest/apps#list-installations-for-the-authenticated-app)." - -## Authenticating as an installation - -Authenticating as an installation lets your app access that organization or user via the API, as well as public resources on {% data variables.product.product_name %}. To authenticate as an installation, you must use an installation access token, which you get by sending a [JWT](#jwt-payload) to {% data variables.product.product_name %} to prove your app's identity. Ensure that you have already installed your GitHub App to at least one organization or user account; it is impossible to create an installation token without an installation. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps)." - -By default, installation access tokens are scoped to all the repositories that an installation was granted access to. You can further limit the scope of the installation access token to specific repositories by using the `repository_ids` parameter. Installation access tokens have the permissions configured by the {% data variables.product.prodname_github_app %}, and like repository access, can also be scoped down using the `permissions` parameter. For more information, see the [Create an installation access token for an app](/rest/apps#create-an-installation-access-token-for-an-app) endpoint documentation. All installation tokens expire after 1 hour. - -To create an installation access token, include the JWT in the Authorization header in the API request, replacing `:installation_id` with the installation's `id`. For more information about generating a JWT, see "[JWT payload](#jwt-payload)." - -```shell -$ curl -i -X POST \ --H "Authorization: Bearer YOUR_JWT" \ --H "Accept: application/vnd.github+json" \ -{% data variables.product.api_url_pre %}/app/installations/:installation_id/access_tokens -``` - -The response will include your installation access token, the expiration date, the token's permissions, and the repositories that the token can access. For more information about the response format, see the [Create an installation access token for an app](/rest/apps#create-an-installation-access-token-for-an-app) endpoint. - -To authenticate with an installation access token, include it in the Authorization header in the API request. Replace `YOUR_INSTALLATION_ACCESS_TOKEN` with an installation access token: - -```shell -$ curl -i \ --H "Authorization: Bearer YOUR_INSTALLATION_ACCESS_TOKEN" \ --H "Accept: application/vnd.github+json" \ -{% data variables.product.api_url_pre %}/installation/repositories -``` - -{% note %} - -**Note:** {% data reusables.getting-started.bearer-vs-token %} - -{% endnote %} - -## Accessing API endpoints as an installation - -For a list of REST API endpoints that are available for use by {% data variables.product.prodname_github_apps %} using an installation access token, see "[AUTOTITLE](/rest/overview/endpoints-available-for-github-apps)." - -For a list of endpoints related to installations, see "[AUTOTITLE](/rest/apps#installations)." - -## HTTP-based Git access by an installation - -Installations with [permissions](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps) on `contents` of a repository, can use their installation access tokens to authenticate for Git access. Use the installation access token as the HTTP password: - -```shell -git clone https://x-access-token:<token>@github.com/owner/repo.git -``` - -## Generating a JSON Web Token (JWT) - -The [JWT](https://jwt.io/) that's used to authenticate your application is made up of several claims, as well as a signature that's used to validate its authenticity. Those claims are: - -|Claim | Meaning | Details | -|---|---|---| -|`iat`| Issued At | The time the JWT was created. To protect against clock drift, we recommend you set this 60 seconds in the past. | -|`exp`| Expires At | The expiration time of the JWT, after which it can't be used to request an installation token. The `exp` must be no more than 10 minutes into the future. | -|`iss`| Issuer | Your application ID, used to find the right public key to verify the signature of the JWT. | - -Tokens must be signed using the `RS256` algorithm, with a matching `alg` claim of `RS256`. - -### Using Ruby - -Here's a Ruby script you can use to generate a JWT. Note you'll have to run `gem install jwt` before using it. `YOUR_PATH_TO_PEM` and `YOUR_APP_ID` are the values you must replace. Make sure to enclose the values in double quotes. - - -```ruby -require 'openssl' -require 'jwt' # https://rubygems.org/gems/jwt - -# Private key contents -private_pem = File.read("YOUR_PATH_TO_PEM") -private_key = OpenSSL::PKey::RSA.new(private_pem) - -# Generate the JWT -payload = { - # issued at time, 60 seconds in the past to allow for clock drift - iat: Time.now.to_i - 60, - # JWT expiration time (10 minute maximum) - exp: Time.now.to_i + (10 * 60), - # {% data variables.product.prodname_github_app %}'s identifier - iss: "YOUR_APP_ID" -} - -jwt = JWT.encode(payload, private_key, "RS256") -puts jwt -``` - -#### Using Python - -Here is a similar script for generating a JWT in Python. Note you will have to use `pip install jwt` in order to use this script. This script will prompt you for the location of your PEM file and your app's ID, or you can pass them as inline arguments when you execute the script. - -```python{:copy} -#!/usr/bin/env python3 -import jwt -import time -import sys - - -# Get PEM file path -if len(sys.argv) > 1: - pem = sys.argv[1] -else: - pem = input("Enter path of private PEM file: ") - -# Get the App ID -if len(sys.argv) > 2: - app_id = sys.argv[2] -else: - app_id = input("Enter your APP ID: ") - -# Open PEM -with open(pem, 'rb') as pem_file: - signing_key = jwt.jwk_from_pem(pem_file.read()) - -payload = { - # Issued at time - 'iat': int(time.time()), - # JWT expiration time (10 minutes maximum) - 'exp': int(time.time()) + 600, - # GitHub App's identifier - 'iss': app_id -} - -# Create JWT -jwt_instance = jwt.JWT() -encoded_jwt = jwt_instance.encode(payload, signing_key, alg='RS256') - -print(f"JWT: ", encoded_jwt) -``` - -Use your {% data variables.product.prodname_github_app %}'s identifier (`YOUR_APP_ID`) as the value for the JWT [iss](https://tools.ietf.org/html/rfc7519#section-4.1.1) (issuer) claim. You can obtain the {% data variables.product.prodname_github_app %} identifier via the initial webhook ping after [creating the app](/apps/creating-github-apps/creating-github-apps/creating-a-github-app), or at any time from the app settings page in the GitHub.com UI. - -After creating the JWT, set it in the `Header` of the API request: - -```shell -$ curl -i -H "Authorization: Bearer YOUR_JWT" -H "Accept: application/vnd.github+json" {% data variables.product.api_url_pre %}/app -``` - -`YOUR_JWT` is the value you must replace. - -The examples above uses the maximum expiration time of 10 minutes, after which the API will start returning a `401` error: - -```json -{ - "message": "'Expiration' claim ('exp') must be a numeric value representing the future time at which the assertion expires.", - "documentation_url": "{% data variables.product.doc_url_pre %}" -} -``` - -You'll need to create a new JWT after the time expires. - -## Accessing API endpoints as a {% data variables.product.prodname_github_app %} - -For a list of REST API endpoints you can use to get high-level information about a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/rest/apps)." - -## Generating a private key - -After you create a {% data variables.product.prodname_github_app %}, you'll need to generate one or more private keys in order to make requests to the {% data variables.product.product_name %} API as the application itself. You'll use the private key to sign the [JWTs used to request an installation access token](#jwt-payload). - -You can create multiple private keys and rotate them to prevent downtime if a key is compromised or lost. To verify that a private key matches a public key, see [Verifying private keys](#verifying-private-keys). - -To generate a private key: - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -{% data reusables.user-settings.modify_github_app %} -5. Under "Private keys", click **Generate a private key**. -6. You will see a private key in PEM format downloaded to your computer. Make sure to store this file because GitHub only stores the public portion of the key. - -{% note %} - -**Note:** If you're using a library that requires a specific file format, the PEM file you download will be in `PKCS#1 RSAPrivateKey` format. - -{% endnote %} - -## Verifying private keys -{% data variables.product.product_name %} generates a fingerprint for each private and public key pair using the SHA-256 hash function. You can verify that your private key matches the public key stored on {% data variables.product.product_name %} by generating the fingerprint of your private key and comparing it to the fingerprint shown on {% data variables.product.product_name %}. - -To verify a private key: - -1. Find the fingerprint for the private and public key pair you want to verify in the "Private keys" section of your {% data variables.product.prodname_github_app %}'s developer settings page. For more information, see [Generating a private key](#generating-a-private-key). -![Private key fingerprint](/assets/images/github-apps/github_apps_private_key_fingerprint.png) -2. Generate the fingerprint of your private key (PEM) locally by using the following command: - ```shell - $ openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64 - ``` -3. Compare the results of the locally generated fingerprint to the fingerprint you see in {% data variables.product.product_name %}. - -## Deleting private keys -You can remove a lost or compromised private key by deleting it, but you must always have at least one private key registered for your {% data variables.product.prodname_github_app %}. When your {% data variables.product.prodname_github_app %} has only one key, you will need to generate a new one before deleting the old one. -![Deleting last private key](/assets/images/github-apps/github_apps_delete_key.png) diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/index.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/index.md index 0cb69b944e5b..02bbf6d2648f 100644 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/index.md +++ b/content/apps/creating-github-apps/authenticating-with-a-github-app/index.md @@ -1,5 +1,5 @@ --- -title: Authenticating with a {% data variables.product.prodname_github_app %} +title: 'Authenticating with a {% data variables.product.prodname_github_app %}' intro: 'Learn how to set up authentication options for {% data variables.product.prodname_github_apps %}.' versions: fpt: '*' @@ -9,7 +9,7 @@ versions: topics: - GitHub Apps children: - - /authenticating-with-github-apps + - /about-authentication-with-a-github-app - /authenticating-as-a-github-app - /authenticating-as-a-github-app-installation - /managing-private-keys-for-github-apps @@ -18,3 +18,4 @@ children: - /identifying-and-authorizing-users-for-github-apps - /refreshing-user-to-server-access-tokens --- + diff --git a/content/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps.md b/content/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps.md index 246f3f3f732e..b6178e5f3713 100644 --- a/content/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps.md +++ b/content/apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps.md @@ -102,7 +102,7 @@ Unlike OAuth apps, GitHub Apps have targeted permissions that allow them to requ | GitHub Apps | OAuth Apps | | ----- | ----------- | -| GitHub Apps ask for repository contents permission and use your installation token to authenticate via [HTTP-based Git](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#http-based-git-access-by-an-installation). | OAuth Apps ask for `write:public_key` scope and [Create a deploy key](/rest/deployments#create-a-deploy-key) via the API. You can then use that key to perform Git commands. | +| GitHub Apps ask for repository contents permission and use your installation access token to authenticate via HTTP-based Git. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)"| OAuth Apps ask for `write:public_key` scope and [Create a deploy key](/rest/deployments#create-a-deploy-key) via the API. You can then use that key to perform Git commands. | | The token is used as the HTTP password. | The token is used as the HTTP username. | ## Machine vs. bot accounts diff --git a/content/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private.md b/content/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private.md index e6dd1ae1a5ac..f5c1ebd12d29 100644 --- a/content/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private.md +++ b/content/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private.md @@ -18,7 +18,7 @@ topics: - GitHub Apps shortTitle: Manage app visibility --- -For authentication information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation)." +For authentication information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)." ## Public installation flow diff --git a/content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md b/content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md index e69369ed02e0..c64fd122d3f2 100644 --- a/content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md +++ b/content/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps.md @@ -73,8 +73,8 @@ After you've created a new GitHub App and selected its permissions, you can sele GitHub Apps primarily use a token-based authentication that expires after a short amount of time, providing more security than an OAuth token that does not expire. It’s important to understand the different methods of authentication available to you and when you need to use them: -* A **JSON Web Token (JWT)** [authenticates as the GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app). For example, you can authenticate with a **JWT** to fetch application installation details or exchange the **JWT** for an **installation access token**. -* An **installation access token** [authenticates as a specific installation of your GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation) (also called server-to-server requests). For example, you can authenticate with an **installation access token** to open an issue or provide feedback on a pull request. +* A **JSON Web Token (JWT)** [authenticates as the GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app). For example, you can authenticate with a **JWT** to fetch application installation details or exchange the **JWT** for an **installation access token**. +* An **installation access token** [authenticates as a specific installation of your GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app) (also called server-to-server requests). For example, you can authenticate with an **installation access token** to open an issue or provide feedback on a pull request. * An **OAuth access token** can [authenticate as a user of your GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps#identifying-users-on-your-site) (also called user-to-server requests). For example, you can use an OAuth access token to authenticate as a user when a GitHub App needs to verify a user’s identity or act on a user’s behalf. The most common scenario is to authenticate as a specific installation using an **installation access token**. diff --git a/content/apps/creating-github-apps/guides/setting-up-your-development-environment-to-create-a-github-app.md b/content/apps/creating-github-apps/guides/setting-up-your-development-environment-to-create-a-github-app.md index eebf60c8bd02..705342d0b316 100644 --- a/content/apps/creating-github-apps/guides/setting-up-your-development-environment-to-create-a-github-app.md +++ b/content/apps/creating-github-apps/guides/setting-up-your-development-environment-to-create-a-github-app.md @@ -237,7 +237,7 @@ To make API calls, you'll be using the [Octokit library](http://octokit.github.i You'll learn about authenticating as an installation in the [next section](#authenticating-as-an-installation). -[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app) lets you do a couple of things: +[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) lets you do a couple of things: * You can retrieve high-level management information about your GitHub App. * You can request access tokens for an installation of the app. @@ -272,7 +272,7 @@ def authenticate_app end ``` -The code above generates a [JSON Web Token (JWT)](https://jwt.io/introduction) and uses it (along with your app's private key) to initialize the Octokit client. GitHub checks a request's authentication by verifying the token with the app's stored public key. To learn more about how this code works, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app)." +The code above generates a [JSON Web Token (JWT)](https://jwt.io/introduction) and uses it (along with your app's private key) to initialize the Octokit client. GitHub checks a request's authentication by verifying the token with the app's stored public key. To learn more about how this code works, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app)." #### Authenticating as an installation @@ -293,7 +293,7 @@ The [`create_app_installation_access_token`](http://octokit.github.io/octokit.rb * Installation (integer): The ID of a GitHub App installation * Options (hash, defaults to `{}`): A customizable set of options -Any time a GitHub App receives a webhook, it includes an `installation` object with an `id`. Using the client authenticated as a GitHub App, you pass this ID to the `create_app_installation_access_token` method to generate an access token for each installation. Since you're not passing any options to the method, the options default to an empty hash. If you look back at [the docs](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation), you can see the response for `create_app_installation_access_token` includes two fields: `token` and `expired_at`. The template code selects the token in the response and initializes an installation client. +Any time a GitHub App receives a webhook, it includes an `installation` object with an `id`. Using the client authenticated as a GitHub App, you pass this ID to the `create_app_installation_access_token` method to generate an access token for each installation. Since you're not passing any options to the method, the options default to an empty hash. The response for `create_app_installation_access_token` includes two fields: `token` and `expired_at`. The template code selects the token in the response and initializes an installation client. With this method in place, each time your app receives a new webhook payload, it creates a client for the installation that triggered the event. This authentication process enables your GitHub App to work for all installations on any account. diff --git a/content/apps/index.md b/content/apps/index.md index b4ea49dea787..f05016fc47cc 100644 --- a/content/apps/index.md +++ b/content/apps/index.md @@ -10,11 +10,11 @@ featuredLinks: - /apps/creating-github-apps/creating-github-apps/about-apps - /apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps - /apps/creating-github-apps/creating-github-apps/creating-a-github-app - - /apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps + - /apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app - /apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps popular: - /apps/creating-github-apps/creating-github-apps/creating-a-github-app - - /apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps + - /apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app - /apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace guideCards: - /apps/creating-github-apps/guides/creating-ci-tests-with-the-checks-api diff --git a/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps.md b/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps.md index 0acd06c5aff3..0049eb276c55 100644 --- a/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps.md +++ b/content/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps.md @@ -28,7 +28,7 @@ We recommend creating a GitHub App rather than an OAuth App. {% data reusables.m - Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties. - Apps should not use {% data variables.product.pat_generic %}s to authenticate and should authenticate as an [OAuth App](/apps/creating-github-apps/creating-github-apps/about-apps#about-oauth-apps) or a [GitHub App](/apps/creating-github-apps/creating-github-apps/about-apps#about-github-apps): - OAuth Apps should authenticate using an [OAuth token](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). - - GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app), [OAuth token](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps), or [installation access token](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation). + - GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app), [OAuth token](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps), or [installation access token](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app). ## Data protection diff --git a/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md b/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md index 8672d410471a..23be5b4c5085 100644 --- a/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md +++ b/content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md @@ -24,7 +24,7 @@ Here are some useful endpoints available for Marketplace listings: See these pages for details on how to authenticate when using the {% data variables.product.prodname_marketplace %} API: * [Authorization options for OAuth Apps](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) -* [Authentication options for GitHub Apps](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps) +* [Authentication options for GitHub Apps](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) {% note %} diff --git a/content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md b/content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md index 5b5ea9536323..d29ff254f081 100644 --- a/content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md +++ b/content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md @@ -143,10 +143,10 @@ Since GitHub Apps are a first class actor on {% data variables.product.product_ 1. Determine the permissions your GitHub App requires, such as read-only access to repository contents. 1. Create your GitHub App via your organization's settings page. For more information, see [Creating a GitHub App](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). 1. Note your GitHub App `id`. -1. Generate and download your GitHub App's private key, and store this safely. For more information, see [Generating a private key](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#generating-a-private-key). +1. Generate and download your GitHub App's private key, and store this safely. For more information, see [Generating a private key](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). 1. Install your GitHub App on the repositories it needs to act upon, optionally you may install the GitHub App on all repositories in your organization. -1. Identify the `installation_id` that represents the connection between your GitHub App and the organization repositories it can access. Each GitHub App and organization pair have at most a single `installation_id`. You can identify this `installation_id` via [Get an organization installation for the authenticated app](/rest/apps#get-an-organization-installation-for-the-authenticated-app). This requires authenticating as a GitHub App using a JWT, for more information see [Authenticating as a GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app). -1. Generate a server-to-server token using the corresponding REST API endpoint, [Create an installation access token for an app](/rest/apps#create-an-installation-access-token-for-an-app). This requires authenticating as a GitHub App using a JWT, for more information see [Authenticating as a GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app), and [Authenticating as an installation](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation). +1. Identify the `installation_id` that represents the connection between your GitHub App and the organization repositories it can access. Each GitHub App and organization pair have at most a single `installation_id`. You can identify this `installation_id` via [Get an organization installation for the authenticated app](/rest/apps#get-an-organization-installation-for-the-authenticated-app). This requires authenticating as a GitHub App using a JWT, for more information see [Authenticating as a GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app). +1. Generate a server-to-server token using the corresponding REST API endpoint, [Create an installation access token for an app](/rest/apps#create-an-installation-access-token-for-an-app). This requires authenticating as a GitHub App using a JWT, for more information see [Authenticating as a GitHub App](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app), and [Authenticating as an installation](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). 1. Use this server-to-server token to interact with your repositories, either via the REST or GraphQL APIs, or via a Git client. ## Machine users diff --git a/content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md b/content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md index 9b836d77ecfd..23d629ff6b8b 100644 --- a/content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md +++ b/content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md @@ -83,7 +83,7 @@ You can authenticate with the API in different ways. - **Web application flow** - For OAuth Apps in production, you should authenticate using the web application flow. For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#web-application-flow)." - **GitHub Apps** - - For GitHub Apps in production, you should authenticate on behalf of the app installation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps)." + - For GitHub Apps in production, you should authenticate on behalf of the app installation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)." ## Authenticating with the command line @@ -120,5 +120,5 @@ To use a {% data variables.product.pat_generic %} or SSH key to access resources | {% data variables.product.pat_v2_caps %} | `github_pat_` | "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)" |{% endif %} | OAuth access token | `gho_` | "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)" | | User-to-server token for a {% data variables.product.prodname_github_app %} | `ghu_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)" | -| Server-to-server token for a {% data variables.product.prodname_github_app %} | `ghs_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation)" | +| Server-to-server token for a {% data variables.product.prodname_github_app %} | `ghs_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)" | | Refresh token for a {% data variables.product.prodname_github_app %} | `ghr_` | "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-to-server-access-tokens)" | diff --git a/content/graphql/guides/forming-calls-with-graphql.md b/content/graphql/guides/forming-calls-with-graphql.md index 66ef1f1b0ec8..141c17d4bc3e 100644 --- a/content/graphql/guides/forming-calls-with-graphql.md +++ b/content/graphql/guides/forming-calls-with-graphql.md @@ -31,7 +31,7 @@ If your token does not have the required scopes to access a resource, the API wi ### Authenticating with a {% data variables.product.prodname_github_app %} -If you want to use the API on behalf of an organization or another user, GitHub recommends that you use a {% data variables.product.prodname_github_app %}. To authenticate as a {% data variables.product.prodname_github_app %} , you must first generate a private key in PEM format. Then, you must use this key to sign a JSON Web Token (JWT). You can use the JSON Web Token to request an installation token from {% data variables.product.company_short %} that you can use to authenticate to the GraphQL API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)", "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps), and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." +If you want to use the API on behalf of an organization or another user, GitHub recommends that you use a {% data variables.product.prodname_github_app %}. To authenticate as a {% data variables.product.prodname_github_app %} , you must first generate a private key in PEM format. Then, you must use this key to sign a JSON Web Token (JWT). You can use the JSON Web Token to request an installation token from {% data variables.product.company_short %} that you can use to authenticate to the GraphQL API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)", "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app), and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." ### Authenticating with a {% data variables.product.prodname_oauth_app %} diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md index 0e0c47eafa9e..7a50f349d721 100644 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md +++ b/content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md @@ -46,7 +46,7 @@ You may also want to use the **actions/add-to-project** workflow, which is maint 3. Install the {% data variables.product.prodname_github_app %} in your organization. Install it for all repositories that your project needs to access. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps#installing-your-private-github-app-on-your-repository)." 4. Store your {% data variables.product.prodname_github_app %}'s ID as a secret in your repository or organization. In the following workflow, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "[AUTOTITLE](/rest/apps#get-an-app)." -5. Generate a private key for your app. Store the contents of the resulting file as a secret in your repository or organization. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following workflow, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#generating-a-private-key)." +5. Generate a private key for your app. Store the contents of the resulting file as a secret in your repository or organization. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following workflow, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." 6. In the following workflow, replace `YOUR_ORGANIZATION` with the name of your organization. For example, `octo-org`. Replace `YOUR_PROJECT_NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://github.com/orgs/octo-org/projects/5` has a project number of 5. ```yaml{:copy} diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects.md index 6bf31902f508..cc43fa11ea02 100644 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects.md +++ b/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects.md @@ -18,7 +18,7 @@ This article demonstrates how to use the GraphQL API to manage a project. For mo {% curl %} -In all of the following `curl` command examples, replace `TOKEN` with a token that has the `read:project` scope (for queries) or `project` scope (for queries and mutations). The token can be a {% data variables.product.pat_v1 %} for a user or an installation access token for a {% data variables.product.prodname_github_app %}. For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." For more information about creating an installation access token for a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app)." +In all of the following `curl` command examples, replace `TOKEN` with a token that has the `read:project` scope (for queries) or `project` scope (for queries and mutations). The token can be a {% data variables.product.pat_v1 %} for a user or an installation access token for a {% data variables.product.prodname_github_app %}. For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." For more information about creating an installation access token for a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)." {% endcurl %} diff --git a/content/rest/apps/apps.md b/content/rest/apps/apps.md index 4ac3ec1a2105..8bbb6376337b 100644 --- a/content/rest/apps/apps.md +++ b/content/rest/apps/apps.md @@ -18,7 +18,7 @@ autogenerated: rest {% data reusables.apps.general-apps-restrictions %} -This page lists endpoints that you can access while authenticated as a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app)". +This page lists endpoints that you can access while authenticated as a {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app)". See "[AUTOTITLE](/rest/apps#installations)" for a list of endpoints that require authentication as a {% data variables.product.prodname_github_app %} installation. diff --git a/content/rest/apps/installations.md b/content/rest/apps/installations.md index a10adbc08e5f..730851b3b12d 100644 --- a/content/rest/apps/installations.md +++ b/content/rest/apps/installations.md @@ -18,7 +18,7 @@ autogenerated: rest ## About {% data variables.product.prodname_github_app %} installations -A {% data variables.product.prodname_github_app %} installation refers to any user or organization account that has installed the app. For information on how to authenticate as an installation and limit access to specific repositories, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-an-installation)." +A {% data variables.product.prodname_github_app %} installation refers to any user or organization account that has installed the app. For information on how to authenticate as an installation and limit access to specific repositories, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)." To list all GitHub App installations for an organization, see "[AUTOTITLE](/rest/orgs/orgs#list-app-installations-for-an-organization)." diff --git a/content/rest/guides/getting-started-with-the-rest-api.md b/content/rest/guides/getting-started-with-the-rest-api.md index 3e79fa789a43..24c1f50d65c5 100644 --- a/content/rest/guides/getting-started-with-the-rest-api.md +++ b/content/rest/guides/getting-started-with-the-rest-api.md @@ -100,7 +100,7 @@ You can authenticate your request by adding a token. If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. The REST API operations used in this article require `repo` scope for {% data variables.product.pat_v1_plural %}{% ifversion pat-v2 %} or, unless otherwise noted, read-only access to public repositories for {% data variables.product.pat_v2 %}s{% endif %}. Other operations may require different scopes{% ifversion pat-v2%} or permissions{% endif %}. For more information about creating a {% data variables.product.pat_generic %}, see "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)." -If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an operation is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that operation will say "Works with GitHub Apps." The REST API operations used in this article require `issues` read and write permissions for {% data variables.product.prodname_github_apps %}. Other operations may require different permissions. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)", "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps), and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." +If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an operation is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that operation will say "Works with GitHub Apps." The REST API operations used in this article require `issues` read and write permissions for {% data variables.product.prodname_github_apps %}. Other operations may require different permissions. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)", "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app), and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)." diff --git a/content/rest/guides/scripting-with-the-rest-api-and-javascript.md b/content/rest/guides/scripting-with-the-rest-api-and-javascript.md index 0d94e916a2f8..d36c65afdb15 100644 --- a/content/rest/guides/scripting-with-the-rest-api-and-javascript.md +++ b/content/rest/guides/scripting-with-the-rest-api-and-javascript.md @@ -54,9 +54,9 @@ const octokit = new Octokit({ {% ifversion ghes or ghae %} ### Authenticating with a {% data variables.product.prodname_github_app %} -If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)," "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps)," and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." +If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will say "Works with {% data variables.product.prodname_github_apps %}." For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)," "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)," and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps)." -Instead of importing `Octokit` from `octokit`, import `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)" in the REST reference documentation. +Instead of importing `Octokit` from `octokit`, import `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)" in the REST reference documentation. ```javascript{:copy} import { App } from "octokit"; diff --git a/content/rest/overview/endpoints-available-for-github-apps.md b/content/rest/overview/endpoints-available-for-github-apps.md index 13c687430c39..48c4324c2863 100644 --- a/content/rest/overview/endpoints-available-for-github-apps.md +++ b/content/rest/overview/endpoints-available-for-github-apps.md @@ -1,7 +1,7 @@ --- title: Endpoints available for GitHub Apps intro: Your app can make requests to the following REST endpoints. -permissions: 'You must use an installation access token to access endpoints using your {% data variables.product.prodname_github_app %}. For more information, see "[Authenticating with {% data variables.product.prodname_github_apps %}](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation)."' +permissions: 'You must use an installation access token to access endpoints using your {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)."' redirect_from: - /v3/apps/available-endpoints - /rest/reference/endpoints-available-for-github-apps diff --git a/content/rest/quickstart.md b/content/rest/quickstart.md index bd869a840038..3822f7187cfe 100644 --- a/content/rest/quickstart.md +++ b/content/rest/quickstart.md @@ -78,7 +78,7 @@ jobs: If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: 1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)" in the REST API documentation. For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." -1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#generating-a-private-key)." +1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." 1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example: ```yaml @@ -223,7 +223,7 @@ try { If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: 1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." -1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#generating-a-private-key)." +1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." 1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example: ```yaml @@ -348,7 +348,7 @@ jobs: If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: 1. Store your {% data variables.product.prodname_github_app %}'s ID as a secret. In the following example, replace `APP_ID` with the name of the secret. You can find your app ID on the settings page for your app or through the App API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)." -1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#generating-a-private-key)." +1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." 1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example: ```yaml diff --git a/content/rest/scim.md b/content/rest/scim.md index 71487f52f79a..2b1a3e2693ca 100644 --- a/content/rest/scim.md +++ b/content/rest/scim.md @@ -28,7 +28,7 @@ These endpoints are used by SCIM-enabled Identity Providers (IdPs) to automate p ### Authentication -You must authenticate as an owner of a {% data variables.product.product_name %} organization to use these endpoints. The REST API expects an [OAuth 2.0 Bearer](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps) token to be included in the `Authorization` header. If you use a {% data variables.product.pat_v1 %} for authentication, it must have the `admin:org` scope and you must also [authorize it for use with your SAML SSO organization](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). +You must authenticate as an owner of a {% data variables.product.product_name %} organization to use these endpoints. The REST API expects an OAuth 2.0 Bearer token (for example, a {% data variables.product.prodname_github_app %} user access token) to be included in the `Authorization` header. If you use a {% data variables.product.pat_v1 %} for authentication, it must have the `admin:org` scope and you must also [authorize it for use with your SAML SSO organization](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). ### Mapping of SAML and SCIM data diff --git a/data/reusables/shortdesc/authenticating_github_app.md b/data/reusables/shortdesc/authenticating_github_app.md index 9a306557024a..cf4967a3c760 100644 --- a/data/reusables/shortdesc/authenticating_github_app.md +++ b/data/reusables/shortdesc/authenticating_github_app.md @@ -1 +1 @@ -For information on how to authenticate as a GitHub App, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps#authenticating-as-a-github-app)." +For information on how to authenticate as a GitHub App, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)."