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

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

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

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

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

代替手段

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

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

ライブラリとサンプル

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

前提条件

プロジェクトで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. [Library] ページでは、YouTube Analytics API と YouTube Reporting API を探して有効にします。YouTube アナリティクスのデータを取得する多くのアプリケーションは、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 クライアントに名前を付け、フォームの他のフィールドを適切に設定します。
Android
  1. アプリケーションの種類として [Android] を選択します。
  2. OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
  3. Android アプリのパッケージ名を入力します。この値は、アプリ マニフェスト ファイル内の <manifest> 要素の package 属性で定義されています。
  4. アプリ配信の SHA-1 署名証明書フィンガープリントを入力します。
    • アプリで Google Play アプリ署名を使用している場合は、Google Play Console の [アプリ署名] ページから SHA-1 フィンガープリントをコピーします。
    • 独自のキーストアと署名鍵を管理する場合は、Java に付属の keytool ユーティリティを使用して、人が読める形式で証明書情報を出力します。keytool 出力の Certificate fingerprints セクションにある SHA1 値をコピーします。詳しくは、Android 用 Google API ドキュメントのクライアントの認証をご覧ください。
  5. (省略可)Android アプリの所有権を確認します。
  6. [作成] をクリックします。
iOS
  1. アプリケーションの種類として [iOS] を選択します。
  2. OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
  3. アプリのバンドル ID を入力します。バンドル ID は、アプリの情報プロパティ リストのリソース ファイル(info.plist)に含まれている CFBundleIdentifier キーの値です。この値は、通常、Xcode プロジェクト エディタの [General] ペインまたは [Signing & Capabilities] ペインに表示されます。バンドル ID は、Apple の App Store Connect サイトで、対象アプリの [アプリ情報] ページの [全般情報] セクションにも表示されます。
  4. (省略可)

    アプリが Apple の App Store で公開されている場合は、アプリの App Store ID を入力します。ストア ID は、Apple App Store のすべての URL に含まれる数字文字列です。

    1. iOS デバイスまたは iPadOS デバイスで Apple App Store アプリを開きます。
    2. 自分のアプリを探します。
    3. [共有] ボタン(正方形と上矢印アイコン)を選択します。
    4. [リンクをコピー] を選択します。
    5. コピーしたリンクをテキスト エディタに貼り付けます。App Store ID は URL の最後の部分です。

      例: https://apps.apple.com/app/google/id284815942

  5. (省略可)

    チーム ID を入力します。詳細については、Apple Developer Account ドキュメントのチーム ID を確認するをご覧ください。

  6. [作成] をクリックします。
UWP
  1. アプリケーションの種類として [ユニバーサル Windows プラットフォーム] を選択します。
  2. OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
  3. アプリの 12 文字の Microsoft Store ID を入力します。この値は、[アプリ管理] セクションの [アプリ ID] ページの Microsoft パートナー センターで確認できます。
  4. [作成] をクリックします。

UWP アプリの場合、カスタム URI スキームは 39 文字以下にする必要があります。

カスタム URI スキーム(Android、iOS、UWP)

カスタム URI スキームはディープリンクの一種で、カスタム定義のスキームを使ってアプリを開くことができます。

Android でカスタム URI スキームを使用する代替方法

Android 用 Google ログイン SDK を使用すると、OAuth 2.0 レスポンスがアプリに直接配信されるため、リダイレクト URI が不要になります。

Google Sign-In for Android SDK への移行方法

現在、Android で OAuth 統合にカスタム スキームを使用している場合、推奨される Android 向け Google ログイン SDK の使用に完全に移行するには、以下の操作を完了する必要があります。

  1. Google ログイン SDK を使用するようにコードを更新します。
  2. Google API Console でカスタム スキームのサポートを無効にします。

Google ログイン Android SDK に移行する手順は次のとおりです。

  1. Google ログイン Android SDK を使用するようにコードを更新します。
    1. コードを調べて、Google の OAuth 2.0 サーバーにリクエストを送信する場所を特定します。カスタム スキームを使用する場合、リクエストは次のようになります。
        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        
      com.example.app:/oauth2redirect は、上記の例のカスタム スキームのリダイレクト URI です。カスタム URI スキームの値の形式について詳しくは、 redirect_uri パラメータの定義をご覧ください。
    2. Google ログイン SDK の設定に必要な scopeclient_id のリクエスト パラメータをメモしておきます。
    3. Android アプリへの Google ログインの統合を開始するの手順に沿って SDK をセットアップします。前の手順で取得した client_id を再利用するため、バックエンド サーバーの OAuth 2.0 クライアント ID を取得する手順はスキップできます。
    4. サーバーサイド API アクセスを有効にするの手順に沿って操作します。手順は次のとおりです。
      1. getServerAuthCode メソッドを使用して、権限をリクエストするスコープの認証コードを取得します。
      2. 認証コードをアプリのバックエンドに送信して、アクセス トークンおよび更新トークンと交換します。
      3. 取得したアクセス トークンを使用して、ユーザーの代わりに Google API を呼び出します。
  2. Google API Console でカスタム スキームのサポートを無効にします。
    1. OAuth 2.0 認証情報リストに移動し、Android クライアントを選択します。
    2. [詳細設定] セクションに移動し、[カスタム URI スキームを有効にする] チェックボックスをオフにし、[保存] をクリックしてカスタム URI スキームのサポートを無効にします。
カスタム URI スキームを有効にする
推奨される代替手段がうまくいかない場合は、次の手順に沿って Android クライアントのカスタム URI スキームを有効にします。
  1. OAuth 2.0 認証情報リストに移動し、Android クライアントを選択します。
  2. [詳細設定] セクションに移動し、[カスタム URI スキームを有効にする] チェックボックスをオンにして、[保存] をクリックしてカスタム URI スキームのサポートを有効にします。
Chrome アプリでカスタム URI スキームを使用する代わりに使用する方法

Chrome Identity API を使用すると、OAuth 2.0 レスポンスをアプリに直接配信できるため、リダイレクト URI が不要になります。

アプリの所有権を確認する(Android、Chrome)

アプリの所有権を確認して、アプリのなりすましのリスクを軽減できます。

Android

Google Play デベロッパー アカウントがあり、アプリが Google Play Console に登録されている場合は、確認プロセスを完了するためにそのアカウントを使用できます。検証を成功させるには、次の要件を満たす必要があります。

  • 検証対象の Android OAuth クライアントと同じパッケージ名と SHA-1 署名証明書フィンガープリントを持つアプリが Google Play Console に登録されている必要があります。
  • Google Play Console で、アプリの管理者権限が必要です。Google Play Console でのアクセス管理について詳しくは、こちらをご覧ください。

Android クライアントの [Verify App Ownership] で、[Verify Ownership] ボタンをクリックして、検証プロセスを完了します。

検証に成功すると、検証プロセスが成功したことを確認する通知が表示されます。それ以外の場合は、エラー プロンプトが表示されます。

確認が失敗した場合の解決方法:

  • 検証するアプリが Google Play Console に登録されていることを確認します。
  • Google Play Console で、アプリの管理者権限があることを確認します。
Chrome

確認プロセスを完了するには、Chrome ウェブストアのデベロッパー アカウントを使用します。 適格性の確認に合格するには、次の要件を満たす必要があります。

  • Chrome ウェブストア デベロッパー ダッシュボードに、確認対象の Chrome 拡張機能 OAuth クライアントと同じアイテム ID の登録済みアイテムが必要です。
  • Chrome ウェブストアのアイテムのパブリッシャーである必要があります。 Chrome ウェブストア デベロッパー ダッシュボードでのアクセス管理の詳細をご覧ください。

Chrome 拡張機能クライアントの [Verify App Ownership] セクションで、[Verify Ownership] ボタンをクリックして、検証プロセスを完了します。

注: アカウントにアクセス権を付与した後、数分待ってから確認プロセスを完了してください。

検証に成功すると、検証プロセスが成功したことを確認する通知が表示されます。それ以外の場合は、エラー プロンプトが表示されます。

確認が失敗した場合の解決方法:

  • 確認対象の Chrome 拡張機能 OAuth クライアントと同じアイテム ID を持つ登録済みアイテムが Chrome ウェブストア デベロッパー ダッシュボードにあることを確認します。
  • アプリのパブリッシャーであることを確認してください。つまり、アプリの個別のパブリッシャーか、アプリのグループ パブリッシャーのメンバーである必要があります。Chrome ウェブストア デベロッパー ダッシュボードでのアクセス管理の詳細をご確認ください。
  • グループ投稿者リストを更新したばかりの場合は、Chrome ウェブストア デベロッパー ダッシュボードで、グループ投稿者メンバーシップ リストが同期されていることを確認します。 パブリッシャー メンバーシップ リストの同期について

ループバック IP アドレス(macOS、Linux、Windows デスクトップ)

この URL を使用して認証コードを受信するには、アプリケーションがローカル ウェブサーバーをリッスンしている必要があります。これは多くのプラットフォームで可能ですが、すべてではありません。ただし、プラットフォームでサポートされている場合は、このメカニズムを使用して認証コードを取得することをおすすめします。

アプリが認証レスポンスを受け取った場合、ユーザビリティを最大限に高めるため、ブラウザを閉じてアプリに戻るようユーザーに指示する HTML ページを表示してレスポンスを返す必要があります。

推奨される使用方法 macOS、Linux、Windows のデスクトップ アプリ(Universal Windows Platform は除く)
フォームの値 アプリケーションの種類を [デスクトップ アプリ] に設定します。

手動でのコピー/貼り付け

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

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

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

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

スコープ
https://www.googleapis.com/auth/youtube YouTubeアカウントを管理する
https://www.googleapis.com/auth/youtube.readonly YouTubeアカウントを表示する
https://www.googleapis.com/auth/youtubepartner YouTubeでアセットと関連コンテンツを表示および管理する
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTubeコンテンツの金銭的および非金銭的なYouTubeAnalyticsレポートを表示する
https://www.googleapis.com/auth/yt-analytics.readonly YouTubeコンテンツのYouTubeAnalyticsレポートを表示する

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

スコープ
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTubeコンテンツの金銭的および非金銭的なYouTubeAnalyticsレポートを表示する
https://www.googleapis.com/auth/yt-analytics.readonly YouTubeコンテンツのYouTubeAnalyticsレポートを表示する

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 つの方法がサポートされています。

コード チャレンジの生成方法
S256(推奨) コード チャレンジは、Base64URL(パディングなし)でエンコードされたコード検証ツールの SHA256 ハッシュです。
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)接続は拒否されます。

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

パラメータ
client_id 必須

アプリケーションのクライアント ID。この値は API Console Credentials pageで確認できます。

redirect_uri 必須

Google の承認サーバーがアプリにレスポンスを送信する方法を指定します。インストール済みのアプリで使用できるリダイレクト オプションはいくつかありますが、特定のリダイレクト方法を念頭に置いて認証認証情報をセットアップします。

この値は、クライアントの API Console Credentials pageで構成した OAuth 2.0 クライアントで承認済みのリダイレクト URI のいずれかと完全に一致する必要があります。この値が承認済みの URI と一致しない場合、redirect_uri_mismatch エラーが発生します。

次の表に、各メソッドの適切な redirect_uri パラメータ値を示します。

redirect_uri 個の値
カスタム URI スキーム com.example.app:redirect_uri_path

or

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app は、ユーザーが管理するドメインの逆 DNS 表記です。カスタム スキームを有効にするには、ピリオドを含める必要があります。
  • com.googleusercontent.apps.123 は、クライアント ID の逆 DNS 表記です。
  • redirect_uri_path は、/oauth2redirect などのオプションのパス コンポーネントです。パスの先頭は 1 つのスラッシュにする必要があります。これは、通常の HTTP URL とは異なります。
ループバック IP アドレス http://127.0.0.1:port または http://[::1]:port

関連するループバック IP アドレスをプラットフォームに照会し、ランダムに使用可能なポートで HTTP リスナーを起動します。port は、アプリがリッスンする実際のポート番号に置き換えます。

モバイルアプリでのループバック IP アドレスのリダイレクト オプションのサポートは 非推奨になりました。

response_type 必須

Google OAuth 2.0 エンドポイントが認証コードを返すかどうかを決定します。

インストール済みのアプリのパラメータ値を code に設定します。

scope 必須

ユーザーの代わりにアプリケーションがアクセスできるリソースを識別するスコープのスペース区切りリスト。これらの値により、Google がユーザーに表示する同意画面が決まります。

スコープを使用すると、アプリケーションが必要とするリソースへのアクセス権のみをリクエストできると同時に、ユーザーはアプリケーションに付与するアクセス権の量を制御できます。したがって、リクエストするスコープの数とユーザーの同意を得る可能性には逆相関があります。

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

スコープ
https://www.googleapis.com/auth/youtube YouTubeアカウントを管理する
https://www.googleapis.com/auth/youtube.readonly YouTubeアカウントを表示する
https://www.googleapis.com/auth/youtubepartner YouTubeでアセットと関連コンテンツを表示および管理する
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTubeコンテンツの金銭的および非金銭的なYouTubeAnalyticsレポートを表示する
https://www.googleapis.com/auth/yt-analytics.readonly YouTubeコンテンツのYouTubeAnalyticsレポートを表示する

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

スコープ
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTubeコンテンツの金銭的および非金銭的なYouTubeAnalyticsレポートを表示する
https://www.googleapis.com/auth/yt-analytics.readonly YouTubeコンテンツのYouTubeAnalyticsレポートを表示する

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

code_challenge 推奨

認証コードの交換時にサーバーサイド チャレンジとして使用する、エンコードされた code_verifier を指定します。詳細については、上記のコード チャレンジの作成をご覧ください。

code_challenge_method 推奨

認証コードの交換時に使用される code_verifier のエンコードに使用された方法を指定します。このパラメータは、上記の code_challenge パラメータと併用する必要があります。code_challenge を含むリクエストに code_challenge_method の値が存在しない場合、code_challenge_method の値はデフォルトで plain になります。このパラメータでサポートされている値は S256 または plain のみです。

state 推奨

アプリケーションが認可リクエストと認可サーバーのレスポンスの間で状態を維持するために使用する任意の文字列値を指定します。ユーザーがアプリケーションのアクセス リクエストを承諾または拒否すると、サーバーは redirect_uri の URL フラグメント識別子(#)で name=value ペアとして送信した正確な値を返します。

このパラメータは、ユーザーをアプリ内の適切なリソースに誘導する、ノンスを送信する、クロスサイト リクエスト フォージェリを緩和するなど、さまざまな目的で使用できます。redirect_uri は推測できるため、state 値を使用すると、受信接続が認証リクエストの結果であるという保証を高めることができます。ランダムな文字列を生成するか、クライアントの状態を取得する Cookie などのハッシュをエンコードする場合、レスポンスを検証して、リクエストとレスポンスが同じブラウザから送信されたことを確認して、クロスサイト リクエスト フォージェリなどの攻撃から保護できます。state トークンを作成して確認する方法の例については、OpenID Connect のドキュメントをご覧ください。

login_hint 省略可

認証対象のユーザーをアプリケーションが認識している場合、このパラメータを使用して、Google 認証サーバーにヒントを提供できます。サーバーはこのヒントを使用して、ログイン フォームのメール フィールドに事前入力するか、適切なマルチログイン セッションを選択することで、ログインフローを簡素化します。

パラメータ値をメールアドレスまたは sub 識別子に設定します。これは、ユーザーの Google ID に相当します。

認証 URL の例

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

各 URL は、ユーザーの YouTube アナリティクス レポートを取得するアクセスを許可するスコープへのアクセスをリクエストします。

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

カスタム URI スキーム

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.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

ループバック IP アドレス

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.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 API サービスの名前と、付与されるアクセス権の範囲の概要が表示されます。ユーザーは、アプリケーションからリクエストされた 1 つ以上のスコープへのアクセスを許可することも、リクエストを拒否することもできます。

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

エラー

Google の OAuth 2.0 認可エンドポイントへのリクエストでは、想定される認証フローと認可フローではなく、ユーザー向けのエラー メッセージが表示されることがあります。一般的なエラーコードと推奨解決策を以下に示します。

admin_policy_enforced

Google アカウントは、Google Workspace 管理者のポリシーにより、リクエストされた 1 つ以上のスコープを承認できません。OAuth クライアント ID にアクセスが明示的に付与されるまで、管理者がすべてのスコープまたは機密性の高いスコープや制限付きスコープへのアクセスを制限する方法の詳細については、Google Workspace 管理者用ヘルプ記事の Google Workspace データにアクセスするサードパーティ製アプリと内部アプリを制御するをご覧ください。

disallowed_useragent

認可エンドポイントが、Google の OAuth 2.0 ポリシーで許可されていない埋め込みのユーザー エージェント内に表示される。

Android

Android デベロッパーが android.webkit.WebView で承認リクエストを開いたときに、このエラー メッセージが表示されることがあります。デベロッパーは、代わりに Android 用 Google ログインや OpenID Foundation の Android 用 AppAuth などの Android ライブラリを使用する必要があります。

Android アプリが埋め込みユーザー エージェントで一般的なウェブリンクを開き、ユーザーがサイトから Google の OAuth 2.0 認可エンドポイントに移動すると、このエラーが発生することがあります。デベロッパーは、オペレーティング システムのデフォルト リンクハンドラ(Android アプリリンク ハンドラとデフォルトのブラウザアプリの両方を含む)で一般的なリンクを開くことができるようにする必要があります。Android カスタムタブ ライブラリもサポートされているオプションです。

iOS

iOS や macOS のデベロッパーが WKWebView で承認リクエストを開くと、このエラーが発生することがあります。デベロッパーは、代わりに iOS 用の Google ログインや OpenID Foundation の iOS 用 AppAuth などの iOS ライブラリを使用する必要があります。

iOS または macOS のアプリが埋め込みユーザー エージェントで一般的なウェブリンクを開き、ユーザーがサイトから Google の OAuth 2.0 認可エンドポイントに移動すると、このエラーが発生することがあります。デベロッパーは、オペレーティング システムのデフォルトのリンクハンドラ(ユニバーサル リンク ハンドラとデフォルトのブラウザアプリの両方を含む)で一般的なリンクを開けるようにする必要があります。SFSafariViewController ライブラリもサポートされているオプションです。

org_internal

リクエスト内の OAuth クライアント ID は、特定の Google Cloud 組織内の Google アカウントへのアクセスを制限するプロジェクトの一部です。この構成オプションの詳細については、OAuth 同意画面の設定に関するヘルプ記事のユーザータイプのセクションをご覧ください。

invalid_grant

コード検証ツールとチャレンジを使用している場合、code_callenge パラメータが無効であるか、欠落しています。code_challenge パラメータが正しく設定されていることを確認します。

アクセス トークンの更新時、トークンの有効期限が切れているか、無効化されている。ユーザーを再度認証し、新しいトークンの取得についてユーザーの同意を求めます。このエラーが引き続き表示される場合は、アプリケーションが正しく構成され、リクエストで正しいトークンとパラメータを使用していることを確認してください。それ以外の場合は、ユーザー アカウントが削除されたか、無効になっている可能性があります。

redirect_uri_mismatch

承認リクエストで渡された redirect_uri が、OAuth クライアント ID の承認済みのリダイレクト URI と一致しません。 Google API Console Credentials pageで承認済みのリダイレクト URI を確認します。

渡された redirect_uri は、このクライアント タイプでは無効である可能性があります。

redirect_uri パラメータは、非推奨となりサポートされなくなった OAuth 帯域外(OOB)フローを参照している可能性があります。統合を更新するには、移行ガイドをご覧ください。

invalid_request

リクエストに何か問題がありました。これには、さまざまな理由が考えられます。

  • リクエストの形式が正しくありませんでした
  • リクエストに必須パラメータがありません
  • Google がサポートしていない認証方法がリクエストで使用されている。OAuth 統合で推奨の統合方法が使用されていることを確認する
  • リダイレクト URI にカスタム スキームが使用されている: 「Custom URI scheme is not supported on Chrome apps」または「Custom URI scheme is not enabled for your Android client」というエラー メッセージが表示される場合は、カスタム URI スキームを使用していることを意味します。このスキームは Chrome アプリでサポートされておらず、Android ではデフォルトで無効になっています。カスタム URI スキームの代替の詳細をご覧ください。

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

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

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

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

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

フィールド
client_id Credentials pageから取得した API Consoleクライアント ID。
client_secret Credentials pageから取得した API Consoleクライアント シークレット。
code 最初のリクエストから返された認証コード。
code_verifier ステップ 1 で作成したコード検証ツール。
grant_type OAuth 2.0 仕様で定義されている、このフィールドの値は authorization_code に設定する必要があります。
redirect_uri 指定された client_id の API Console Credentials page にあるプロジェクト用として一覧表示されたリダイレクト URI のいずれか。

次のスニペットはリクエストの例を示したものです。

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 Google API リクエストを承認するためにアプリケーションが送信するトークン。
expires_in アクセス トークンの残りの存続期間(秒)。
id_token 注: このプロパティは、リクエストに openidprofileemail などの ID スコープが含まれている場合のみ返されます。値は、ユーザーに関するデジタル署名された ID 情報を含む JSON Web Token(JWT)です。
refresh_token 新しいアクセス トークンを取得するために使用できるトークン。更新トークンは、ユーザーがアクセス権を取り消すまで有効です。 インストール済みのアプリケーションに対しては、更新トークンが常に返されます。
scope access_token で付与されるアクセス権のスコープ。スペース区切りの文字列(大文字と小文字を区別)のリストとして表されます。
token_type 返されるトークンのタイプ。現在、このフィールドの値は常に Bearer に設定されます。

次のスニペットは、レスポンスの例を示しています。

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

Google API の呼び出し

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

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

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

HTTP GET の例

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

GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

curl の例

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

または、クエリ文字列パラメータ オプションを次のように指定します。

curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

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

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

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

フィールド
client_id API Consoleから取得したクライアント ID。
client_secret API Consoleから取得したクライアント シークレット。(client_secret は、Android、iOS、Chrome アプリケーションとして登録されたクライアントからのリクエストには適用されません)。
grant_type OAuth 2.0 仕様で定義されているように、このフィールドの値は refresh_token に設定する必要があります。
refresh_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 人のユーザーごとに 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 は、ここで説明するベスト プラクティスの多くを確立しています。