このドキュメントでは、スマートフォン、タブレット、パソコンなどのデバイスにインストールされているアプリケーションが、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 フローを実装するため、次のライブラリとサンプルを使用することをおすすめします。
- Android 用 AppAuth ライブラリ
- iOS 用 AppAuth ライブラリ
- アプリ向け OAuth: Windows サンプル
前提条件
プロジェクトでAPI を有効にする
Google API を呼び出すアプリケーションは、 API Consoleでこれらの API を有効にする必要があります。
プロジェクトで API を有効にするには:
- Google API Console内のOpen the API Library 。
- If prompted, select a project, or create a new one.
- API Library には、利用可能なすべての API がプロダクト ファミリーと人気度別にグループ化されて一覧表示されます。有効にする API がリストに表示されない場合は、検索を使用して見つけるか、その API が属するプロダクト ファミリーの [すべて表示] をクリックします。
- 有効にする API を選択し、[有効にする] ボタンをクリックします。
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
承認認証情報を作成する
OAuth 2.0 を使用して Google API にアクセスするアプリケーションには、Google の OAuth 2.0 サーバーに対してそのアプリケーションを識別する認証情報が必要です。次の手順では、プロジェクトの認証情報を作成する方法について説明します。アプリケーションはこの認証情報を使用して、そのプロジェクトで有効にした API にアクセスできます。
- Go to the Credentials page.
- [認証情報を作成] > [OAuth クライアント ID] をクリックします。
- 以下のセクションでは、Google の承認サーバーがサポートするクライアントの種類とリダイレクト方法について説明します。アプリケーションに適したクライアント タイプを選択し、OAuth クライアントに名前を付け、フォームの他のフィールドを適切に設定します。
Android
- アプリケーションの種類として [Android] を選択します。
- OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
- Android アプリのパッケージ名を入力します。この値は、アプリ マニフェスト ファイル内の
<manifest>
要素のpackage
属性で定義されています。 - アプリ配信の SHA-1 署名証明書フィンガープリントを入力します。
- アプリで Google Play アプリ署名を使用している場合は、Google Play Console の [アプリ署名] ページから SHA-1 フィンガープリントをコピーします。
- 独自のキーストアと署名鍵を管理する場合は、Java に付属の keytool ユーティリティを使用して、人が読める形式で証明書情報を出力します。keytool 出力の
Certificate fingerprints
セクションにあるSHA1
値をコピーします。詳しくは、Android 用 Google API ドキュメントのクライアントの認証をご覧ください。
- (省略可)Android アプリの所有権を確認します。
- [作成] をクリックします。
iOS
- アプリケーションの種類として [iOS] を選択します。
- OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
- アプリのバンドル ID を入力します。バンドル ID は、アプリの情報プロパティ リストのリソース ファイル(info.plist)に含まれている CFBundleIdentifier キーの値です。この値は、通常、Xcode プロジェクト エディタの [General] ペインまたは [Signing & Capabilities] ペインに表示されます。バンドル ID は、Apple の App Store Connect サイトで、対象アプリの [アプリ情報] ページの [全般情報] セクションにも表示されます。
- (省略可)
アプリが Apple の App Store で公開されている場合は、アプリの App Store ID を入力します。ストア ID は、Apple App Store のすべての URL に含まれる数字文字列です。
- iOS デバイスまたは iPadOS デバイスで Apple App Store アプリを開きます。
- 自分のアプリを探します。
- [共有] ボタン(正方形と上矢印アイコン)を選択します。
- [リンクをコピー] を選択します。
- コピーしたリンクをテキスト エディタに貼り付けます。App Store ID は URL の最後の部分です。
例:
https://apps.apple.com/app/google/id284815942
- (省略可)
チーム ID を入力します。詳細については、Apple Developer Account ドキュメントのチーム ID を確認するをご覧ください。
- [作成] をクリックします。
UWP
- アプリケーションの種類として [ユニバーサル Windows プラットフォーム] を選択します。
- OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
- アプリの 12 文字の Microsoft Store ID を入力します。この値は、[アプリ管理] セクションの [アプリ ID] ページの Microsoft パートナー センターで確認できます。
- [作成] をクリックします。
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 の使用に完全に移行するには、以下の操作を完了する必要があります。
- Google ログイン SDK を使用するようにコードを更新します。
- Google API Console でカスタム スキームのサポートを無効にします。
Google ログイン Android SDK に移行する手順は次のとおりです。
-
Google ログイン Android SDK を使用するようにコードを更新します。
-
コードを調べて、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
パラメータの定義をご覧ください。 -
Google ログイン SDK の設定に必要な
scope
とclient_id
のリクエスト パラメータをメモしておきます。 -
Android アプリへの Google ログインの統合を開始するの手順に沿って SDK をセットアップします。前の手順で取得した
client_id
を再利用するため、バックエンド サーバーの OAuth 2.0 クライアント ID を取得する手順はスキップできます。 -
サーバーサイド API アクセスを有効にするの手順に沿って操作します。手順は次のとおりです。
-
getServerAuthCode
メソッドを使用して、権限をリクエストするスコープの認証コードを取得します。 - 認証コードをアプリのバックエンドに送信して、アクセス トークンおよび更新トークンと交換します。
- 取得したアクセス トークンを使用して、ユーザーの代わりに Google API を呼び出します。
-
-
コードを調べて、Google の OAuth 2.0 サーバーにリクエストを送信する場所を特定します。カスタム スキームを使用する場合、リクエストは次のようになります。
-
Google API Console でカスタム スキームのサポートを無効にします。
- OAuth 2.0 認証情報リストに移動し、Android クライアントを選択します。
- [詳細設定] セクションに移動し、[カスタム URI スキームを有効にする] チェックボックスをオフにし、[保存] をクリックしてカスタム URI スキームのサポートを無効にします。
カスタム URI スキームを有効にする
推奨される代替手段がうまくいかない場合は、次の手順に沿って Android クライアントのカスタム URI スキームを有効にします。- OAuth 2.0 認証情報リストに移動し、Android クライアントを選択します。
- [詳細設定] セクションに移動し、[カスタム URI スキームを有効にする] チェックボックスをオンにして、[保存] をクリックしてカスタム 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 認証の実装を開始する前に、アプリがアクセス権限を必要とするスコープを特定することをおすすめします。
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 ハッシュです。
|
無地 | コード チャレンジは、上記で生成したコード検証ツールと同じ値です。
|
ステップ 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 と一致しない場合、 次の表に、各メソッドの適切な
|
||||||
response_type |
必須
Google OAuth 2.0 エンドポイントが認証コードを返すかどうかを決定します。 インストール済みのアプリのパラメータ値を |
||||||
scope |
必須 ユーザーの代わりにアプリケーションがアクセスできるリソースを識別するスコープのスペース区切りリスト。これらの値により、Google がユーザーに表示する同意画面が決まります。 スコープを使用すると、アプリケーションが必要とするリソースへのアクセス権のみをリクエストできると同時に、ユーザーはアプリケーションに付与するアクセス権の量を制御できます。したがって、リクエストするスコープの数とユーザーの同意を得る可能性には逆相関があります。 |
||||||
code_challenge |
推奨
認証コードの交換時にサーバーサイド チャレンジとして使用する、エンコードされた |
||||||
code_challenge_method |
推奨
認証コードの交換時に使用される |
||||||
state |
推奨
アプリケーションが認可リクエストと認可サーバーのレスポンスの間で状態を維持するために使用する任意の文字列値を指定します。ユーザーがアプリケーションのアクセス リクエストを承諾または拒否すると、サーバーは このパラメータは、ユーザーをアプリ内の適切なリソースに誘導する、ノンスを送信する、クロスサイト リクエスト フォージェリを緩和するなど、さまざまな目的で使用できます。 |
||||||
login_hint |
省略可
認証対象のユーザーをアプリケーションが認識している場合、このパラメータを使用して、Google 認証サーバーにヒントを提供できます。サーバーはこのヒントを使用して、ログイン フォームのメール フィールドに事前入力するか、適切なマルチログイン セッションを選択することで、ログインフローを簡素化します。 パラメータ値をメールアドレスまたは |
認証 URL の例
以下のタブに、さまざまなリダイレクト URI オプション用の承認 URL の例を示します。
redirect_uri
パラメータの値を除き、URL は同じです。この URL には、必須の response_type
パラメータと client_id
パラメータ、オプションの state
パラメータも含まれます。読みやすくするために、各 URL には改行とスペースが含まれています。
カスタム URI スキーム
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
ループバック IP アドレス
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 サーバーからのレスポンスを待機するため、何もする必要はありません。このレスポンスについては、次の手順で説明します。
エラー
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 |
注: このプロパティは、リクエストに openid 、profile 、email などの 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/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 リクエストでは無効な認証情報になります。トークンに関連付けられたスコープへのオフライン アクセスをリクエストした場合、ユーザーに権限を求めることなくアクセス トークンを更新できます(ユーザーが存在しない場合を含む)。
アクセス トークンを更新するには、アプリケーションから 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 は、ここで説明するベスト プラクティスの多くを確立しています。