GitHub App インストールとしての認証

GitHub App インストールとしての認証について

GitHub App がアカウントにインストールされたら、API 要求に対してアプリインストールとして認証を行うことができます。これにより、アプリはそのインストールによって所有されているリソースにアクセスできます (アプリに必要なリポジトリアクセス権とアクセス許可が付与されている限り)。アプリインストールによって行われた API 要求は、アプリに帰属します。 GitHub App のインストールについて詳しくは、「GitHub App のインストール」を参照してください。

たとえば、"octo-org" という組織が所有するプロジェクトに対するイシューの Status フィールドをアプリで変更する場合は、アプリの octo-org インストールとして認証します。イシューのタイムラインには、アプリによって状態が更新されたことが示されます。

インストールとして API 要求を行うには、まずインストールアクセストークンを生成する必要があります。次に、後続の API 要求の Authorization ヘッダーで、インストールアクセストークンを送信します。 GitHub の Octokit SDK を使うこともできます。これを使ってインストールアクセストークンを生成できます。

REST API エンドポイントが GitHub App インストールアクセストークンで動作する場合、そのエンドポイントの REST リファレンスドキュメントには、"GitHub Apps で動作する" と記載されます。さらに、アプリにはエンドポイントを使用するために必要なアクセス許可が必要です。詳しくは、「Choosing permissions for a GitHub App」を参照してください。

アプリインストールでは、GraphQL API を使用することもできます。 REST API と同様に、アプリには GraphQL API のオブジェクトにアクセスするための特定のアクセス許可が必要です。 GraphQL 要求の場合は、アプリをテストして、実行したい GraphQL クエリと変更に必要なアクセス許可がアプリにあることを確認する必要があります。

インストールアクセストークンを使って、HTTP ベースの Git アクセスの認証を行うこともできます。アプリには、"コンテンツ" リポジトリのアクセス許可が必要です。その後は、インストールアクセストークンを HTTP パスワードとして使用できます。 TOKEN をインストールアクセストークンに置き換えます: git clone https://x-access-token:TOKEN@github.com/owner/repo.git"。

インストールアクセストークンを使用して行われた要求は、"サーバー間" 要求と呼ばれることもあります。

アプリインストールとしてではなく、ユーザーに代わるアプリとして認証する方法について詳しくは、「ユーザーに代わって GitHub アプリで認証する」を参照してください。

インストールアクセストークンを使ってアプリインストールとして認証する

インストールアクセストークンを使ってインストールとして認証するには、まず REST API を使ってインストールアクセストークンを生成します。次に、REST API または GraphQL API 要求の Authorization ヘッダーでそのインストールアクセストークンを使用します。インストールアクセストークンは 1 時間後に期限切れになります。

インストールアクセストークンの生成

アプリの JSON Web Token (JWT) を生成します。詳細については、「GitHub アプリの JSON Web トークン (JWT) の生成」を参照してください。
認証に使いたいインストールの ID を取得します。

Webhook イベントに応答する場合、Webhook ペイロードにはインストール ID が含まれます。

REST API を使って、アプリのインストールの ID を見つけることもできます。たとえば、GET /users/{username}/installation、GET /repos/{owner}/{repo}/installation、GET /orgs/{org}/installation、または GET /app/installations エンドポイントでインストール ID を取得できます。詳細については、「GitHub アプリ」を参照してください。
REST API POST 要求を /app/installations/INSTALLATION_ID/access_tokens に送信します。要求の Authorization ヘッダーに JSON Web トークンを含めます。 INSTALLATION_ID を、認証に使いたいインストールの ID に置き換えます。

たとえば、次の curl 要求を送信します。 INSTALLATION_ID をインストールの ID に、JWT を JSON Web トークンに置き換えてください。
```
curl --request POST \
--url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/access_tokens" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer JWT"
```
必要に応じて、repositories または repository_ids 本文パラメーターを使って、インストールアクセストークンがアクセスできる個々のリポジトリを指定できます。 repositories または repository_ids を使って特定のリポジトリへのアクセス権を付与しない場合、インストールアクセストークンでは、インストールがアクセス権を付与されたすべてのリポジトリにアクセスできます。インストールアクセストークンに、インストールがアクセス権を付与されていないリポジトリへのアクセス権を付与することはできません。

必要に応じて、permissions 本文パラメーターを使って、インストールアクセストークンに必要なアクセス許可を指定します。 permissions が指定されていない場合、インストールアクセストークンには、アプリに付与されたすべてのアクセス許可が付与されます。インストールアクセストークンに、アプリが付与されていないアクセス許可を付与することはできません。

応答には、インストールアクセストークン、トークンの有効期限が切れる時刻、トークンが持つアクセス許可、トークンがアクセスできるリポジトリが含まれます。インストールアクセストークンは 1 時間後に期限切れになります。

このエンドポイントについて詳しくは、「GitHub アプリ」をご覧ください。

注: ほとんどの場合は、Authorization: Bearer または Authorization: token を使用してトークンを渡すことができます。ただし、JSON Web トークン (JWT) を渡す場合は、Authorization: Bearer を使用する必要があります。

インストールアクセストークンを使った認証

インストールアクセストークンを使って認証を行うには、それを API 要求の Authorization ヘッダーに含めます。アクセストークンは、GraphQL API と REST API の両方で動作します。

アプリにはエンドポイントを使用するために必要なアクセス許可が必要です。詳しくは、「Choosing permissions for a GitHub App」を参照してください。

次の例では、INSTALLATION_ACCESS_TOKEN をインストールアクセストークンに置き換えてください。

curl --request GET \
--url "http(s)://HOSTNAME/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN"

Octokit.js SDK を使ってアプリインストールとして認証する

GitHub の Octokit.js SDK を使って、アプリインストールとして認証できます。 SDK を使って認証を行う利点の 1 つは、JSON Web Token (JWT) を自分で生成する必要がないことです。さらに、SDK によってインストールアクセストークンの再生成が管理されるため、1 時間の有効期限について心配する必要がありません。

Octokit.js ライブラリを使うには、octokit をインストールしてインポートする必要があります。次の例では、ES6 に従って import ステートメントを使っています。さまざまなインストールとインポートの方法について詳しくは、Octokit.js の README の「使用法」セクションを参照してください。

Octokit.js を使ってインストール ID で認証する

アプリの ID を取得します。アプリの ID は、アプリの設定ページで確認できます。ユーザー所有アプリの場合、設定ページは https://github.com/settings/apps/APP-SLUG です。組織所有アプリの場合、設定ページは https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG です。 APP-SLUG はスラッグにしたアプリの名前に置き換えてください。 ORGANIZATION はスラッグにした組織の名前に置き換えてください。たとえば、「 https://github.com/organizations/octo-org/settings/apps/octo-app 」のように入力します。
秘密キーを作成します。詳細については、「GitHub Apps の秘密キーの管理」を参照してください。
認証に使いたいインストールの ID を取得します。

Webhook イベントに応答する場合、Webhook ペイロードにはインストール ID が含まれます。

REST API を使って、アプリのインストールの ID を見つけることもできます。たとえば、GET /users/{username}/installation、GET /repos/{owner}/{repo}/installation、GET /orgs/{org}/installation、または GET /app/installations エンドポイントでインストール ID を取得できます。詳細については、「GitHub アプリ」を参照してください。
octokit から App をインポートします。 App の新しいインスタンスを作成します。次の例では、APP_ID をアプリの ID への参照に置き換えます。 PRIVATE_KEY をアプリの秘密キーへの参照に置き換えます。
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
getInstallationOctokit メソッドを使って、認証された octokit インスタンスを作成します。次の例では、INSTALLATION_ID を、代わりに認証するアプリのインストールの ID に置き換えます。
JavaScript
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
octokit メソッドを使って、API に対して要求を行います。

アプリにはエンドポイントを使用するために必要なアクセス許可が必要です。詳しくは、「Choosing permissions for a GitHub App」を参照してください。

たとえば、GraphQL API に対して要求を行う場合:
JavaScript
```
await octokit.graphql(`
  query {
    viewer {
      login
    }
  }
  `)
```
たとえば、REST API に対して要求を行う場合:
JavaScript
```
await octokit.request("GET /meta")
```

Webhook イベントに応答して Octokit.js を使って認証する

Octokit.js SDK では、事前に認証された octokit インスタンスも Webhook イベントハンドラーに渡されます。

アプリの ID を取得します。アプリの ID は、アプリの設定ページで確認できます。ユーザー所有アプリの場合、設定ページは https://github.com/settings/apps/APP-SLUG です。組織所有アプリの場合、設定ページは https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG です。 APP-SLUG はスラッグにしたアプリの名前に置き換えてください。 ORGANIZATION はスラッグにした組織の名前に置き換えてください。たとえば、「 https://github.com/organizations/octo-org/settings/apps/octo-app 」のように入力します。
秘密キーを作成します。詳細については、「GitHub Apps の秘密キーの管理」を参照してください。
アプリの設定で指定した Webhook シークレットを取得します。 Webhook シークレットについて詳しくは、「Using webhooks with GitHub Apps」をご覧ください。
octokit から App をインポートします。 App の新しいインスタンスを作成します。次の例では、APP_ID をアプリの ID への参照に置き換えます。 PRIVATE_KEY をアプリの秘密キーへの参照に置き換えます。 WEBHOOK_SECRET をアプリの Webhook シークレットに置き換えます。
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
  webhooks: { WEBHOOK_SECRET },
});
```

app.webhooks.* メソッドを使って Webhook イベントを処理します。詳しくは、Octokit.js の README の Webhooks セクションを参照してください。たとえば、イシューが開かれたときにイシューに対してコメントを作成するには、次のようにします。

app.webhooks.on("issues.opened", ({ octokit, payload }) => {
  await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", {
      owner: payload.repository.owner.login,
      repo: payload.repository.name,
      issue_number: payload.issue.number,
      body: `This is a bot post in response to this issue being opened.`,
      
    }
  )
});

GitHub App インストールとしての認証

この記事の内容