このドキュメントでは、スマートフォン、タブレット、パソコンなどのデバイスにインストールされたアプリケーションが、Google の OAuth 2.0 エンドポイントを使用して Google API へのアクセスを承認する方法について説明します。
OAuth 2.0 を使用すると、ユーザー名やパスワードなどの情報を非公開にしたまま、特定のデータをアプリケーションと共有できます。たとえば、アプリケーションで OAuth 2.0 を使用して、ユーザーの Google ドライブにファイルを保存する権限を取得できます。
インストール済みのアプリは個々のデバイスに配布され、これらのアプリは Secret を保持できないものと想定されます。ユーザーがアプリを使用しているとき、またはアプリがバックグラウンドで実行されているときに、Google API にアクセスできます。
この承認フローは、ウェブサーバー アプリケーションで使用される承認フローと似ています。主な違いは、インストール済みのアプリは、Google の承認サーバーからのレスポンスを処理するために、システム ブラウザを開いてローカル リダイレクト URI を指定する必要がある点です。
代替方法
モバイルアプリの場合は、Android または iOS で Google ログインを使用することをおすすめします。Google ログイン クライアント ライブラリは、認証とユーザー認証を処理します。これらのライブラリは、ここで説明する下位レベルのプロトコルよりも簡単に実装できます。
システム ブラウザをサポートしていないデバイス、またはテレビ、ゲーム機、カメラ、プリンタなどの入力機能が制限されたデバイス上で実行されるアプリについては、テレビとデバイス用の OAuth 2.0、またはテレビと制限付き入力デバイスでのログインをご覧ください。
ライブラリとサンプル
このドキュメントで説明する OAuth 2.0 フローの実装に役立つ、次のライブラリとサンプルをおすすめします。
- Android 用 AppAuth ライブラリ
- iOS 用 AppAuth ライブラリ
- アプリ向け OAuth: Windows サンプル
Prerequisites
プロジェクトでAPI を有効にする
Google API を呼び出すアプリケーションでは、これらの API を API Consoleで有効にする必要があります。
プロジェクトで API を有効にするには:
- Open the API Library は Google API Consoleにあります。
- 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 クライアントに名前を付け、必要に応じてフォームの他のフィールドを設定します。
カスタム URI スキーム（Android、iOS、UWP）
カスタム URI スキームは、Android アプリ、iOS アプリ、ユニバーサル Windows プラットフォーム（UWP）アプリで推奨されます。
Android
- アプリの種類として [Android] を選択します。
- OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
- Android アプリのパッケージ名を入力します。この値は、アプリ マニフェスト ファイルの
<manifest>要素のpackage属性に定義されています。 - アプリの配布用の SHA-1 署名証明書フィンガープリントを入力します。
- アプリが Google Play アプリ署名を使用している場合は、Play Console の [アプリの署名] ページから SHA-1 フィンガープリントをコピーします。
- 独自のキーストアと署名鍵を管理する場合は、Java に含まれる keytool ユーティリティを使用して、人が読める形式で証明書情報を出力します。keytool 出力の
Certificate fingerprintsセクションのSHA1値をコピーします。詳しくは、Android API 向け Google API ドキュメントのクライアントの認証をご覧ください。
- [作成] をクリックします。
iOS
- アプリケーションの種類として [iOS] を選択します。
- OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
- アプリのバンドル ID を入力します。バンドル ID は、アプリの情報プロパティ リスト リソース ファイル（info.plist）内の CFBundleIdentifier キーの値です。この値は、Xcode プロジェクト エディタの [General] ペインまたは [Signing & Capabilities] ペインに最もよく表示されます。バンドル ID は Apple の App Store Connect サイトにあるアプリの [App Information] ページの [General Information] セクションにも表示されます。
- （省略可）
アプリが Apple の 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 デベロッパー アカウントのドキュメントでチーム ID を確認するをご覧ください。
- [作成] をクリックします。
Uwp
- [Universal Windows Platform] アプリケーション タイプを選択します。
- OAuth クライアントの名前を入力します。この名前は、クライアントを識別するためにプロジェクトの Credentials page に表示されます。
- アプリの 12 文字の Microsoft Store ID を入力しますこの値は Microsoft Partner Center の [アプリの管理] にある [アプリの ID] ページで確認できます。
- [作成] をクリックします。
UWP アプリの場合、カスタム URI スキームは 39 文字以下にする必要があります。
ループバック IP アドレス（macOS、Linux、Windows デスクトップ）
この URL を使用して認証コードを受信するには、アプリケーションがローカル ウェブサーバーでリッスンする必要があります。これは、多くのプラットフォームで可能です。お使いのプラットフォームでサポートされている場合は、認証コードを取得する際にこの方法をおすすめします。
アプリが認証レスポンスを受け取ったら、ブラウザを閉じてアプリに戻るよう指示する HTML ページを表示し、ユーザビリティを最大限に高める必要があります。
| 推奨される使用方法 | macOS、Linux、Windows のデスクトップ アプリ（ユニバーサル Windows プラットフォームを除く） |
| フォームの値 | アプリケーション タイプを [デスクトップ アプリ] に設定します。 |
手動でのコピーして貼り付け
アクセス スコープを特定する
スコープを使用すると、アプリケーションは必要なリソースへのアクセスのみをリクエストでき、ユーザーはアプリケーションに付与するアクセス権をコントロールできます。したがって、リクエストされたスコープの数とユーザーの同意を取得する可能性の間には、逆関係が存在する場合があります。
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] / " -" / " && ;
コード検証ツールは、値を推測するのは現実的でない十分なエントロピーを持っている必要があります。
コードによる確認を行う
コードによる本人確認を作成する 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 ConsoleCredentials 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 認証サーバーにヒントを提供できます。サーバーはヒントを使用して、ログインフォームにメールアドレスのフィールドを事前に入力するか、適切なマルチログイン セッションを選択することにより、ログインフローを簡素化します。 パラメータ値には、ユーザーの Google ID に相当するメールアドレスまたは |
||||||
承認 URL の例
以下のタブには、各リダイレクト URI オプションに対応する認可 URL の例が表示されます。
URL は redirect_uri パラメータの値以外と同じです。この URL には、必須の response_type パラメータと client_id パラメータのほか、オプションの state パラメータも含まれています。各 URL には、読みやすくするために改行とスペースが含まれています。
カスタム URI スキーム
https://accounts.google.com/o/oauth2/v2/auth? scope=& 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=& 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 Workspace 管理者のポリシーにより、リクエストされた 1 つ以上のスコープを Google アカウントが承認できません。管理者が 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 同意画面の設定に関するヘルプ記事のユーザータイプのセクションをご覧ください。
redirect_uri_mismatch
認可リクエストで渡された redirect_uri が、OAuth クライアント ID の承認されたリダイレクト URI と一致しません。 Google API Console Credentials pageで承認済みのリダイレクト URI を確認してください。
渡された redirect_uri は、クライアント タイプに対して無効である可能性があります。
ステップ 4: OAuth 2.0 サーバー レスポンスを処理する
アプリケーションが認証レスポンスを受信する方法は、使用するリダイレクト URI スキームによって異なります。スキームに関係なく、レスポンスには認証コード（code）またはエラー（error）が含まれます。たとえば、error=access_denied はユーザーがリクエストを拒否したことを示します。
ユーザーがアプリケーションにアクセス権を付与した場合は、次のステップで説明するように、認証コードをアクセス トークンと更新トークンに交換できます。
ステップ 5: 更新トークンとアクセス トークンの認証コードを交換する
認証コードをアクセス トークンと交換するには、https://oauth2.googleapis.com/token エンドポイントを呼び出して、次のパラメータを設定します。
| フィールド | |
|---|---|
client_id |
Credentials pageから取得したクライアント ID。 API Console |
client_secret |
Credentials pageから取得したクライアント シークレット。 API Console |
code |
最初のリクエストから返された認証コード。 |
code_verifier |
ステップ 1 で作成したコード ベリファイア。 |
grant_type |
OAuth 2.0 仕様で定義されている場合、このフィールドの値は authorization_code に設定する必要があります。 |
redirect_uri |
指定された client_id の API ConsoleCredentials page 内のプロジェクトのリダイレクト URI の 1 つ。 |
次のスニペットはリクエストの例を示しています。
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%3A//127.0.0.1%3A9004& grant_type=authorization_code
Google は、このリクエストに対して、有効期間が短いアクセス トークンと更新トークンを含む JSON オブジェクトを返します。
レスポンスには、次のフィールドが含まれます。
| フィールド | |
|---|---|
access_token |
Google API リクエストを認可するためにアプリケーションが送信するトークン。 |
expires_in |
アクセス トークンの有効期間（秒）です。 |
id_token |
注: このプロパティは、リクエストに ID スコープ（openid、profile、email など）が含まれている場合にのみ返されます。値は、ユーザーについてデジタル署名された 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 を呼び出す場合など）。
すべての Google API を試して、OAuth 2.0 Playground でスコープを確認できます。
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）に送信します。次のパラメータが含まれています。
| フィールド | |
|---|---|
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 つのユーザー上限があります。更新トークンは長期保存のために保存し、有効な限り継続的に使用する必要があります。アプリケーションが更新トークンが多すぎると、これらの制限に達し、古い更新トークンが機能しなくなります。
トークンの取り消し
場合によっては、ユーザーはアプリケーションに付与されているアクセス権を取り消すこともできます。ユーザーはアカウント設定でアクセス権を取り消すことができます。詳しくは、サードパーティのサイトやアプリのアクセス権を削除するをご覧ください。
また、付与されたアクセスをプログラムによって取り消すこともできます。 ユーザーが登録解除したり、アプリを削除したり、アプリに必要な 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 は、ここで説明する多くのベスト プラクティスを確立しています。