モバイル / デスクトップ アプリ用の OAuth 2.0

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

OAuth 2.0 では、ユーザー名やパスワードなどの情報を秘密にしたまま、ユーザーが特定のデータをアプリケーションと共有できます。たとえば、アプリケーションで OAuth 2.0 を使い、ユーザーの YouTube チャンネルに動画をアップロードする権限を取得できます。

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

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

代替手段

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

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

ライブラリとサンプル

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

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

前提条件

プロジェクトで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. [ライブラリ] ページで、YouTube Data API を見つけて有効にします。アプリケーションで使用する他の API を見つけて、それらも有効にします。

承認認証情報を作成する

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 認証の実装を開始する前に、アプリがアクセス権限を必要とするスコープを設定しておくことをおすすめします。

YouTube Data API v3 は、次のスコープを使用します。

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 サーバーにリクエストを送信する

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

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

認証 URL の例

以下のタブには、さまざまなリダイレクト URI オプションの承認 URL の例を示します。

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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 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 から同意ウィンドウが表示されます。このウィンドウには、アプリケーションの名前と、ユーザーの認証情報を使用してアクセス権限をリクエストしている 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/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

ステップ 6: ユーザーが付与したスコープを確認する

複数のスコープを一度にリクエストする場合、ユーザーがアプリがリクエストするすべてのスコープを許可しないことがあります。アプリは、ユーザーによって付与されたスコープを常に確認し、スコープの拒否が発生した場合は関連する機能を無効にして対処する必要があります。詳細については、きめ細かい権限を処理する方法をご覧ください。

ユーザーがアプリケーションに特定のスコープへのアクセス権を付与しているかどうかを確認するには、アクセス トークン レスポンスの scope フィールドを確認します。access_token によって付与されたアクセス権のスコープ。スペース区切りの大文字と小文字を区別する文字列のリストとして表されます。

たとえば、次のアクセス トークン レスポンスの例は、ユーザーがアプリに、ユーザーの YouTube 動画、評価、コメント、字幕の表示、編集、完全削除の権限を付与したことを示しています。

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

Google API の呼び出し

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

YouTube Data API は、複数の YouTube チャンネルを所有して管理している YouTube コンテンツ所有者（レコード レーベルや映画制作会社など）のサービス アカウントのみをサポートしています。

すべての Google API を試して、そのスコープを確認するには、OAuth 2.0 Playground をご覧ください。

HTTP GET の例

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

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下は、access_token クエリ文字列パラメータを使用して、認証済みユーザーの同じ API を呼び出すコードです。

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl の例

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

または、クエリ文字列パラメータ オプションを使用します。

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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

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

アクセス トークンを更新するには、アプリケーションが Google の認可サーバーに HTTPS POST リクエストを送信します。このリクエストには、次のパラメータが含まれます。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 では、ここで説明するベスト プラクティスの多くが定められています。