OAuthとリンクするGoogleアカウント

アカウントは、業界標準のOAuth2.0暗黙的および認証コードフローを使用してリンクされます。サービスは、OAuth2.0準拠の承認トークン交換エンドポイントをサポートする必要があります。

暗黙的なフローでは、Googleはユーザーのブラウザで認証エンドポイントを開きます。サインインに成功すると、長期間有効なアクセストークンをGoogleに返します。このアクセストークンは、Googleから送信されるすべてのリクエストに含まれるようになりました。

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

  • 既に署名されていないユーザーにサインインUIを提示認可エンドポイントは、。認可エンドポイントはまた、要求されたアクセスにレコードのユーザーの同意に短命認証コードを作成します。

  • トークン交換エンドポイント。2種類の交換を担当します。

    1. 認証コードを、有効期間の長い更新トークンと有効期間の短いアクセストークンに交換します。この交換は、ユーザーがアカウントリンクフローを通過するときに発生します。
    2. 有効期間の長い更新トークンを有効期間の短いアクセストークンと交換します。この交換は、有効期限が切れたためにGoogleが新しいアクセストークンを必要とするときに発生します。

OAuth2.0フローを選択します

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

設計ガイドライン

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

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

要件

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

推奨事項

次のことを行うことをお勧めします。

  1. Googleのプライバシーポリシーを表示します。同意画面にGoogleのプライバシーポリシーへのリンクを含めます。

  2. 共有するデータ。明確で簡潔な言葉を使用して、Googleが必要とするデータとその理由をユーザーに伝えます。

  3. 召喚状を明確にします。 「同意してリンクする」など、同意画面に明確な召喚状を記載します。これは、ユーザーがアカウントをリンクするためにGoogleと共有する必要があるデータを理解する必要があるためです。

  4. キャンセルする機能。リンクしないことを選択した場合、ユーザーが戻るかキャンセルする方法を提供します。

  5. サインインプロセスをクリアします。ユーザーは、自分のユーザ名とパスワード、またはのためのフィールドとして、自分のGoogleアカウントにログインするための明確な方法があることを確認してくださいGoogleアカウントでサインインし

  6. リンクを解除する機能。プラットフォームのアカウント設定へのURLなど、ユーザーがリンクを解除するためのメカニズムを提供します。または、ユーザーがリンクされたアカウントを管理できるGoogleアカウントへのリンクを含めることもできます。

  7. ユーザーアカウントを変更する機能。ユーザーが自分のアカウントを切り替える方法を提案します。これは、ユーザーが複数のアカウントを持っている傾向がある場合に特に役立ちます。

    • ユーザーがアカウントを切り替えるために同意画面を閉じる必要がある場合は、回復可能なエラーをGoogleに送信して、ユーザーがOAuthリンク暗黙的なフロー使用して目的のアカウントにサインインできるようにします。
  8. あなたのロゴを含めてください。同意画面に会社のロゴを表示します。スタイルガイドラインを使用してロゴを配置します。 Googleのロゴも表示したい場合は、ロゴと商標を参照してください。

建立专案

要创建您的项目以使用帐户链接:

  1. Go to the Google API Console.
  2. [ プロジェクトを作成]をクリックします
  3. 名前を入力するか、生成された提案を受け入れます。
  4. 残りのフィールドを確認または編集します。
  5. 作成をクリックします

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

  1. Go to the Google API Console.
  2. ランディングページの表でプロジェクトを見つけます。 ID列にプロジェクトIDが表示されます。

Google帐户链接过程包括一个同意屏幕,该屏幕告诉用户请求访问其数据的应用程序,他们要求的数据类型以及适用的条款。在生成Google API客户端ID之前,您需要先配置OAuth同意屏幕。

  1. 打开Goog​​le API控制台的OAuth同意屏幕页面。
  2. 如果出现提示,请选择刚刚创建的项目。
  3. 在“ OAuth同意屏幕”页面上,填写表格,然后单击“保存”按钮。

    申请名称:要求同意的申请名称。该名称应准确反映您的应用程序,并与用户在其他地方看到的应用程序名称一致。应用程序名称将显示在“帐户链接同意”屏幕上。

    应用程序徽标:同意屏幕上的图像,可帮助用户识别您的应用程序。徽标显示在“帐户链接同意”屏幕和帐户设置上

    支持电子邮件:供用户与您联系以获取有关其同意的问题。

    Google API范围范围允许您的应用访问用户的私人Google数据。对于Google帐户关联用例,默认范围(电子邮件,个人资料,openid)就足够了,您无需添加任何敏感范围。通常,最佳做法是在需要访问时而不是预先请求增量地作用域。 了解更多

    授权域:为了保护您和您的用户,Google仅允许使用OAuth进行身份验证的应用程序使用授权域。您的应用程序的链接必须托管在授权域中。 了解更多

    应用程序主页链接:您的应用程序的主页。必须托管在授权域上。

    应用程序隐私权政策链接:显示在Google Acount Linking同意屏幕上。必须托管在授权域上。

    应用程序服务条款链接(可选):必须托管在授权域中。

    图1 。虚拟应用程序Google Tuning的Google帐户链接同意屏幕

  4. 选中“验证状态”,如果您的应用程序需要验证,则单击“提交验证”按钮以提交您的应用程序以进行验证。有关详细信息,请参阅OAuth验证要求

OAuthサーバーを実装する

为了支持OAuth 2.0已隐含流,你的服务使可通过HTTPS授权端点。此端点负责身份验证并获得用户对数据访问的同意。授权端点向尚未登录的用户显示登录 UI,并记录对请求访问的同意。

当 Google 应用程序需要调用您的服务的授权 API 之一时,Google 会使用此端点来获得您的用户的许可,以代表他们调用这些 API。

一个典型的由 Google 发起的 OAuth 2.0 隐式流会话具有以下流程:

  1. Google 在用户的浏览器中打开您的授权端点。用户登录(如果尚未登录)并授予 Google 使用您的 API 访问其数据的权限(如果他们尚未授予权限)。
  2. 您的服务创建的访问令牌并将其返回给谷歌。为此,请使用附加到请求的访问令牌将用户的浏览器重定向回 Google。
  3. Google 会调用您服务的 API 并在每个请求中附加访问令牌。您的服务会验证访问令牌是否授予 Google 访问 API 的授权,然后完成 API 调用。

处理授权请求

当 Google 应用程序需要通过 OAuth 2.0 隐式流执行帐户链接时,Google 会将用户发送到您的授权端点,并包含以下参数的请求:

授权端点参数
client_id您分配给 Google 的客户端 ID。
redirect_uri您向其发送对此请求的响应的 URL。
state传递回 Google 的簿记值在重定向 URI 中保持不变。
response_type要在响应中返回的值的类型。对于的OAuth 2.0隐式流程中,响应类型总是token
user_locale在谷歌帐户语言设置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

对于处理登录请求的授权端点,请执行以下步骤:

  1. 验证client_idredirect_uri值,以防止授权访问意外或错误配置的客户端应用程序:

    • 确认该client_id你分配给谷歌的客户ID相匹配。
    • 确认URL指定由redirect_uri参数有以下形式:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  2. 检查用户是否已登录您的服务。如果用户未登录,请完成服务的登录或注册流程。

  3. 生成供 Google 用来访问您的 API 的访问令牌。访问令牌可以是任何字符串值,但它必须唯一地代表用户和令牌所针对的客户端,并且不能被猜测。

  4. 发送用户的浏览器重定向到被指定的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

谷歌的OAuth 2.0重定向处理接收的令牌的访问并确认state的值并没有改变。在 Google 为您的服务获取访问令牌后,Google 会将令牌附加到对您的服务 API 的后续调用中。

userinfoリクエストを処理する

ユーザー情報エンドポイントは、リンクされたユーザについての戻り主張OAuth 2.0の保護されたリソースです。次のユースケースを除いて、userinfoエンドポイントの実装とホスティングはオプションです。

トークンエンドポイントからアクセストークンが正常に取得されると、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エンドポイントでリクエストを処理するには、次の手順を実行します。

  1. Authorizationヘッダーからアクセストークンを抽出し、アクセストークンに関連付けられているユーザーの情報を返します。
  2. アクセストークンが無効である場合は、使用してHTTP 401不正なエラーを返すWWW-Authenticate応答ヘッダを。以下のユーザー情報のエラー応答の例である:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: error="invalid_token",
    error_description="The Access Token expired"
    
    401不正な、または他の任意の失敗エラー応答をリンク処理中に返された場合、エラーが回復不能、検索されたトークンは廃棄されることになり、ユーザが持っているであろうリンクプロセスを再開します。
  3. アクセストークンが有効であれば、リターンおよび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の遊び場のツールを。

ツールで、次の手順を実行します。

  1. 設定をクリックし OAuth 2.0の設定]ウィンドウを開きます。
  2. OAuthの流れ場では、クライアント側を選択します。
  3. OAuthのエンドポイント]フィールドで、[カスタム]を選択します。
  4. OAuth2.0エンドポイントとGoogleに割り当てたクライアントIDを対応するフィールドに指定します。
  5. ステップ1セクションでは、すべてのGoogleサービスのスコープを選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーに有効なスコープ(または、OAuthスコープを使用しない場合は任意の文字列)を入力してください。設定が完了したら、承認のAPIをクリックします。
  6. ステップ2ステップ3のセクションでは、OAuth 2.0のフローを通過し、意図したように各ステップが動作することを確認。

あなたは使用して実装を検証することができ、Googleアカウントのリンクデモツールを。

ツールで、次の手順を実行します。

  1. Googleのボタンでサインインしをクリックしてください。
  2. リンクするアカウントを選択してください。
  3. サービスIDを入力します。
  4. オプションで、アクセスを要求する1つ以上のスコープを入力します。
  5. スタートデモをクリックしてください。
  6. プロンプトが表示されたら、リンク要求に同意して拒否できることを確認します。
  7. プラットフォームにリダイレクトされていることを確認します。