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. GoogleAPIコンソールのOAuth同意画面ページを開きます。
  2. プロンプトが表示されたら、作成したプロジェクトを選択します。
  3. [OAuth同意画面]ページで、フォームに入力して[保存]ボタンをクリックします。

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

    アプリケーションのロゴ:ユーザーがアプリを認識するのに役立つ同意画面上の画像。ロゴはアカウントリンク同意画面とアカウント設定に表示されます

    サポートメール:ユーザーが同意について質問するためにあなたに連絡するため。

    Google APIのスコープスコープを使用すると、アプリケーションはユーザーのプライベートGoogleデータにアクセスできます。 Googleアカウントリンクのユースケースでは、デフォルトのスコープ(メール、プロファイル、openid)で十分であり、機密性の高いスコープを追加する必要はありません。一般に、事前にではなく、アクセスが必要なときにスコープを段階的に要求することがベストプラクティスです。 詳細をご覧ください

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

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

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

    アプリケーション利用規約リンク(オプション):承認されたドメインでホストされている必要があります。

    図1 。架空のアプリケーション、TuneryのGoogleアカウントリンク同意画面

  4. 「検証ステータス」をチェックし、アプリケーションが検証を必要とする場合は、「検証のために送信」ボタンをクリックして、検証のためにアプリケーションを送信します。詳細については、 OAuth検証要件を参照してください。

OAuthサーバーを実装する

OAuth 2.0の暗黙の流れをサポートするために、あなたのサービスは、HTTPSで使用可能認可エンドポイントになります。このエンドポイントは、データアクセスの認証とユーザーからの同意の取得を担当します。承認エンドポイントは、まだサインインしていないユーザーにサインインUIを提示し、要求されたアクセスへの同意を記録します。

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

Googleによって開始される一般的なOAuth2.0の暗黙的なフローセッションには、次のフローがあります。

  1. Googleは、ユーザーのブラウザで認証エンドポイントを開きます。ユーザーは、まだサインインしていない場合はサインインし、まだアクセス許可を付与していない場合は、APIを使用してデータにアクセスするためのGoogleアクセス許可を付与します。
  2. あなたのサービスでは、アクセストークンとGoogleに戻り、それを作成します。これを行うには、リクエストにアクセストークンを添付して、ユーザーのブラウザをGoogleにリダイレクトします。
  3. GoogleはサービスのAPIを呼び出し、リクエストごとにアクセストークンを添付します。サービスは、アクセストークンがGoogleにAPIへのアクセスを許可することを確認してから、API呼び出しを完了します。

承認リクエストを処理する

GoogleアプリケーションがOAuth2.0の暗黙的なフローを介してアカウントのリンクを実行する必要がある場合、Googleは、次のパラメーターを含むリクエストを使用して、ユーザーを承認エンドポイントに送信します。

承認エンドポイントパラメータ
client_id Googleに割り当てたクライアントID。
redirect_uriこのリクエストへの応答を送信するURL。
stateリダイレクトURIで変更されずにGoogleに返される簿記の値。
response_type応答で返す値のタイプ。 OAuth 2.0の暗黙の流れについては、応答タイプは、常に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

承認エンドポイントがサインイン要求を処理するには、次の手順を実行します。

  1. 確認client_idredirect_uri意図しないまたは誤って設定クライアントアプリケーションへのアクセスを許可防ぐために、値を:

    • ことを確認しclient_id Googleに割り当てられたクライアント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

Googleの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. プラットフォームにリダイレクトされていることを確認します。