モバイル &デスクトップ アプリ向け OAuth 2.0

このドキュメントでは、スマートフォン、タブレット、パソコンなどのデバイスにインストールされたアプリケーションが、Google の OAuth 2.0 エンドポイントを使用して Google API へのアクセスを承認する方法について説明します。

OAuth 2.0 を使用すると、ユーザー名やパスワードなどの情報を秘密にしたまま、ユーザーが特定のデータをアプリケーションと共有できます。 たとえば、アプリケーションは OAuth 2.0 を使用して、Google ドライブにファイルを保存する権限をユーザーから取得できます。

インストール済みのアプリは個々のデバイスに配布され、それらのアプリはシークレットを保持できないとみなされます。ユーザーがアプリを使用しているとき、またはアプリがバックグラウンドで実行されているときに、Google API にアクセスできます。

この承認フローは、ウェブサーバー アプリケーションで使用するものと似ています。主な違いは、インストール済みのアプリがシステム ブラウザを開き、Google の承認サーバーからのレスポンスを処理するためにローカル リダイレクト URI を指定する必要があることです。

代案

モバイルアプリの場合は、Android または iOS 向けの Google ログインを使用することをおすすめします。Google ログインのクライアント ライブラリは認証とユーザー承認を処理するので、ここで説明する低レベルのプロトコルよりも実装が容易です。

システム ブラウザをサポートしていないデバイス、または入力機能が制限されているデバイス（テレビ、ゲーム機、カメラ、プリンタなど）で実行されるアプリについては、テレビおよびデバイス用の OAuth 2.0 またはテレビや入力が限られているデバイスでのログインをご覧ください。

ライブラリとサンプル

このドキュメントで説明する OAuth 2.0 フローを実装するため、次のライブラリとサンプルを使用することをおすすめします。

• AppAuth for Android ライブラリ
• AppAuth for iOS ライブラリ
• アプリ用 OAuth: Windows サンプル

Prerequisites

プロジェクトでAPI を有効にする

Google API を呼び出すすべてのアプリケーションは、 API Consoleでこれらの API を有効にする必要があります。

プロジェクトで API を有効にするには:

1. Google API ConsoleのOpen the API Library 。
2. If prompted, select a project, or create a new one.
3. API Library には、利用可能なすべての API がプロダクト ファミリーと人気度別にグループ化されて一覧表示されます。有効にする API がリストに表示されない場合は、検索を使用して探すか、その API が属するプロダクト ファミリーの [すべて表示] をクリックします。
4. 有効にする API を選択し、[有効にする] ボタンをクリックします。
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

承認認証情報を作成する

OAuth 2.0 を使用して Google API にアクセスするアプリケーションには、Google の OAuth 2.0 サーバーでそのアプリケーションを識別するための認証情報が必要です。次の手順では、プロジェクトの認証情報を作成する方法について説明します。アプリケーションはこの認証情報を使用して、そのプロジェクトで有効にした API にアクセスできます。

1. Go to the Credentials page.
2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
3. 以下のセクションでは、Google の承認サーバーがサポートするクライアント タイプとリダイレクト方法について説明します。アプリケーションに適したクライアント タイプを選択し、OAuth クライアントに名前を付け、フォームの他のフィールドを適宜設定します。

アクセス スコープを特定する

スコープを使用すると、アプリケーションは必要なリソースへのアクセスのみをリクエストできます。また、ユーザーはアプリケーションに付与するアクセス権の量を制御することもできます。そのため、リクエストするスコープの数とユーザーの同意を得る可能性の間には逆の関係がある場合があります。

OAuth 2.0 認証の実装を開始する前に、アプリがアクセス権限を必要とするスコープを特定することをおすすめします。

OAuth 2.0 API スコープのドキュメントには、Google API へのアクセスに使用できるスコープの一覧が記載されています。

OAuth 2.0 アクセス トークンの取得

以下の手順では、アプリケーションが Google の OAuth 2.0 サーバーとやり取りし、ユーザーの代わりに API リクエストを実行することについてユーザーの同意を得ます。ユーザーの承認が必要な Google API リクエストをアプリケーションで実行するには、この同意が必要です。

ステップ 1: コード検証とチャレンジを生成する

Google は、インストール済みのアプリフローのセキュリティを高めるため、Proof Key for Code Exchange（PKCE）プロトコルをサポートしています。認可リクエストごとに一意のコード検証ツールが作成され、変換された値（「code_challenge」と呼ばれる）が認可サーバーに送信されて認可コードを取得します。

コード検証ツールを作成する

code_verifier は、予約されていない文字 [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" を使用する高エントロピー暗号ランダム文字列で、最小文字数は 43 文字、最大文字数は 128 文字です。

コード検証ツールには、値の推測が実用的にならないように、十分なエントロピーが必要です。

コード作成チャレンジ

コード チャレンジを作成する 2 つの方法がサポートされています。

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

ステップ 2: Google の OAuth 2.0 サーバーにリクエストを送信する

ユーザー承認を取得するには、Google の承認サーバーに https://accounts.google.com/o/oauth2/v2/auth でリクエストを送信します。このエンドポイントは、アクティブ セッションの検索を処理し、ユーザーを認証して、ユーザーの同意を取得します。エンドポイントには SSL を介してのみアクセスでき、HTTP（非 SSL）接続は拒否されます。

認可サーバーは、インストール済みのアプリケーションについて、次のクエリ文字列パラメータをサポートしています。

認可 URL の例

以下のタブに、リダイレクト URI オプションごとの認証 URL のサンプルを示します。

redirect_uri パラメータの値を除き、URL は同じです。URL には、必須の response_type パラメータと client_id パラメータ、省略可能な state パラメータも含まれています。読みやすくするため、各 URL には改行とスペースが含まれています。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

ステップ 3: Google がユーザーに同意を求める

このステップでは、ユーザーは、リクエストされたアクセス権をアプリケーションに付与するかどうかを判断します。この段階では、アプリケーションの名前と、ユーザーの認証情報を使用してアクセス権限をリクエストしている Google API サービスの名前、付与するアクセス スコープの概要を示す同意ウィンドウが表示されます。ユーザーは、アプリケーションからリクエストされた 1 つ以上のスコープへのアクセスを許可することも、リクエストを拒否することもできます。

アプリケーションは、アクセスが許可されたことを示す Google の OAuth 2.0 サーバーからのレスポンスを待つため、この段階では何も行う必要はありません。このレスポンスについては、次の手順で説明します。

ステップ 4: OAuth 2.0 サーバーのレスポンスを処理する

アプリケーションが認可レスポンスを受け取る方法は、使用するリダイレクト URI スキームによって異なります。スキームに関係なく、レスポンスには認証コード（code）またはエラー（error）が含まれます。たとえば、error=access_denied はユーザーがリクエストを拒否したことを示します。

ユーザーがアプリケーションにアクセス権を付与した場合、次のステップで説明するように、認証コードをアクセス トークンと更新トークンと交換できます。

ステップ 5: 更新トークンとアクセス トークンの認証コードを交換する

認可コードをアクセス トークンと交換するには、https://oauth2.googleapis.com/token エンドポイントを呼び出して、次のパラメータを設定します。

次のスニペットにサンプル リクエストを示します。

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google はこのリクエストに対して、有効期間の短いアクセス トークンと更新トークンを含む JSON オブジェクトを返します。

レスポンスには、次のフィールドが含まれます。

次のスニペットにサンプル レスポンスを示します。

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Google API の呼び出し

アプリケーションがアクセス トークンを取得した後、API に必要なアクセスのスコープが付与されていれば、そのトークンを使用して、特定のユーザー アカウントに代わって Google API を呼び出すことができます。これを行うには、access_token クエリ パラメータまたは Authorization HTTP ヘッダーの Bearer 値のいずれかを含めて、API へのリクエストにアクセス トークンを含めます。クエリ文字列はサーバーログに表示される傾向があるため、可能であれば HTTP ヘッダーを使用することをおすすめします。ほとんどの場合、クライアント ライブラリを使用して Google API の呼び出しをセットアップできます（Drive Files API の呼び出しなど）。

OAuth 2.0 Playground では、すべての Google API とそのスコープを確認できます。

HTTP GET の例

Authorization: Bearer HTTP ヘッダーを使用した drive.files エンドポイント（Drive Files API）の呼び出しは、次のようになります。独自のアクセス トークンを指定する必要があります。

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

access_token クエリ文字列パラメータを使用した、認証されたユーザーに対する同じ API の呼び出しの例を次に示します。

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl の例

これらのコマンドは、curl コマンドライン アプリケーションでテストできます。HTTP ヘッダー オプションを使用した例を次に示します（推奨）。

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

または、クエリ文字列パラメータ オプション:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

アクセス トークンをリフレッシュする

アクセス トークンは定期的に期限が切れ、関連する API リクエストに対して無効な認証情報になります。トークンに関連付けられたスコープへのオフライン アクセスをリクエストした場合、ユーザーに権限をリクエストしなくても（ユーザーが不在の場合を含めて）アクセス トークンを更新できます。

アクセス トークンを更新するには、アプリケーションが次のパラメータを含む HTTPS POST リクエストを Google の承認サーバー（https://oauth2.googleapis.com/token）に送信します。

次のスニペットにサンプル リクエストを示します。

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

ユーザーがアプリケーションに付与されたアクセスを取り消さない限り、トークン サーバーは新しいアクセス トークンを含む JSON オブジェクトを返します。次のスニペットにサンプル レスポンスを示します。

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

発行される更新トークンの数には制限があります。クライアントとユーザーの組み合わせごとに 1 つ、すべてのクライアントでユーザーごとに 1 つの制限があります。更新トークンは長期間保存し、有効な間は継続して使用する必要があります。アプリケーションがリクエストする更新トークンが多すぎると、これらの制限に達することがあり、その場合は古い更新トークンが機能しなくなります。

トークンの取り消し

場合によっては、ユーザーがアプリケーションに与えられたアクセス権の取り消しを希望することがあります。ユーザーは アカウント設定にアクセスしてアクセス権を取り消すことができます。詳しくは、サポート ドキュメント「アカウントにアクセスできるサードパーティのサイトやアプリのサイトやアプリのアクセス権の削除」をご覧ください。

また、アプリケーションに付与されているアクセス権をプログラムで取り消すこともできます。プログラムによる取り消しは、ユーザーがアプリケーションの登録を解除した場合や、アプリケーションを削除した場合、またはアプリに必要な API リソースが大幅に変更された場合などに重要です。つまり、削除プロセスに、以前にアプリに付与された権限を確実に削除するための API リクエストを含めることができます。

プログラムでトークンを取り消すには、アプリケーションは https://oauth2.googleapis.com/revoke にリクエストを行い、トークンをパラメータとして含めます。

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

トークンはアクセス トークンまたは更新トークンのいずれかです。トークンがアクセス トークンで、対応する更新トークンがある場合、更新トークンも取り消されます。

取り消しが正常に処理されると、レスポンスの HTTP ステータス コードは 200 になります。エラーが発生すると、HTTP ステータス コード 400 がエラーコードとともに返されます。

関連情報

ここで説明するベスト プラクティスの多くが、IETF の現在のベスト プラクティスである OAuth 2.0 for Native Apps で確立されています。