OAuth による Google アカウントのリンク

アカウントは、業界標準の OAuth 2.0 の インプリシット フローと 認可コード フローを使用してリンクされます。

サービスは、OAuth 2.0 準拠の認可エンドポイントと トークン交換 エンドポイントをサポートする必要があります。

暗黙的フローでは、Google がデベロッパーのブラウザで認可エンドポイントを開きます。ログインに成功したら、認可エンドポイントから長期のアクセストークンを Google に返します。このアクセストークンは、Google から送信されるすべてのリクエストに含まれます。

認証コードフローでは、次の 2 つのエンドポイントが必要になります。

認可エンドポイント。ログインしていないユーザーにログイン用の UI を表示します。認可エンドポイントは、リクエストされたアクセスに対するユーザーの同意を記録するために、有効期間の短い認可コードも作成します。
トークン交換エンドポイント。次の 2 種類の交換を行います。
1. 長期の更新トークンと短期のアクセストークンの認可コードを交換します。この処理は、ユーザーがアカウントのリンクフローを行ったときに発生します。
2. 長期の更新トークンを短期のアクセストークンと交換します。この処理は、トークンが期限切れになり、新しいアクセストークンが必要になった場合に発生します。

OAuth 2.0 フローを選択する

暗黙的フローの実装は簡単ですが、暗黙的フローによって発行されたアクセストークンには有効期限を設定しないことをおすすめします。これは、暗黙的フローでトークンが期限切れになると、ユーザーがアカウントを再度リンクしなければならないためです。セキュリティ上の理由からトークンに有効期限を設定する必要がある場合は、代わりに認可コードフローを使用することを強くおすすめします。

設計ガイドライン

このセクションでは、OAuth リンクフロー用にホストするユーザー画面の設計要件と推奨事項について説明します。Google のアプリから呼び出されると、プラットフォームはユーザーに Google にログインするページとアカウントのリンクに関する同意画面を表示します。アカウントのリンクに同意すると、ユーザーは Google のアプリに戻されます。

この図は、ユーザーが自身の Google アカウントをデベロッパーの認証システムにリンクする手順を示しています。最初のスクリーンショットは、プラットフォームからユーザーが開始するリンクを示しています。2 つ目の画像は Google へのユーザーのログインを示しています。3 つ目の画像は、Google アカウントとアプリをリンクすることに対するユーザーの同意と確認を示しています。最後のスクリーンショットは、Google アプリでユーザーアカウントが正常にリンクされた状態を示しています。 — **図 1.** アカウントリンクのユーザーが Google にログインする画面と同意画面。

要件

ユーザーのアカウントは、Google Home や Google アシスタントなどの特定の Google プロダクトではなく、Google にリンクされることを伝える必要があります。

推奨事項

次のことをおすすめします。

Google のプライバシーポリシーを表示する。同意画面に Google のプライバシーポリシーへのリンクを含めます。
共有するデータ。明確で簡潔な表現を使用して、Google に必要なデータとその理由をユーザーに伝えます。
行動を促す明確なフレーズ同意画面に「同意してリンク」など、わかりやすい行動を促すフレーズを表示します。これは、アカウントをリンクするために Google と共有する必要があるデータをユーザーが理解する必要があるためです。
キャンセルできること。ユーザーがリンクしないことを選択した場合に、ユーザーが戻るまたはキャンセルできる方法を提供します。
ログインプロセスを明確にする。ユーザーが Google アカウントにログインするための明確な方法（ユーザー名とパスワードのフィールド、Google でログインなど）があることを確認します。
リンクを解除できること。ユーザーがリンクを解除するためのメカニズム（プラットフォームのアカウント設定への URL など）を提供します。または、ユーザーがリンクされたアカウントを管理できる Google アカウントへのリンクを含めることもできます。
ユーザーアカウントを変更する機能。ユーザーがアカウントを切り替える方法を提案します。これは、ユーザーが複数のアカウントを持っている場合に特に便利です。
- ユーザーがアカウントを切り替えるために同意画面を閉じる必要がある場合は、回復可能なエラーを Google に送信して、ユーザーが OAuth リンクと暗黙的フローを使用して目的のアカウントにログインできるようにします。
ロゴを含めます。同意画面に会社のロゴを表示します。スタイルガイドラインに沿ってロゴを配置します。Google のロゴも表示する場合は、ロゴと商標をご覧ください。

プロジェクトを作成する

アカウントリンクを使用するプロジェクトを作成するには:

Google API コンソールに移動します。
[プロジェクトの作成] をクリックします。
名前を入力するか、生成された候補を受け入れます。
残りのフィールドを確認または編集します。
[作成] をクリックします。

プロジェクト ID を表示するには:

Google API コンソールに移動します。
ランディングページの表でプロジェクトを探します。プロジェクト ID は [ID] 列に表示されます。

OAuth 同意画面を構成する

Google アカウントのリンクプロセスには同意画面が含まれています。この画面では、データへのアクセスをリクエストしているアプリケーション、リクエストしているデータの種類、適用される規約がユーザーに通知されます。Google API クライアント ID を生成する前に、OAuth 同意画面を構成する必要があります。

Google API コンソールの OAuth 同意画面ページを開きます。
プロンプトが表示されたら、作成したプロジェクトを選択します。
[OAuth 同意画面] ページでフォームに入力し、[保存] ボタンをクリックします。

アプリケーション名: 同意を求めるアプリケーションの名前。名前はアプリケーションを正確に反映し、ユーザーが他の場所で見るアプリケーション名と一致している必要があります。アプリケーション名は、アカウントリンクの同意画面に表示されます。

アプリケーションロゴ: 同意画面に表示される画像で、ユーザーがアプリを認識しやすくなります。ロゴは、アカウントリンクの同意画面とアカウント設定に表示されます。

サポートメール: 同意に関して問い合わせる際に使用します。

Google API のスコープ: スコープを使用すると、アプリケーションはユーザーの非公開の Google データにアクセスできます。Google アカウントのリンクのユースケースでは、デフォルトのスコープ（email、profile、openid）で十分です。機密性の高いスコープを追加する必要はありません。一般的に、スコープは事前にリクエストするのではなく、アクセスが必要になったときに段階的にリクエストすることが効果的な手法です。詳細

承認済みドメイン: デベロッパーとユーザーを保護するために、Google では、OAuth を使用して認証するアプリケーションのみに承認済みドメインの使用を許可しています。アプリケーションのリンクは、承認済みドメインでホストする必要があります。詳細

アプリケーションのホームページへのリンク: アプリケーションのホームページ。承認済みドメインでホストする必要があります。

アプリケーションのプライバシーポリシーへのリンク: Google アカウントリンクの同意画面に表示されます。承認済みドメインでホストする必要があります。

アプリケーションの利用規約へのリンク（省略可）: 承認済みドメインでホストする必要があります。

図 1. 架空のアプリケーション Tunery の Google アカウントのリンクの同意画面
[検証ステータス] を確認します。アプリケーションの検証が必要な場合は、[検証のために送信] ボタンを**クリック**して、検証を受けるためにアプリケーションを送信します。詳しくは、OAuth の検証要件をご覧ください。

OAuth サーバーを実装する

認可コードフローの OAuth 2.0 サーバーは 2 つのエンドポイントで構成されます。これらのエンドポイントには HTTPS 経由でアクセスできます。最初のエンドポイントは認可エンドポイントで、これはデータアクセスに対するユーザーの同意を検索または取得する処理を担当します。認可エンドポイントは、ログインしていないユーザーにログイン用の UI を表示し、リクエストされたアクセスへの同意を記録します。2 つ目のエンドポイントはトークン交換エンドポイントで、トークンという暗号化された文字列を取得し、ユーザーにサービスへのアクセスを許可します。

Google アプリケーションでサービスの API を呼び出す必要がある場合、Google はこれらのエンドポイントを使用して、API の呼び出し許可をユーザーから取得します。

Google アカウントのリンク: OAuth 認可コードフロー

次のシーケンス図は、ユーザー、Google、サービスの各エンドポイント間のインタラクションの詳細を示しています。

図 1. Google アカウントのリンクの OAuth 2.0 認可コードフローのイベントのシーケンス。

役割と責任

次の表に、Google アカウントのリンク（GAL）OAuth フローにおけるアクターの役割と責任を定義します。GAL では、Google は OAuth クライアントとして機能し、サービスはID/サービスプロバイダとして機能します。

アクター / コンポーネント	GAL ロール	責任
Google アプリ / サーバー	OAuth クライアント	フローを開始し、認証コードを受け取り、トークンと交換して、サービス API にアクセスするために安全に保存します。
認可エンドポイント	認可サーバー	ユーザーを認証し、Google とのデータへのアクセス権の共有についてユーザーの同意を得ます。
トークン交換エンドポイント	認可サーバー	認証コードと更新トークンを検証し、Google サーバーにアクセストークンを発行します。
Google リダイレクト URI	コールバックエンドポイント	`code` 値と `state` 値を含むユーザーリダイレクトを承認サービスから受信します。

Google が開始する OAuth 2.0 認可コードフローのセッションは次のような流れになります。

Google がユーザーのブラウザで認可エンドポイントを開きます。アクションのフローが音声専用デバイスで開始した場合、Google は実行をスマートフォンに転送します。
ユーザーがログインし（ログインしていない場合）、Google が API を使用してデータにアクセスすることを承諾します（まだ許可していない場合）。
サービスが認証コードを作成し、Google に返します。そのためには、認証コードをリクエストに付加して、ユーザーのブラウザを Google にリダイレクトします。
Google が認証コードをトークン交換エンドポイントに送信します。トークン交換エンドポイントはコードの真正性を検証し、アクセストークンと更新トークンを返します。アクセストークンは、API にアクセスするための認証情報としてサービスが受け入れる有効期間の短いトークンです。更新トークンは長期のトークンで、Google が保存してアクセストークンが期限切れになったときに新しいトークンを取得するために使用できます。
ユーザーがアカウントリンクフローを完了すると、それ以降 Google から送信されるすべてのリクエストにアクセストークンが含まれます。

認可リクエストの処理

OAuth 2.0 認可コードフローを使用してアカウントリンクを行う必要がある場合、Google は、次のパラメータを含むリクエストを使用して、ユーザーを認可エンドポイントに送信します。

認可エンドポイントのパラメータ
`client_id`	Google に割り当てたクライアント ID。
`redirect_uri`	このリクエストに対するレスポンスを送信する宛先 URL。
`state`	リダイレクト URL で変更されずに Google に返される会計上の値。
`scope`	省略可: Google が許可を求めているデータ範囲を表す、スペースで区切られた文字列。
`response_type`	レスポンスで返される値のタイプ。OAuth 2.0 認可コードフローの場合、レスポンスタイプは常に `code` です。
`user_locale`	RFC5646 形式の Google アカウントの言語設定。ユーザーの優先言語でコンテンツをローカライズするために使用されます。

たとえば、認可エンドポイントが https://myservice.example.com/auth の場合、リクエストは次のようになります。

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

認可エンドポイントでログインリクエストを処理する場合は、次の手順に従います。

client_id が Google に割り当てたクライアント ID と一致し、redirect_uri が Google からサービスに提供されたリダイレクト URL と一致することを確認します。これにより、意図しないクライアントアプリや誤って構成されたクライアントアプリによるアクセスを防ぐことができるため、このチェックは重要です。複数の OAuth 2.0 フローをサポートしている場合は、response_type が code であることも確認してください。
ユーザーがサービスにログインしているかどうか確認します。ユーザーがログインしていない場合は、サービスのログインまたは登録フローを完了します。
Google が API にアクセスする際に使用する認証コードを生成します。認証コードには任意の文字列値を使用できますが、ユーザー、そのトークンの対象となるクライアント、コードの有効期限を一意に表し、なおかつ簡単に推測できないものにする必要があります。通常、約 10 分後に期限切れになる認可コードを発行します。

redirect_uri パラメータで指定された URL が次の形式になっていることを確認します。

  https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

redirect_uri パラメータで指定された URL にユーザーのブラウザをリダイレクトします。code パラメータと state パラメータを追加してリダイレクトする場合は、生成された認証コードと元の未変更の state 値を含めます。結果の URL は次のようになります。
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
```

トークン交換リクエストの処理

サービスのトークン交換エンドポイントは、次の 2 種類のトークン交換を処理します。

認可コードとアクセストークンおよび更新トークンとの交換
更新トークンとアクセストークンの交換

トークン交換リクエストには、次のパラメータを使用します。

トークン交換エンドポイントのパラメータ
`client_id`	リクエスト元を Google として識別する文字列。この文字列は、Google の一意の識別子としてシステムに登録されている必要があります。
`client_secret`	Google に登録したサービスのシークレット文字列。
`grant_type`	交換されるトークンの種類。`authorization_code` または `refresh_token` のいずれかです。
`code`	`grant_type=authorization_code` の場合、このパラメータは、Google がログインまたはトークン交換エンドポイントから受け取ったコードです。
`redirect_uri`	`grant_type=authorization_code` の場合、このパラメータは最初の認可リクエストで使用される URL です。
`refresh_token`	`grant_type=refresh_token` の場合、このパラメータは Google がトークン交換エンドポイントから受け取った更新トークンです。

認可コードとアクセストークンおよび更新トークンとの交換

ユーザーがログインして認可エンドポイントが短期の認証コードを Google に返すと、Google がリクエストをトークン交換エンドポイントに送信し、アクセストークンと更新トークンの認証コードを交換します。

このリクエストの場合、grant_type の値は authorization_code で、code の値は以前に Google に付与した認証コードの値になります。認可コードをアクセストークンと更新トークンに交換するリクエストの例を次に示します。

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

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

アクセストークンと更新トークンの認可コードを交換するため、トークン交換エンドポイントは次の手順に従って POST リクエストに応答します。

client_id によってリクエスト元が認証済みオリジンであること確認し、client_secret が期待値と一致していることを確認します。
認証コードが有効で、期限が切れていないことを確認します。さらに、リクエストで指定されたクライアント ID が、認証コードに関連付けられたクライアント ID と一致することを確認します。
redirect_uri パラメータで指定された URL が、最初の認可リクエストで使用された値と同じであることを確認します。
上記の条件のすべて満たしていない場合、本文で HTTP 400 Bad Request エラーと {"error": "invalid_grant"} を返します。
それ以外の場合は、認証コードのユーザー ID を使用して、更新トークンとアクセストークンを生成します。これらのトークンには任意の文字列値を使用できますが、ユーザーとそのトークンの対象となるクライアントを一意に表し、なおかつ簡単には推測できないものにする必要があります。アクセストークンには、トークンの有効期限（通常はトークンを発行してから 1 時間）も記録します。更新トークンに有効期限はありません。

HTTPS レスポンスの本文で次の JSON オブジェクトを返します。

{
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

Google は、ユーザーのアクセストークンと更新トークンを保存し、アクセストークンの有効期限を記録します。アクセストークンの有効期限が切れると、Google は更新トークンを使用してトークン交換エンドポイントから新しいアクセストークンを取得します。

更新トークンとアクセストークンの交換

アクセストークンの有効期限が切れると、Google はトークン交換エンドポイントにリクエストを送信し、更新トークンと新しいアクセストークンを交換します。

このリクエストの場合、grant_type の値は refresh_token で、refresh_token の値は以前に Google に付与した更新トークンの値になります。更新トークンをアクセストークンと交換するリクエストの例を次に示します。

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

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

更新トークンをアクセストークンと交換するため、トークン交換エンドポイントは次のステップを実行してPOST リクエストに応答します。

client_id がリクエスト元を Google として識別し、client_secret が期待値と一致していることを確認します。
更新トークンが有効で、リクエストで指定されたクライアント ID が更新に関連付けられたクライアント ID と一致していることを確認します。
上記の条件のすべて満たしていない場合、本文で HTTP 400 Bad Request エラーと {"error": "invalid_grant"} を返します。
それ以外の場合は、更新トークンのユーザー ID を使用してアクセストークンを生成します。これらのトークンには任意の文字列値を使用できますが、ユーザーとそのトークンの対象となるクライアントを一意に表し、なおかつ簡単には推測できないものにする必要があります。アクセストークンには、トークンの有効期限（通常はトークンを発行してから 1 時間）も記録します。

HTTPS レスポンスの本文で次の JSON オブジェクトを返します。

{
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

userinfo リクエストを処理する

userinfo エンドポイントは、OAuth 2.0 で保護されたリソースで、リンクされたユーザーに関するクレームを返します。userinfo エンドポイントの実装とホストは任意ですが、以下のユースケースを除きます。

Google One タップによるリンクされたアカウントへのログイン。
Android TV のスムーズな定期購入。

トークンエンドポイントからアクセストークンが正常に取得されると、Google は、リンクされたユーザーに関する基本的なプロフィール情報を取得するためのリクエストを userinfo エンドポイントに送信します。

userinfo エンドポイントリクエストヘッダー
`Authorization header`	Bearer タイプのアクセストークン。

たとえば、userinfo エンドポイントが https://myservice.example.com/userinfo の場合、リクエストは次のようになります。

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

userinfo エンドポイントでリクエストを処理するには、次の手順を行います。

Authorization ヘッダーからアクセストークンを抽出し、そのアクセストークンに関連付けられたユーザーの情報を返します。
アクセストークンが無効な場合は、WWW-Authenticate レスポンスヘッダーを使用して HTTP 401 Unauthorized エラーを返します。userinfo エラーレスポンスの例を次に示します。
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
リンク処理中に 401 Unauthorized またはその他の失敗したエラーレスポンスが返された場合、そのエラーは修復不能となり、取得したトークンは破棄されるため、ユーザーはリンク処理をやり直す必要があります。

アクセストークンが有効な場合は、HTTPS の本文に次の JSON オブジェクトを含む HTTP 200 レスポンスを返します。レスポンス:

{
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}

userinfo エンドポイントが HTTP 200 成功レスポンスを返すと、取得したトークンとクレームがユーザーの Google アカウントに登録されます。

userinfo エンドポイントレスポンス
`sub`	システム内でユーザーを識別する一意の ID。
`email`	ユーザーのメールアドレス。
`given_name`	省略可: ユーザーの名。
`family_name`	省略可: ユーザーの姓。
`name`	省略可: ユーザーの氏名。
`picture`	省略可: ユーザーのプロフィール写真。

実装の検証

OAuth 2.0 Playground ツールを使用して、実装を検証できます。

このツールで、次の手順を行います。

[構成] 設定をクリックして、[OAuth 2.0 構成] ウィンドウを開きます。
[OAuth flow] フィールドで、[クライアントサイド] を選択します。
[OAuth Endpoints] フィールドで、[Custom] を選択します。
対応するフィールドに、OAuth 2.0 エンドポイントと Google に割り当てたクライアント ID を指定します。
[Step 1] セクションで、Google スコープを選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーで有効なスコープを入力します（OAuth スコープを使用しない場合は任意の文字列を入力します）。完了したら、[Authorize APIs] をクリックします。
[Step 2] セクションと [Step 3] セクションで、OAuth 2.0 フローを確認し、各ステップが意図したとおりに動作することを確認します。

Google アカウントリンクデモツールを使用して、実装を検証できます。