OAuth アプリから Appへの移行

OAuth app を App に移行する利点と、OAuth app の移行方法について説明します。

この記事の内容

OAuth apps から Apps に移行する利点

Apps は、 との統合方法として推奨されています。 Apps には、OAuth apps に比べて多くの利点があります。

  • きめ細かいアクセス許可、リポジトリ アクセスの選択肢、有効期間の短いトークンなどの強化されたセキュリティ機能
  • ユーザーから独立して、またはユーザーに代わって動作できること
  • スケーラブルなレート制限
  • 組み込みの Webhook

詳しくは、「 App の作成について」をご覧ください。

OAuth app から App への切り替え

次の手順では、OAuth app から App に移行する方法の概要を示します。 具体的な手順は、アプリによって異なります。

1. OAuth app を確認する

OAuth app のコードを確認し直してください。 OAuth app が行う API 要求は、 App に対して選ぶアクセス許可を決定するのに役立ちます。

さらに、OAuth apps では使用できない REST API エンドポイントがいくつかあります。 「 App インストール アクセス トークンで使用できるエンドポイント」を参照して、使用する REST エンドポイントが Apps で使用可能であることを確認します。

2. App を登録する

新しい App を登録します。 詳しくは、「 App の登録」をご覧ください。

OAuth app と比較すると、 App の設定はより細かく制御できます。 いくつかの重要な追加は次のとおりです。

  • 常にユーザーの代理として動作する OAuth app とは異なり、 App は、それ自体として、またはユーザーの代理としてアクションを実行するように設定できます。 新しい App でユーザーの代理としてのアクションを実行しない場合は、"ユーザーの識別と承認" に関する設定をスキップできます。 詳しくは、「 アプリでの認証について」をご覧ください。

  • Webhook を使用すると、特定のイベントが発生したときに App に通知できます。 リポジトリまたは組織ごとに API を使って構成する必要がある OAuth apps の Webhook とは異なり、 Apps には Webhook が組み込まれています。 App を登録するときに、受信する Webhook イベントを選ぶことができます。 さらに、OAuth app が現在ポーリングを使用してイベントが発生したかどうかを判断している場合は、代わりに Webhook へのサブスクライブによって App をレート制限内に維持することを検討してください。 詳しくは、「 Apps での Webhook の使用」をご覧ください。

  • OAuth app の場合、ユーザーがアプリを承認したときにスコープを要求します。 App では、アプリ設定でアクセス許可を指定します。 これらのアクセス許可はスコープよりも細かく、アプリに必要なアクセス許可のみを選ぶことができます。 さらに、これらのアクセス許可は REST API エンドポイントと Webhook イベントにマップされているため、特定の REST API エンドポイントにアクセスしたり、特定の Webhook にサブスクライブしたりするために App に必要なアクセス許可を簡単に判断できます。 現在、GraphQL 要求に関するアクセス許可は文書化されていません。 詳しくは、「 アプリのアクセス許可を選択する」をご覧ください。

3. アプリのコードを変更する

App を登録したら、以前の OAuth app のコードを、新しい App で動作するように調整します。

認証を更新する

App の API 認証を処理するようにアプリのコードを更新する必要があります。 App は、3 つの方法で認証できます。

  • アプリ自体として ( App 登録に関する詳細を取得または変更したり、インストール アクセス トークンを作成したりするため)。 詳しくは、「 Appとしての認証」をご覧ください。
  • アプリ自体の代理としてアクションを実行するために、アプリのインストールとして。 詳しくは、「 App インストールとしての認証」をご覧ください。
  • アクションが帰属するユーザーを示すために、ユーザーの代理として。 詳しくは、「ユーザーに代わって アプリで認証する」をご覧ください。

の公式な Octokit.js ライブラリを使用している場合は、組み込みの App オブジェクトを使用して認証できます。 例については、「REST API と JavaScript を使用したスクリプト」と「Webhook イベントに応答する App の構築」を参照してください。

レート制限を確認する

Apps と OAuth apps のレート制限の違いを確認します。 Apps ではレート制限に対してスライディング ルールを使います。これは組織のリポジトリ数とユーザー数に基づいて増やすことができます。 詳しくは、「Rate limits for Apps ( アプリのレート制限)」をご覧ください。

可能であれば、条件付きの要求を使用し、ポーリングではなく Webhook へのサブスクライブによってレート制限内に留まるようにすることを検討してください。 条件付きの要求の詳細については、「REST API を使用するためのベスト プラクティス」を参照してください。 App での Webhook の使用の詳細については、「 Apps での Webhook の使用」と「Webhook イベントに応答する App の構築」を参照してください。

コードをテストする

新しい App をテストして、コードが想定どおりに動作することを確認します。

4. 新しい App を公開する

他のアカウントで新しい App を使用できるようにする場合は、アプリがパブリックであることを確認します。 App を見つけやすくするには、アプリを Marketplace に掲載します。 詳細については、「アプリの Marketplace について」と「 Appをパブリックまたはプライベートにする」を参照してください。

5. ユーザーに移行を指示する

新しい App の準備ができたら、以前の OAuth app のユーザーに新しい App への移行を指示します。 ユーザーを自動的に移行する方法はありません。 各ユーザーは、自分で App のインストール、承認、またはその両方を行う必要があります。

アプリ所有者は、新しい App のインストールや承認を行うことと、以前の OAuth app に対する承認を取り消すことをユーザーに促す行動喚起を組み込む必要があります。 ドキュメントまたはユーザー インターフェイス要素も更新する必要があります。

App のインストールをユーザーに求める

App がそれ自体の代理として API 要求や Organization またはリポジトリ リソースへのアクセスを行うようにする場合、ユーザーは App をインストールする必要があります。 ユーザーは自分のアカウントまたは Organization に App をインストールするときに、アプリがアクセスできるリポジトリを選び、アプリが要求した Organization とリポジトリのアクセス許可を付与します。

ユーザーが App をインストールできるように、アプリの Web ページへのリンクを追加できます。ユーザーはそれをクリックして、 App をインストールできます。 インストール URL の形式は https://.com/apps/YOUR_APP_NAME/installations/new です。 YOUR_APP_NAME を、 App のスラッグ名に置き換えます。この名前は、 App の設定ページの [パブリック リンク] フィールドにあります。

OAuth app でアクセスしていたリポジトリを事前に選ぶには、インストール URL に /permissions とクエリ パラメーターを追加できます。 これによりユーザーは、OAuth app で既にアクセスできているリポジトリへのアクセス権を App に付与できます。 クエリ パラメーターは次のとおりです。

  • suggested_target_id: App をインストールするユーザーまたは Organization の ID。 このパラメーターは必須です。
  • repository_ids[]: インストール用に選ぶリポジトリ ID。 省略すると、すべてのリポジトリが選ばれます。 事前選択できるリポジトリ数は、最大で100です。 OAuth app でアクセスできるリポジトリのリストを取得するには、認証されたユーザーのためのリポジトリのリストと Organization のリポジトリのリストのエンドポイントを使用します。

(例: https://.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID)。

Apps のインストールの詳細については、「個人向けアカウント用に Marketplace から アプリをインストールする」、「Organization の Marketplace から アプリをインストールする」、「サード パーティからの App のインストール」、「独自の App のインストール」を参照してください。

アプリの承認をユーザーに求める

App でユーザーの代理として API 要求を行う場合、ユーザーがアプリを承認する必要があります。 ユーザーは、アプリを承認するときに、ユーザーの代わりに動作するためのアクセス許可をアプリに付与し、アプリから要求されたアカウント アクセス許可を付与します。 アプリが Organization アカウントにインストールされている場合、その Organization 内の各ユーザーは、アプリが自分の代わりに動作できるようにアプリを承認する必要があります。

ユーザーにアプリの承認を求めるために、Web アプリケーション フローまたはデバイス フローを介してユーザーを誘導します。 詳しくは、「 アプリのユーザー アクセス トークンの生成」をご覧ください。

Apps の認可の詳細については、「 App の承認」を参照してください。

OAuth app アクセスを取り消すようユーザーに促す

また、以前の OAuth app のアクセス権を取り消すようユーザーに促す必要もあります。 これは、OAuth app から完全に移行するのに役立ち、ユーザーのデータのセキュリティを維持するのにも役立ちます。 詳しくは、「承認された OAuth アプリをレビューする」をご覧ください。

インターフェイスまたはドキュメントを更新する

OAuth app から App への変更を反映するように、アプリに関連したユーザー インターフェイスまたはドキュメントを更新する必要があります。

6. 以前の OAuth app の Webhook を削除する

ユーザーが App をインストールし、リポジトリへのアクセスを許可したときに、以前の OAuth app の Webhook を削除する必要があります。 新しい App と以前の OAuth app が同じイベントの Webhook に応答した場合、重複する動作がユーザーによって観察される可能性があります。

リポジトリの Webhook を削除するには、added アクションを使用して installation_repositories Webhook をリッスンできます。 App がそのイベントを受け取ったら、REST API を使用して、OAuth app のそれらのリポジトリの Webhook を削除できます。 詳細については、「Webhook のイベントとペイロード」および「リポジトリ ウェブフック の REST API エンドポイント」を参照してください。

同様に、Organization の Webhook を削除するには、created アクションを使用して installation Webhook をリッスンできます。 App が Organization のイベントを受け取ったときに、REST API を使用して、その Organization の Webhook と、OAuth app の対応するリポジトリを削除できます。 詳細については、「Webhook のイベントとペイロード」、「組織の Webhook の REST API エンドポイント」、「リポジトリ ウェブフック の REST API エンドポイント」を参照してください。

7. 以前の OAuth app を削除する

ユーザーが新しい App に移行し終えたら、以前の OAuth app を削除する必要があります。 これにより、OAuth app の資格情報の不正使用を回避できます。 このアクションにより、OAuth app の残りの承認もすべて取り消されます。 詳しくは、「OAuth アプリの削除」をご覧ください。 OAuth app が Marketplace に掲載されている場合は、最初に Support に問い合わせて、マーケットプレースからアプリを削除することが必要な場合があります。