iOS およびデスクトップ アプリ用 OAuth 2.0

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

OAuth 2.0 では、ユーザー名やパスワードなどの情報を秘密にしたまま、ユーザーが特定のデータをアプリケーションと共有できます。たとえば、アプリケーションは OAuth 2.0 を使用して、Google ドライブにファイルを保存する権限をユーザーから取得できます。

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

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

ライブラリとサンプル

iOS アプリの場合は、最新バージョンの Sign In With Google iOS SDK を使用することをおすすめします。SDK はユーザー認証を処理するため、このガイドで説明する下位レベルのプロトコルよりも簡単に実装できます。

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

前提条件

プロジェクトでAPI を有効にする

Google API を呼び出すアプリケーションは、API Console でそれらの API を有効にする必要があります。

プロジェクトで API を有効にするには:

1. Google API Console で API ライブラリを開きます。
2. プロンプトが表示されたら、プロジェクトのいずれかを選択するか、新しいプロジェクトを作成します。
3. API ライブラリには、利用可能なすべての API がプロダクト ファミリーと人気度に応じてグループ化されて表示されます。有効にする API がリストで見当たらない場合は、検索して見つけるか、その API が属するプロダクト ファミリーの [すべて表示] をクリックします。
4. 有効にする API を選択し、[有効にする] ボタンをクリックします。
5. プロンプトが表示されたら、請求機能を有効にします。
6. プロンプトが表示されたら、API の利用規約を確認し、同意します。

承認認証情報を作成する

OAuth 2.0 を使用して Google API にアクセスするアプリケーションには、Google の OAuth 2.0 サーバーにアプリケーションを識別させる認証情報が必要です。次の手順では、プロジェクトの認証情報を作成する方法について説明します。アプリケーションは、この認証情報を使用して、そのプロジェクトで有効にした API にアクセスできます。

1. [クライアント] ページに移動します。
2. [クライアントの作成] をクリックします。
3. 以降のセクションでは、Google の認可サーバーがサポートするクライアント タイプについて説明します。アプリケーションに推奨されるクライアント タイプを選択し、OAuth クライアントに名前を付けて、フォームの他のフィールドを適切に設定します。

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

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

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 つあります。

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=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

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 は同意ウィンドウを表示します。このウィンドウには、アプリケーションの名前、ユーザーの認証情報を使用してアクセス許可をリクエストしている Google API サービス、付与されるアクセス スコープの概要が表示されます。ユーザーは、アプリケーションからリクエストされた 1 つ以上のスコープへのアクセス権の付与に同意するか、リクエストを拒否できます。

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

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

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

ユーザーがアプリケーションにアクセスを許可すると、次のステップで説明するように、認証コードをアクセス トークンおよび更新トークンと交換できます。

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

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

DPoP の使用は任意ですが、セキュリティを強化するため、使用することをおすすめします。DPoP のセキュリティは、秘密鍵が 1 台のデバイスに制限されていることに依存しています。TPM、Secure Enclave、その他のハードウェア格納型キーストアなどを使用して、デバイス外にコピーできない方法で保存することをおすすめします。DPoP を使用するには、アプリケーションがトークン エンドポイントへのリクエストごとに新しい一意の DPoP 証明 JWT を生成し、HTTP リクエスト ヘッダーとして追加する必要があります。

次のスニペットは、リクエストの例を示しています。

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

DPoP 証明を作成する

次の手順では、コマンドラインから OpenSSL を使用して DPoP 証明を作成する方法について説明します。

1. EC P-256 鍵ペアを生成します。

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. DPoP ヘッダーを作成します。

   ヘッダーには、typ、alg、jwk（公開鍵）のクレームを含める必要があります。x と y の値は、EC 公開鍵の Base64Url でエンコードされた座標です。この JSON を Base64Url エンコードします。

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. DPoP ペイロードを作成する:

   ペイロードには、jti（リクエストの固有識別子）、htm（HTTP メソッド、例: POST）、htu（HTTP URI、例: https://oauth2.googleapis.com/token）、iat（発行時刻）を含める必要があります。前のリクエストに対するレスポンスの DPoP-Nonce ヘッダーでサーバーからノンスを受け取った場合は、そのノンス値を nonce クレームに含める必要があります。nonce クレームは、認証コード交換では省略可能であり、以前に DPoP-Nonce ヘッダーを受信した場合にのみ使用されます。この JSON を Base64Url エンコードします。

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   jti の値は、エクスチェンジのタイプによって異なります。

   • 認証コード交換の場合、jti は認証コードの Base64Url エンコードされた SHA256 ハッシュ（"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))"）である必要があります。
   • 更新トークンの交換の場合、jti はリクエストごとに一意の識別子（"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER"）にする必要があります。
4. 証明に署名する:

   エンコードされたヘッダーとペイロードをピリオド（.）で連結し、ES256 を使用して秘密鍵で結果に署名します。JWS では、署名が未加工の R | S 連結形式（P-256 の場合は 64 バイト）である必要があります。OpenSSL を直接使用する場合は、デフォルトの ASN.1 DER エンコード署名をこの未加工形式に変換する必要があります。

交換が成功すると、トークンを含む 200 OK レスポンスが返されます。交換時に有効な DPoP 署名が使用された場合、Google から返される更新トークンは鍵に DPoP バインドされますが、アクセス トークンは DPoP バインドされません。アクセス トークンは、DPoP ではなく Bearer の token_type を保持します。また、Google はレスポンスで DPoP-Nonce HTTP ヘッダーを返します。 クライアントは、このノンスをキャッシュに保存し、後続のリクエスト（更新トークンを新しいアクセス トークンと交換する場合や、DPoP で保護された API を呼び出す場合など）で DPoP 証明の nonce クレームに含める必要があります。この早期発行のノンスを使用すると、次のリクエストで余分な往復エラー（use_dpop_nonce）を回避できます。

DPoP バインド更新トークンを使用して行われたトークン交換リクエストには、DPoP 認証を含める必要があります。

DPoP ヘッダーが想定どおりに存在しない場合、無効な場合、または証明がトークンにバインドされている鍵とは異なる鍵を使用している場合、交換は失敗します。このような場合、サーバーは 400 Bad Request エラーを返します。DPoP 証明に一致しない htm クレームまたは htu クレーム、期限切れの iat、再利用された jti、または無効な署名がある場合、Google は invalid_dpop_proof エラーコードを返します。更新トークンの交換時など、DPoP ノンスが必要な場合に、DPoP 証明に nonce クレームがないか、ノンス値がサーバーで受け入れられない（期限切れ、すでに使用されている、正しくないなど）場合、Google は use_dpop_nonce エラーコードを返します。また、後続のリクエストで使用できる新しいノンスを含む DPoP-Nonce HTTP ヘッダーも返します。その他のエラーでは invalid_grant が返されることがあります。

Google は、有効期間の短いアクセス トークンと更新トークンを含む JSON オブジェクトを返すことで、このリクエストに応答します。

レスポンスには、次のフィールドが含まれます。

次のスニペットは、DPoP が使用されている場合の成功したレスポンス ヘッダーと本文の例を示しています。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

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

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

複数の権限（スコープ）をリクエストした場合、ユーザーがアプリにすべての権限へのアクセスを許可しないことがあります。アプリは、実際に付与されたスコープを確認し、一部の権限が拒否された状況を適切に処理する必要があります。通常は、拒否されたスコープに依存する機能を無効にします。

例外もございます。ドメイン全体の権限の委任が設定されている Google Workspace Enterprise アプリ、または信頼できるとしてマークされているアプリでは、詳細な権限の同意画面が省略されます。これらのアプリでは、詳細な権限の同意画面は表示されません。代わりに、アプリはリクエストされたすべてのスコープを受け取るか、まったく受け取らないかのいずれかになります。

詳細については、詳細な権限を処理する方法をご覧ください。

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

たとえば、次のアクセス トークン レスポンスの例は、ユーザーがアプリケーションに読み取り専用のドライブ アクティビティとカレンダーの予定の権限へのアクセスを許可したことを示しています。

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.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 リクエストを送信します。このリクエストの本文には、次のパラメータが含まれます。

DPoP の使用は任意ですが、セキュリティを強化するため、使用することをおすすめします。更新トークンで DPoP を使用するには、アプリケーションはトークン エンドポイントへのリクエストごとに、新しい一意の DPoP 証明 JWT を生成する必要があります。この証明は、最初の認証コード交換で使用されたものと同じ秘密鍵で署名する必要があります。アプリケーションは、証明を HTTP リクエスト ヘッダーとして追加します。

次のスニペットは、リクエストの例を示しています。

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: DPOP_PROOF_JWT

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

更新トークンで DPoP を使用するには、リクエストに新しい一意の DPoP 証明 JWT を生成する必要があります。鍵ペアの生成と JWT の作成の手順については、DPoP 証明を作成するをご覧ください。

交換が成功すると、新しいアクセス トークンを含む 200 OK レスポンスが返されます。DPoP を使用する場合、token_type は Bearer です。成功レスポンスは、更新トークンの DPoP 証明が承認されたことを確認します。Google は、レスポンスで新しい DPoP-Nonce HTTP ヘッダーを返すこともあります。返された場合、クライアントはこのノンスをキャッシュに保存し、後続のリクエストの DPoP 証明の nonce クレームに含める必要があります。

DPoP ヘッダーがない、無効である、または間違った鍵を使用している場合、交換に失敗します。特定の DPoP エラーコードとノンスの処理の詳細については、交換の失敗をご覧ください。

次のスニペットは、DPoP が使用されている場合の成功したレスポンス ヘッダーと本文の例を示しています。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

発行される更新トークンの数には上限があります。クライアントとユーザーの組み合わせごとに 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 がエラーコードとともに返されます。

アプリのリダイレクト方法

アプリを保護する

時間ベースのアクセス

時間ベースのアクセスでは、ユーザーはアプリにデータへのアクセスを期間限定で許可して、アクションを完了できます。時間ベースのアクセスは、同意フロー中に一部の Google サービスで利用できます。これにより、ユーザーは一定期間アクセスを許可するオプションを選択できます。たとえば、 Data Portability API を使用すると、データを 1 回限り転送できます。

ユーザーがアプリケーションに時間ベースのアクセスを許可すると、指定された期間が経過した後に更新トークンが期限切れになります。更新トークンは、特定の状況下ではより早く無効になる場合があります。詳しくは、こちらのケースをご覧ください。このような場合、認可コード交換レスポンスで返される refresh_token_expires_in フィールドは、更新トークンの有効期限が切れるまでの残り時間を表します。

関連情報

IETF の現在のベスト プラクティスである OAuth 2.0 for ネイティブ アプリ には、ここで説明するベスト プラクティスの多くが記載されています。