зеркало из https://github.com/github/docs.git
Add App authentication overview article (#35271)
Co-authored-by: Jess Hosman <1183847+jhosman@users.noreply.github.com>
This commit is contained in:
Sarah Edwards
GitHub
Родитель
83c28d2e6a
Коммит
222be16582
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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)."
|
||||
|
|
@ -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.
|
||||
|
||||
<a name="jwt-payload"></a>
|
||||
```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).
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -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
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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**.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)" |
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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)."
|
||||
|
||||
|
|
|
|||
|
|
@ -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)."
|
||||
|
||||
|
|
|
|||
|
|
@ -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";
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)."
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче