アカウントは、業界標準の OAuth 2.0 インプリシット フローと認可コードフローを使用してリンクされます。サービスは、OAuth 2.0 準拠の認可エンドポイントとトークン交換エンドポイントをサポートする必要があります。
在隐式流程中，Google 会在用户的浏览器中打开您的授权端点。成功登录后，您将向 Google 返回一个长期访问令牌。现在，此访问令牌会包含在 Google 发送的每个请求中。
在授权代码流程中，您需要两个端点：
授权端点，用于向尚未登录的用户显示登录界面。授权端点还会创建一个短期授权代码，以记录用户对所请求访问权限的同意情况。
令牌交换端点，负责两种类型的交换：
- 使用授权代码换取长期有效的刷新令牌和短期有效的访问令牌。当用户完成账号关联流程时，就会发生此交换。
- 将长期有效的刷新令牌换成短期有效的访问令牌。当 Google 需要新的访问令牌（因为现有访问令牌已过期）时，就会发生这种交换。
选择 OAuth 2.0 流程
虽然隐式流程更易于实现，但 Google 建议通过隐式流程签发的访问令牌永不过期。这是因为，在隐式流程中，令牌过期后，系统会强制用户重新关联其账号。如果您出于安全考虑需要令牌过期，我们强烈建议您改用授权码流程。
设计准则
本部分介绍了您为 OAuth 关联流程托管的用户屏幕的设计要求和建议。在 Google 应用调用该 API 后，您的平台会向用户显示登录 Google 页面和账号关联意见征求界面。同意关联账号后，系统会将用户重定向回 Google 的应用。
要求
- 您必须说明用户的账号将与 Google 相关联，而非 Google Home 或 Google 助理等特定 Google 产品相关联。
建议
建议您执行以下操作：
显示 Google 的隐私权政策。在同意屏幕上添加指向 Google 隐私权政策的链接。
要共享的数据。使用清晰简洁的语言告知用户 Google 需要哪些用户数据以及原因。
添加醒目的号召性用语。在用户同意页面上提供明确的号召性用语，例如“同意并关联”。这是因为用户需要了解他们需要与 Google 分享哪些数据才能关联账号。
可以取消。为用户提供返回或取消链接的途径，如果用户选择不进行关联。
明确的登录流程。确保用户有明确的 Google 账号登录方法，例如用户名和密码字段或使用 Google 账号登录。
能够解除关联。提供一种可让用户解除关联的机制，例如指向您平台上账号设置的网址。或者，您也可以添加指向 Google 账号的链接，以便用户管理其关联的账号。
能够更改用户账号。建议用户切换账号的方法。如果用户通常拥有多个账号，这种做法尤为有益。
- 如果用户必须关闭意见征求界面才能切换账号，请向 Google 发送可恢复的错误，以便用户可以使用 OAuth 关联和隐式流程登录所需的账号。
添加您的徽标。在意见征求页面上显示您的公司徽标。 按照您的样式准则放置徽标。如果您还想显示 Google 的徽标，请参阅徽标和商标。
プロジェクトを作成する
アカウントのリンクを使用するプロジェクトを作成するには:
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 2.0 認可コードフロー セッションには、 できます。
- Google がユーザーのブラウザで認可エンドポイントを開きます。フローが 音声のみのデバイスで開始された場合、Google は ダウンロードします
- ユーザーがログインし（まだログインしていない場合）、Google に次の権限を与える API を使用してデータにアクセスする必要があります（まだ権限を付与していない場合）。
- サービスによって認証コードが作成され、Google に返されます。タスク そのため、認証コードを使用してユーザーのブラウザを Google にリダイレクトします。 リクエストに添付されます
- Google がトークン交換エンドポイントに認証コードを送信します。 コードの真正性を検証し、アクセス トークンと 更新トークン。アクセス トークンは有効期間の短いトークンであり、サービス を受け入れて、API にアクセスするための認証情報です。更新トークンは有効期間が長い トークンを保存し、新しいアクセス トークンを取得するために Google が使用 期限が切れます。
- ユーザーがアカウントのリンクのフローを完了すると、それ以降は リクエストにはアクセス トークンが含まれています。
認可リクエストの処理
OAuth 2.0 認証コードを使用してアカウント リンクを行う必要がある場合 リクエストが送信されると、Google はユーザーを認可エンドポイントに送信します。 次のパラメータが含まれます。
| 認可エンドポイントのパラメータ | |
|---|---|
client_id |
Google に割り当てたクライアント ID。 |
redirect_uri |
このリクエストに対するレスポンスを送信する宛先 URL。 |
state |
リダイレクト URL で変更されずに Google に返される会計上の値。 |
scope |
省略可: スコープ文字列をスペースで区切って指定します。 許可を求めているデータです。 |
response_type |
レスポンスで返される値のタイプ。OAuth 2.0 では、
認可コードフローでは、レスポンス タイプは常に code です。
|
user_locale |
Google アカウントの言語設定 RFC5646 形式を使用して、コンテンツをユーザーの好みの言語にローカライズできます。 |
たとえば、認可エンドポイントが
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パラメータ。その際、認証コードを リダイレクトしたときに、変更されていない元の状態値がcodeパラメータとstateパラメータを追加します。以下は、 次のようになります。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 を
本文が
{"error": "invalid_grant"}の 400 Bad Request エラー。 - それ以外の場合は、認証コードのユーザー 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 を返します。
{"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 ツールを使用します。
ツールで、次の操作を行います。
- [Configuration] をクリックして [OAuth 2.0 Configuration] ウィンドウを開きます。
- [OAuth flow] フィールドで、[Client-side] を選択します。
- [OAuth Endpoints]（OAuth エンドポイント）で、[Custom]（カスタム）を選択します。
- 対応するフィールドに、OAuth 2.0 エンドポイントと Google に割り当てたクライアント ID を指定します。
- [ステップ 1] セクションで、Google スコープは選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーで有効なスコープを入力します（OAuth スコープを使用しない場合は任意の文字列を入力します）。完了したら、[API を承認] をクリックします。
- ステップ 2 とステップ 3 のセクションで OAuth 2.0 フローを実行し、各ステップが意図したとおりに機能することを確認します。
実装を検証するには、Google アカウント リンクのデモツールを使用します。
ツールで次の操作を行います。
- [Google でログイン] ボタンをクリックします。
- リンクするアカウントを選択します。
- サービス ID を入力します。
- 必要に応じて、アクセスをリクエストするスコープを 1 つ以上入力します。
- [デモを開始] をクリックします。
- リンク リクエストに同意できることを確認して、リクエストを拒否します。
- プラットフォームにリダイレクトされることを確認します。