GitHub を使用してソーシャルログインを設定する (Set up social login with GitHub via GitHub App)

GitHub App を統合することで、「Sign-in with GitHub」、アカウント連携、細かな権限管理とリフレッシュ トークンによる安全な GitHub API へのアクセスが可能になります。

ヒント:

このガイドは、Logto コネクターについての基本的な理解があることを前提としています。未経験の方は、コネクター ガイドを参照して始めてください。

GitHub App と OAuth App の違い

GitHub では、認証 (Authentication) および API アクセスのために GitHub Apps と OAuth Apps の 2 種類のアプリが提供されています。選択の参考になる比較表は以下の通りです：

機能	GitHub App	OAuth App
権限	細かな権限管理 — 特定のリソースへのアクセスのみをリクエスト可能	広範なスコープ — 必要以上のアクセス権を付与しがち
権限管理	GitHub ダッシュボードでのみ設定可能。Logto の Scope フィールドは空で可	Logto コネクターでスコープを設定
リフレッシュ トークン	OAuth フロー中に常に発行される	サポートなし — トークンは取り消されない限り有効
トークン有効期限	アクセス トークンは 8 時間で失効。リフレッシュ トークンは 6 ヶ月有効	アクセス トークンは失効しない
ユーザーコントロール	アプリがアクセスできるリポジトリをユーザーが選択可能	ユーザーがアクセスできる全リポジトリにアクセス可能
レート制限	インストール数に応じて高いレート制限	低いレート制限（ユーザーごとに 5,000 リクエスト/時）
インストール	アカウント/組織にインストールし、リポジトリ単位でアクセス制御	ユーザーが広範なアクセス権で認可
Webhook	統合された Webhook サポート	各リポジトリごとに個別設定が必要
独立動作	自身の権限で動作可能（サーバー間通信）	常にユーザーの代理で動作

GitHub App を使うべき場合：

• 権限やリポジトリアクセスを細かく制御したい場合
• 長期的な API アクセスのためにリフレッシュ トークンが必要な場合
• より高い API レート制限が必要な場合
• ユーザーセッションに依存しない自動化タスクを実行したい場合

OAuth App を使うべき場合：

• シンプルなサインイン連携と最小限の API アクセスが必要な場合
• 失効しないトークンが必要な場合（レガシー統合向け）
• エンタープライズレベルのリソースにアクセスしたい場合（GitHub App は現時点で未対応）

ヒント:

GitHub は、強化されたセキュリティ機能と細かな権限管理の観点から、ほとんどのユースケースで OAuth App より GitHub App の利用を推奨しています。詳しくは GitHub Apps と OAuth Apps の違い をご覧ください。

はじめに

GitHub App コネクターは OAuth 2.0 連携を可能にし、アプリケーションで以下が実現できます：

• 「Sign-in with GitHub」認証 (Authentication) の追加
• ユーザーアカウントと GitHub アイデンティティの連携
• GitHub からユーザープロフィール情報の同期
• Logto Secret Vault で安全にトークンを保管し、GitHub API への自動化タスク（例：GitHub issue 作成、アプリからのリポジトリ管理）を実行
• リフレッシュ トークン（GitHub App では常に発行）を利用し、ユーザーの再認証なしで長期的な API アクセスを維持

これらの認証 (Authentication) 機能を設定するには、まず Logto で GitHub コネクターを作成してください：

1. Logto コンソール > コネクター > ソーシャルコネクター

   にアクセスします。
2. ソーシャルコネクターを追加 をクリックし、GitHub App を選択、次へ をクリックして、チュートリアルに従い統合を完了してください。

ステップ 1: GitHub App を作成する

GitHub を認証 (Authentication) プロバイダーとして利用する前に、GitHub 上で GitHub App を作成し、OAuth 2.0 資格情報を取得する必要があります。

1. GitHub にアクセスし、アカウントでサインインします。必要に応じて新しいアカウントを作成してください。
2. Settings > Developer settings > GitHub Apps に移動します。
3. New GitHub App をクリックして新しいアプリケーションを登録します：
   • GitHub App name：アプリの一意な名前を入力します。名前は 34 文字以内で、GitHub 全体で一意である必要があります。
   • Homepage URL：アプリケーションのホームページ URL を入力します。
   • Callback URL：Logto の GitHub コネクターから Callback URI をコピーし、ここに貼り付けます。必要に応じて複数のコールバック URL を追加できます。ユーザーが GitHub でサインインした後、ここに認可コード付きでリダイレクトされ、Logto が認証 (Authentication) を完了します。
   • Expire user authorization tokens：この項目は チェックしたまま（推奨）にします。これにより、トークンの有効期限とリフレッシュ トークンが有効になり、セキュリティが強化されます。
   • Request user authorization (OAuth) during installation：インストール時にユーザーにアプリの認可を求めたい場合は、オプションでチェックします。
   • Webhook：Webhook イベントが不要な場合は Active のチェックを外します。認証 (Authentication) のみの用途では通常 Webhook は不要です。
4. Permissions でアプリに必要な権限を設定します（詳細は下記ステップ 2 を参照）。
5. Where can this GitHub App be installed? では、どの GitHub アカウントのユーザーでも認証 (Authentication) に利用できるようにしたい場合は Any account を選択します。
6. Create GitHub App をクリックして GitHub App を作成します。

注記:

OAuth Apps とは異なり、GitHub Apps は広範なスコープではなく細かな権限で管理されます。アプリ作成時に GitHub ダッシュボードで権限を設定し、ユーザーは認可 (Authorization) 時に特定のリポジトリへのアクセスを許可します。

GitHub Apps のセットアップ詳細については Registering a GitHub App を参照してください。

ステップ 2: GitHub で権限を設定する

GitHub Apps は OAuth スコープの代わりに細かな権限で管理されます。GitHub App の作成または編集時に GitHub ダッシュボードで権限を設定 する必要があります。これらの権限によってアプリがアクセスできるデータが決まります。

GitHub App の権限の理解

権限は 3 種類に分類されます：

• リポジトリ権限：リポジトリレベルのリソース（コード、課題、プルリクエストなど）へのアクセス
• 組織権限：組織レベルのリソース（メンバー、チーム、プロジェクトなど）へのアクセス
• アカウント権限：ユーザーアカウントデータ（メール、プロフィール、フォロワーなど）へのアクセス

各権限ごとに次のいずれかを選択できます：

• No access：このリソースにアクセスできません
• Read-only：このリソースを読み取りのみ可能
• Read & write：このリソースの読み取りと変更が可能

認証 (Authentication) 用の推奨権限

基本的な「GitHub でサインイン」機能には、最低限次の アカウント権限 を設定してください：

権限	アクセスレベル	目的
Email addresses	Read-only	アカウント作成のためにユーザーのメールアドレスを取得

ヒント:

GitHub Apps は、ユーザーの代理で動作する場合、公開プロフィール情報の読み取り権限を暗黙的に持っています。ユーザー名、アバター、公開プロフィール URL などの基本的なプロフィールデータについては明示的な権限リクエストは不要です。

API アクセス用の追加権限

認証 (Authentication) 以外で GitHub API へのアクセスが必要な場合は、GitHub ダッシュボードで該当する権限を追加してください。よくある例は以下の通りです：

権限タイプ	権限	アクセスレベル	ユースケース
リポジトリ	Contents	Read-only / Read & write	リポジトリのファイルやコードへのアクセス
リポジトリ	Issues	Read & write	課題の作成と管理
リポジトリ	Pull requests	Read & write	プルリクエストの作成と管理
リポジトリ	Metadata	Read-only	リポジトリのメタデータへのアクセス（多くの操作で必須）
組織	Members	Read-only	組織メンバーの一覧取得
アカウント	Followers	Read-only	ユーザーのフォロワーやフォロー中ユーザーへのアクセス

これは一部の例であり、GitHub Apps ではさらに多くの細かな権限がサポートされています。完全な一覧は Permissions required for GitHub Apps を参照してください。

OAuth Apps との主な違い:

OAuth Apps では Logto コネクターでスコープを設定しますが、GitHub App の権限はすべて GitHub ダッシュボードで管理します。Logto の GitHub コネクターの Scope フィールドは空のままで構いません — GitHub Apps では従来の OAuth スコープは使用しません。

必要な権限を GitHub 側で設定し、ユーザーは認可 (Authorization) 時にアクセス許可を求められます。

ステップ 3: Logto コネクターを設定する

GitHub App を作成したら、その設定ページにリダイレクトされ、資格情報を取得できます。

1. GitHub App の設定ページで Client ID をコピーし、Logto の clientId フィールドに貼り付けます。
2. Client secrets で Generate a new client secret をクリックします。生成されたシークレットをコピーし、Logto の clientSecret フィールドに貼り付けます。
3. Logto で Save and Done をクリックし、アイデンティティシステムと GitHub を接続します。

警告:

Client secret は安全に保管し、クライアントサイドのコードで絶対に公開しないでください。GitHub の client secret は紛失した場合に復元できません — 新たに生成する必要があります。

注記:

GitHub App の Client ID は App ID とは異なります。必ず設定ページに「Client ID」と表示されているものを使用してください（App ID ではありません）。

ステップ 4: 一般設定

GitHub への接続を妨げることはありませんが、エンドユーザーの認証 (Authentication) 体験に影響する一般的な設定をいくつか紹介します。

プロフィール情報の同期

GitHub コネクターでは、GitHub のユーザー情報から Logto ユーザープロフィールへの同期方法（name、avatar、email など）を設定できます。次のオプションから選択してください：

• サインアップ時のみ同期：ユーザーが初めてサインインしたときにプロフィール情報を一度だけ取得します。
• サインイン時に常に同期：ユーザーがサインインするたびにプロフィール情報を更新します。

GitHub API へのアクセス用トークンの保存（オプション）

GitHub API へのアクセスやユーザー認可での操作（ソーシャルサインインやアカウント連携経由）を行いたい場合は、Logto でトークン保存を有効にしてください：

1. GitHub App の設定（ステップ 2）で必要な権限を設定します。
2. Logto の GitHub コネクターで Store tokens for persistent API access を有効にします。Logto はアクセストークンとリフレッシュ トークンの両方を Secret Vault に安全に保存します。

注記:

GitHub Apps は常にリフレッシュ トークンを発行するため、Logto は両方のトークンを自動的に保存します。アクセストークンは 8 時間で期限切れになりますが、Logto はリフレッシュ トークンを使って新しいアクセストークンを取得でき、最大 6 か月間 API アクセスが途切れません。

ステップ 5: 統合のテスト（オプション）

本番運用前に、GitHub App 統合をテストしてください：

1. Logto の開発テナントでコネクターを利用します。
2. ユーザーが GitHub でサインインできることを確認します。
3. 認可 (Authorization) 時に正しい権限がユーザーに求められることを確認します。
4. トークン保存を有効にした場合、アクセストークン（およびリフレッシュ トークン）が正しく保存されていることを確認します。
5. 保存されたトークンを使って API コールをテストし、権限が期待通りに機能しているか確認します。

GitHub Apps は、どの GitHub ユーザーアカウントでもすぐに利用できます。他のプラットフォームのようにテストユーザーやアプリ承認は不要です。ただし、アプリが組織にインストールされている場合は、組織オーナーによるインストール承認が必要な場合があります。

GitHub コネクターの活用

GitHub コネクターを作成し GitHub と連携したら、エンドユーザー向けフローに組み込むことができます。ニーズに合わせて以下のオプションを選択してください：

「Sign-in with GitHub」を有効化

1. Logto コンソールで サインイン体験 > サインアップとサインイン に移動します。
2. ソーシャルサインイン セクションで GitHub コネクターを追加し、ユーザーが GitHub で認証 (Authentication) できるようにします。

ソーシャルサインイン体験 について詳しく学ぶ。

GitHub アカウントの連携 / 解除

Account API を利用して、サインイン済みユーザーが GitHub アカウントを連携 / 解除できるカスタムアカウントセンターをアプリ内に構築できます。Account API チュートリアル をご参照ください。

ヒント:

GitHub コネクターは、ソーシャルサインインを有効化せず、アカウント連携や API アクセス専用として有効化することも可能です。

GitHub API へのアクセスとアクション実行

アプリケーションは Secret Vault から保存された GitHub トークンを取得し、GitHub API を呼び出してバックエンドタスク（例：issue 作成、リポジトリ管理、ワークフロー自動化など）を自動化できます。API アクセス用の保存トークン取得ガイドを参照してください。

GitHub App は OAuth フロー中に必ずリフレッシュ トークンを発行するため、Logto はアクセス トークンとリフレッシュ トークンの両方を保存します。アクセス トークンは 8 時間で失効しますが、Logto は自動的にリフレッシュ トークン（6 ヶ月有効）を使って新しいアクセス トークンを取得し、途切れない API アクセスを実現します。

ユーザーの GitHub アイデンティティ管理

ユーザーが GitHub アカウントを連携した後、管理者は Logto コンソールでその接続を管理できます：

1. Logto コンソール > ユーザー管理 に移動し、対象ユーザーのプロフィールを開きます。
2. ソーシャル接続 セクションで GitHub 項目を見つけ、管理 をクリックします。
3. このページで管理者は、ユーザーの GitHub 接続を管理し、GitHub アカウントから付与・同期されたすべてのプロフィール情報や、アクセス トークン・リフレッシュ トークンの状態を確認できます。

注記:

OAuth App がスコープを使うのに対し、GitHub App は GitHub ダッシュボードで設定する細かな権限を利用します。ユーザーのアクセストークンは、アプリとユーザーの両方が持つ権限に限定されます。Logto で権限リストを直接表示することはできませんが、アプリケーションは GitHub App 設定で構成した権限に基づきアクセスできます。

参考情報

GitHub 開発者ドキュメント - GitHub App について

GitHub 開発者ドキュメント - GitHub App の登録

GitHub 開発者ドキュメント - ユーザーアクセストークンの生成

GitHub 開発者ドキュメント - ユーザーアクセストークンのリフレッシュ

GitHub App と OAuth App の違い