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

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

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

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

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

代替手段

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

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

ライブラリとサンプル

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

• Android 用 AppAuth ライブラリ
• iOS 用 AppAuth ライブラリ
• アプリ用の 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 では、次のスコープを使用します。

Google API へのアクセスに使用できるスコープの一覧については、OAuth 2.0 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=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"
}

Google API の呼び出し

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

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

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

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 リクエストに対する無効な認証情報になります。トークンに関連付けられているスコープへのオフライン アクセスをリクエストした場合、ユーザーに権限を求めることなくアクセス トークンを更新できます（ユーザーがいない場合も同様です）。

アクセス トークンを更新するため、次のパラメータを含む 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 では、ここで説明する多くのベスト プラクティスが確立されています。