アカウントは、業界標準の OAuth 2.0 の暗黙的フローと認証コードフローを使用してリンクされます。サービスが OAuth 2.0 準拠の承認とトークン交換のエンドポイントをサポートしている必要があります。
暗黙的フローでは、Google がユーザーのブラウザで認証エンドポイントを開きます。ログインに成功すると、Google に有効期間の長いアクセス トークンが返されます。このアクセス トークンは、Google から送信されるすべてのリクエストに含まれるようになりました。
認証コードフローでは、2 つのエンドポイントが必要です。
認証エンドポイント。まだログインしていないユーザーにログイン UI を表示します。認証エンドポイントは、リクエストされたアクセスへのユーザーの同意を記録するための有効期間の短い認証コードも作成します。
トークン交換エンドポイント。次の 2 種類の交換を行います。
- 長期の更新トークンと短期のアクセス トークンの認可コードを交換します。このやり取りは、ユーザーがアカウントのリンクのフローを行ったときに行われます。
- 有効期間が長い更新トークンと有効期間の短いアクセス トークンを交換します。この交換は、トークンが期限切れであるために Google が新しいアクセス トークンを必要とする場合に発生します。
OAuth 2.0 フローの選択
暗黙的フローは実装が簡単ですが、暗黙的フローによって発行されたアクセス トークンに有効期限は設定しないことをおすすめします。これは、暗黙のフローでトークンが期限切れになったときに、ユーザーが再びアカウントをリンクしなければならないためです。セキュリティ上の理由でトークンの有効期限が必要な場合は、代わりに認証コードフローを使用することを強くおすすめします。
設計ガイドライン
このセクションでは、OAuth リンクフローをホストするユーザー画面のデザイン要件と推奨事項について説明します。Google アプリに呼び出されると、プラットフォームから Google ログインページとアカウントのリンクの同意画面が表示されます。アカウントのリンクに同意したユーザーは、Google のアプリにリダイレクトされます。
![この図は、ユーザーが Google アカウントを認証システムにリンクするための手順を示しています。最初のスクリーンショットは、ユーザーがプラットフォームから開始したリンクを示しています。2 番目の画像は、Google へのユーザーのログインを示し、3 番目の画像は、Google アカウントとアプリのリンクに関するユーザーの同意と確認を示しています。最後のスクリーンショットは、Google アプリで正常にリンクされたユーザー アカウントを示しています。](https://developers.google.cn/static/identity/images/oauth-linking-flow.png?authuser=2&hl=ja)
要件
- ユーザーのアカウントが Google や Google アシスタントなどの特定の Google サービスではなく、Google にリンクされていることを伝える必要があります。
推奨事項
次の手順を行うことをおすすめします。
Google のプライバシー ポリシーを表示する。同意画面に Google のプライバシー ポリシーへのリンクを含めます。
共有するデータ。明確で簡潔な表現を使って、Google が必要とするデータとその理由をユーザーに伝えます。
行動を促す明確なフレーズがある。「同意してリンクする」など、行動を促す明確なフレーズを明記する。これは、ユーザーがアカウントをリンクするために Google と共有する必要があるデータを理解する必要があるからです。
解約が可能。ユーザーがリンクしない場合に、戻るかキャンセルする方法を提供する。
ログイン処理をクリアするユーザーが Google アカウントにログインするための明確な方法(ユーザー名とパスワードのフィールド、Google でログインなど)を提供していることを確認します。
リンクを解除する機能。プラットフォーム上でのアカウント設定の URL など、リンクを解除するメカニズムをユーザーに提供します。あるいは、ユーザーがリンクされたアカウントを管理できる Google アカウントへのリンクを含めることもできます。
ユーザー アカウントを変更できること。ユーザーがアカウントを切り替える方法を提案する。これは、ユーザーが複数のアカウントを持つ傾向がある場合に特に役立ちます。
- ユーザーがアカウントを切り替えて同意画面を閉じる必要がある場合は、OAuth リンクと暗黙的フローを使用して、ユーザーが希望するアカウントにログインできるように、回復可能なエラーを Google に送信します。
ロゴを掲載する。同意画面に会社のロゴを表示します。 スタイル ガイドラインを使用してロゴを配置します。Google のロゴも表示する場合は、ロゴと商標をご覧ください。
![この図は、個々のログイン画面と同意画面を設計する際の推奨事項と推奨事項を示す、ユーザーのログイン画面と同意画面を示しています。](https://developers.google.cn/static/identity/images/oauth-linking-consent.png?authuser=2&hl=ja)
プロジェクトを作成する
プロジェクトを作成してアカウント リンクを使用するには:
- Go to the Google API Console.
- [ プロジェクトを作成]をクリックします 。
- 名前を入力するか、生成された提案を受け入れます。
- 残りのフィールドを確認または編集します。
- 作成をクリックします 。
プロジェクトIDを表示するには:
- Go to the Google API Console.
- ランディングページの表でプロジェクトを見つけます。 ID列にプロジェクトIDが表示されます。
OAuth 同意画面を設定する
Google アカウント リンクのプロセスには同意画面が含まれます。この画面では、データへのアクセスをリクエストしているユーザーのアプリケーション、リクエストしているデータの種類、適用される規約を確認できます。Google API クライアント ID を生成する前に、OAuth 同意画面を設定する必要があります。
- Google API コンソールの OAuth 同意画面ページを開きます。
- プロンプトが表示されたら、作成したプロジェクトを選択します。
[OAuth 同意画面] ページでフォームに記入し、[保存] ボタンをクリックします。
アプリケーション名: 同意を求めるアプリケーションの名前。この名前は、アプリケーションを正確に反映し、ユーザーが他の部分で目にするアプリケーション名と一致する必要があります。アプリ名は、アカウント リンクの同意画面に表示されます。
アプリケーションのロゴ: ユーザーがアプリを認識できるよう、同意画面に表示する画像です。ロゴは、アカウントのリンクの同意画面とアカウント設定に表示されます。
サポートメール: ユーザーからの同意に関する問い合わせ先です。
Google API のスコープ: スコープを使用すると、アプリケーションがユーザーの限定公開の Google データにアクセスできるようになります。Google アカウント リンクのユースケースでは、デフォルトのスコープ(メール、プロファイル、openid)で十分です。機密性の高いスコープを追加する必要はありません。通常は、事前にアクセスするのではなく、アクセスが必要になったときに段階的にスコープをリクエストすることをおすすめします。詳しくはこちらをご覧ください。
承認済みドメイン: 管理者とユーザーを保護するため、Google では、OAuth を使用して認証を行うアプリケーションのみに承認済みドメインの使用を許可します。アプリケーションのリンクは承認済みドメインでホストする必要があります。詳しくはこちらをご覧ください。
Application Homepage リンク: アプリケーションのホームページ。承認済みドメインでホストされている必要があります。
アプリのプライバシー ポリシーへのリンク: Google アカウント リンクの同意画面に表示されます。承認済みドメインでホストされている必要があります。
お申し込みの利用規約へのリンク(省略可): 承認済みドメインでホストされている必要があります。
図 1. 架空のアプリケーション(Tunery)の Google アカウント リンクの同意画面
[Verification Status] をオンにします。申請に確認が必要な場合は、[Submit For Verification] ボタンをクリックして、確認の申請を送信します。詳しくは、OAuth 検証の要件をご覧ください。
OAuth サーバーを実装する
OAuth 2.0 の暗黙的フローをサポートするには、サービスで認証を行います。 使用できます。このエンドポイントは、認証と認可を担当します。 データアクセスについてユーザーから同意を得る。認可エンドポイントは、ログインしていないユーザーにログイン用の UI を表示し、リクエストされたアクセスへの同意を記録します。
Google アプリケーションが、サービスの承認済み API のいずれかを呼び出す必要がある場合は、 Google はこのエンドポイントを使用して、これらの API を呼び出す権限をユーザーから取得します 委任できます。
通常、Google が開始する OAuth 2.0 インプリシット フローのセッションは次のような流れになります。
- Google がユーザーのブラウザで認可エンドポイントを開きます。「 ユーザーがログインし(まだログインしていない場合)、Google に次の権限を与える API を使用してデータにアクセスする必要があります(まだ権限を付与していない場合)。
- サービスによってアクセス トークンが作成され、トークンが Googleそのためには、アクセス権を使ってユーザーのブラウザを Google にリダイレクトします。 リクエストに添付されたトークンです。
- Google がサービスの API を呼び出し、アクセス トークンを できます。サービスが、そのアクセス トークンが Google Cloud アクセスが承認され、API 呼び出しが完了します。
認可リクエストの処理
Google アプリケーションで OAuth 2.0 経由でアカウント リンクを実行する必要がある場合 の暗黙的フローで、Google はユーザーを認可エンドポイントに送り、 次のパラメータを含むリクエストです。
認可エンドポイントのパラメータ | |
---|---|
client_id |
Google に割り当てたクライアント ID。 |
redirect_uri |
このリクエストに対するレスポンスを送信する URL。 |
state |
リダイレクト URL で変更されずに Google に返される会計上の値。 |
response_type |
レスポンスで返される値のタイプ。OAuth 2.0 暗黙の API では、
レスポンス タイプは常に token です。 |
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&response_type=token&user_locale=LOCALE
認可エンドポイントでログイン リクエストを処理するには、次の操作を行います。 手順:
client_id
とredirect_uri
の値を検証する 意図しないクライアント アプリへのアクセスや構成ミスのあるクライアント アプリclient_id
が、指定したクライアント ID と一致することを確認します。 割り当てられていますredirect_uri
で指定された URL を確認します。 パラメータの形式は次のとおりです。https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
ユーザーがサービスにログインしているかどうか確認します。ユーザーがログインしていない場合は、サービスのログインまたは登録フローを完了します。
Google が API にアクセスするために使用するアクセス トークンを生成します。「 アクセス トークンには任意の文字列値を指定できますが、アクセス トークンを一意に 推測できるようにする必要があります。
ユーザーのブラウザを URL にリダイレクトする HTTP レスポンスを送信する
redirect_uri
パラメータで指定します。URL フラグメントに次のパラメータをすべて含めます。access_token
: 生成したアクセス トークンtoken_type
: 文字列bearer
state
: 元の状態から変更されていない状態の値 リクエスト
結果の URL の例を次に示します。
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
Google の OAuth 2.0 リダイレクト ハンドラがアクセス トークンを受け取り、
state
値が変更されていないことを確認します。Google は、
そのトークンを後続の呼び出しにアタッチします。
サービス API に追加できます。
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の遊び場のツールを。
ツールで、次の手順を実行します。
- 設定をクリックし OAuth 2.0の設定]ウィンドウを開きます。
- OAuthの流れ場では、クライアント側を選択します。
- OAuthのエンドポイント]フィールドで、[カスタム]を選択します。
- OAuth2.0エンドポイントとGoogleに割り当てたクライアントIDを対応するフィールドに指定します。
- ステップ1セクションでは、すべてのGoogleサービスのスコープを選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーに有効なスコープ(または、OAuthスコープを使用しない場合は任意の文字列)を入力してください。設定が完了したら、承認のAPIをクリックします。
- ステップ2とステップ3のセクションでは、OAuth 2.0のフローを通過し、意図したように各ステップが動作することを確認。
あなたは使用して実装を検証することができ、Googleアカウントのリンクデモツールを。
ツールで、次の手順を実行します。
- Googleのボタンでサインインしをクリックしてください。
- リンクするアカウントを選択してください。
- サービスIDを入力します。
- オプションで、アクセスを要求する1つ以上のスコープを入力します。
- スタートデモをクリックしてください。
- プロンプトが表示されたら、リンク要求に同意して拒否できることを確認します。
- プラットフォームにリダイレクトされていることを確認します。