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

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

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

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

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

一部の REST API エンドポイントはインストールアクセストークンを受け入れず、ほとんどの REST API エンドポイントでは、エンドポイントを使用するために、アプリには特定のアクセス許可が必要です。 REST API エンドポイントがインストールアクセストークンを受け入れるかどうかを確認し、必要なアクセス許可を確認するには、エンドポイントのドキュメントを参照してください。

アプリインストールでは、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 Apps用 REST API エンドポイント」をご覧ください。

アプリ ID は、アプリの設定ページでも確認できます。アプリ ID は、クライアント ID とは異なります。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。
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" \
--header "X-GitHub-Api-Version: 2022-11-28"
```
必要に応じて、repositories または repository_ids 本文パラメーターを使って、インストールアクセストークンがアクセスできる個々のリポジトリを指定できます。 repositories または repository_ids を使って特定のリポジトリへのアクセス権を付与しない場合、インストールアクセストークンでは、インストールがアクセス権を付与されたすべてのリポジトリにアクセスできます。インストールアクセストークンには、インストールがアクセス権を付与されていないリポジトリへのアクセス権を付与できません。最大 500 個のリポジトリを一覧表示できます。

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

permissions パラメーターを使用してトークンのアクセスを減らす場合、要求内のアクセス許可の数と、トークンがアクセスできるリポジトリの数が原因で、トークンの複雑さが増加します。複雑さが大きすぎる場合は、サポートできるリポジトリの最大数を示すエラーメッセージが表示されます。この場合は、permissions パラメーターを使用して要求するアクセス許可を減らすか、repositories または repository_ids パラメーターを使用して要求するリポジトリの数を減らすか、Organization 内の all リポジトリにアプリをインストールする必要があります。

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

このエンドポイントについて詳しくは、「GitHub Apps用 REST API エンドポイント」をご覧ください。

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

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

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

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

次の例では、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" \
--header "X-GitHub-Api-Version: 2022-11-28"

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 で認証する

GitHub App の ID を取得します。アプリの ID は、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。
秘密キーを作成します。詳細については、「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 Apps用 REST API エンドポイント」を参照してください。
octokit から App をインポートします。 App の新しいインスタンスを作成します。次の例では、APP_ID をアプリの ID への参照に置き換えます。 PRIVATE_KEY をアプリの秘密キーへの参照に置き換えます。
JavaScript
```
import { App } from "octokit";

const app = new App({
  appId: APP_ID,
  privateKey: PRIVATE_KEY,
});
```
```
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);
```
```
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
```
octokit メソッドを使って、API に対して要求を行います。

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

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

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

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

GitHub App の ID を取得します。アプリの ID は、GitHub App の設定ページで確認できます。 GitHub App の設定ページに移動する方法の詳細については、「AUTOTITLE」を参照してください。
秘密キーを作成します。詳細については、「GitHub Apps の秘密キーの管理」を参照してください。
アプリの設定で指定した Webhook シークレットを取得します。 Webhook シークレットについて詳しくは、「GitHub Apps での Webhook の使用」をご覧ください。
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 },
});
```
```
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.`,
      headers: {
        "x-github-api-version": "2022-11-28",
      },
    }
  )
});

この記事の内容