ガイド：GitHubのOAuth 2.0認証プロセスを実装

OAuth 2.0の認証は、GitHub を含む多くのサービスで使われている一般的な認証方式で、サードパーティアプリケーションがパスワードを共有することなくユーザーデータにアクセスできるようにしています。

本文では、Apidogという便利なAPI 管理ツールを使って、GitHubのOAuth 2.0認証プロセスを実装する方法を皆さんに紹介します。

button

OAuth 2.0 とは?

OAuth 2.0 は、ユーザー認証情報を要求することなく、サードパーティのアプリケーションが保護されたリソースにアクセスできるようにする広く使われている認可プロトコルです。以下の 4 つの主要な役割が関係します。

リソース所有者: 通常は保護されたリソースを所有するユーザー。
クライアント: リソース所有者のデータへのアクセスを求めるサードパーティのアプリケーション。
認可サーバー: リソース所有者を検証し、クライアントに認可を付与します。
リソースサーバー: 保護されたリソースを格納・管理し、アクセス用の API を提供します。

OAuth 2.0認証フロー

OAuth 2.0プロトコルでは、さまざまな認可フローを使って認可を実装します。

一般的な認可フローは次のとおりです。

Authorization Code Grant: クライアントはユーザーを認可サーバーにリダイレクトします。ユーザーがログインして許可を与えると、認可サーバーはクライアントに認可コードを返します。その後クライアントは認可コードと自身の資格情報を交換してアクセストークンを取得します。
Authorization Code Grant with PKCE (Proof Key for Code Exchange): 標準の認可コードフローと似ていますが、クライアントが PKCE (Proof Key for Code Exchange) を使ってセキュリティを強化します。
Resource Owner Password Credentials Grant: リソース所有者がクライアントに直接ユーザー名とパスワードを提供します。クライアントはこれらの資格情報を使って認可サーバーからアクセストークンを要求します。
Client Credentials Grant: クライアント自身がリソースへのアクセスを必要とする場合に、自身の資格情報を使って直接認可サーバーからアクセストークンを要求します。
Implicit Grant: クライアントがブラウザベースのアプリケーションから直接アクセストークンを取得するために使われます。一般にウェブフロントエンドアプリケーションで使われます。

GitHub の OAuth 2.0 (クライアントID、クライアントシークレット) を設定

ステップ 1: アプリを作成してクライアントID とクライアントシークレットを取得する

クライアントIDとクライアントキーを取得するには、まずアプリケーションを作成する必要があります。次のリンクから Github でアプリを作成してください: https://github.com/settings/applications/new

次に、"Homepage URL" にドメイン名を入力します。ローカルデバッグの場合は、ローカルサービスを入力できます(例: http://127.0.0.1:8000)。

"Authorization callback URL" にコールバックアドレスを入力します。ドメイン名またはローカルコールバックアドレスを使えます(例:http://127.0.0.1:8000/callback)。

関連する設定を入力したら、"Register application" をクリックしてアプリを作成します。

アプリが作成されると、クライアントIDが生成されます。クライアントシークレットは別途生成する必要があります。"Generate a new client secret" をクリックしてキーを生成してください。

ステップ 2: アクセストークンを取得する

上記のステップ1の準備ができたら、アクセストークン(Token)を申請できます。この手順を Apidog を使ってデモします。Apidog は優れた API デバッグおよび管理ツールです。

Apidog でアクセストークン(Token)を直接取得できます。まだ Apidog をインストールしていない場合は、ダウンロードしてください!

button

⒈Apidog で新しい HTTP プロジェクトを作成し、開いたら、そのプロジェクト内に新しいリクエストを作成し、[編集 -> 認証 -> OAuth 2.0] のオプションを選択します。

⒉クライアントID、クライアントシークレット、リダイレクトアドレスを設定
Apidog の OAuth 2.0 ページで、デフォルトで選択されている認可モードは Authorization Code (認可コードモード) です。

GitHub の OAuth 2.0 も Authorization Code (認可コードモード) を使うため、ここでは切り替える必要はありません。

次に、ページの下部にある Client ID、Client Secret、Callback URL を探します。クライアントID(Client ID)、クライアントシークレット(Client Secret)、設定したコールバックアドレス(Callback URL)は、GitHub の OAuth 2.0 サービスから取得します。

取得した値をそのまま入力してください。具体的な値は「ステップ 1」の設定値です。

⒊認可コードのリクエストアドレスを設定
GitHub の公式ドキュメントによると、OAuth 2.0 認証時の認可コードのリクエストアドレス(Auth URL)は次のとおりです。
https://github.com/login/oauth/authorize

この認可コードのリクエストアドレスをAuth URLに入力します。このアドレスはログイン認可ページと考えられます。

初めてログイン状態を確認する際に、このページ(クライアント側でウィンドウ形式で)が開き、ユーザー名とパスワードの入力を求められます。

一般に、手動でログイン認可ページを構築する場合は、認可アドレスの後ろにパラメータを付けて渡す必要があります。

しかし、Apidog ではURLの後ろのパラメータを渡す必要はなく、疑問符 ? の手前のパスのみで十分です。それ以外の必須パラメータは別のオプションで個別に設定されているためです。

もちろん、Query パラメータを付けたい場合は、インプットボックスの後ろにあるアイコンをクリックして追加することができます。

また、「詳細設定」を展開し、必要なパラメータの値を対応するオプションに入力することもできます。例えば、「Scope」に必要な権限 read:user、user:email などを入力できます。

その他の権限については、GitHub ヘルプドキュメントの権限モジュールで確認できます。「State」オプションには state を入力します。state はクロスサイトリクエストフォージェリを防ぐためです。

⒋アクセストークンのリクエストアドレスを設定
GitHub の公式ドキュメントによると、アクセストークンを申請するための要求URLは次のとおりです。
https://github.com/login/oauth/access_token

上記のアドレスを Apidog の OAuth 2.0 ページの Access Token URL の入力フィールドに入力します。

⒌GitHubのOAuth 2.0 サービスのアクセストークンを取得
上記の設定項目を設定したら、「Get Token」ボタンをクリックしてアクセストークンを取得できます。

クリックすると、初回ログイン時は認可を求めるウィンドウがポップアップするので、GitHub アカウントのユーザー名とパスワードを入力します。

ユーザー名とパスワードを入力すると、認可の確認または二段階認証を求められます。確認後、「確認」をクリックします。

認可が完了すると、アクセストークンが自動的に取得され、ページに表示されます。同時に、GitHub から返された他の情報も解析されます(下図)。ここで "期限切れ" と表示されているのは、GitHub から expires_in 属性が返されなかったため判断できないためですが、このトークンは使用可能です。

次に別のリクエストを実行してみましょう。

ステップ 3: トークンに基づいてオープンリソースにアクセス

アクセストークン(Token)を取得できたら、このアクセストークンを使って GitHub のオープンリソースを呼び出すことができます。具体的なオープンリソースは GitHub API で確認できます。

例えば、次の API ではユーザー情報を取得しています。インターフェースで何も返されない場合は、権限を持っているかを確認する必要があります。「ステップ 2」のセクション 3 で説明したように、Scope で設定します。

リクエストを送信する際、Apidog は自動的にリクエストヘッダーの Authorization に Token を "Bearer" とともに付加して送信します。トークンをURLに付加したい場合は、ページの設定項目で Token の「追加場所」を変更し、「Query Params」を選択することもできます。

まとめ

この記事では、OAuth 2.0 認証の仕組みと、GitHub の OAuth 2.0 サービスを利用してアクセストークンを取得する手順をご紹介しました。OAuth 2.0 は、サードパーティアプリケーションがパスワードを共有することなく、ユーザーデータにアクセスできる認可プロトコルです。主な関係者は、リソース所有者、クライアント、認可サーバー、リソースサーバーです。

GitHub の OAuth 2.0 サービスを使う前に、クライアントID とクライアントシークレットを取得する必要があります。GitHub の開発者設定ページで新しいアプリケーションを登録することで、これらの値を取得できます。

次に、Apidog という便利な API 管理ツールを使って、GitHub の OAuth 2.0 認証フローを実装しました。認可コードのリクエストURL、アクセストークンのリクエストURL、クライアントID、クライアントシークレット、コールバックURLなどの設定値を入力し、ユーザー認証を経てアクセストークンを取得しました。最後に、取得したアクセストークンを使って、GitHub の公開APIにアクセスする方法を説明しました。

OAuth 2.0 はセキュアでスケーラブルな認可方式なので、今後さまざまなサービスで広く利用されていくでしょう。Apidog のようなツールを使えば、OAuth 2.0 の認証フローを簡単に実装し、APIを呼び出すことができます。