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

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

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

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

  • 認証エンドポイント。まだログインしていないユーザーにログイン UI を表示します。認証エンドポイントは、リクエストされたアクセスへのユーザーの同意を記録するための有効期間の短い認証コードも作成します。

  • トークン交換エンドポイント。次の 2 種類の交換を行います。

    1. 長期の更新トークンと短期のアクセス トークンの認可コードを交換します。このやり取りは、ユーザーがアカウントのリンクのフローを行ったときに行われます。
    2. 有効期間が長い更新トークンと有効期間の短いアクセス トークンを交換します。この交換は、トークンが期限切れであるために Google が新しいアクセス トークンを必要とする場合に発生します。

OAuth 2.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. ユーザー アカウントを変更できること。ユーザーがアカウントを切り替える方法を提案する。これは、ユーザーが複数のアカウントを持つ傾向がある場合に特に役立ちます。

    • ユーザーがアカウントを切り替えて同意画面を閉じる必要がある場合は、OAuth リンクと暗黙的フローを使用して、ユーザーが希望するアカウントにログインできるように、回復可能なエラーを Google に送信します。

  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. Google API コンソールの OAuth 同意画面ページを開きます。
  2. プロンプトが表示されたら、作成したプロジェクトを選択します。

  3. [OAuth 同意画面] ページでフォームに記入し、[保存] ボタンをクリックします。

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

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

    サポートメール: ユーザーからの同意に関する問い合わせ先です。

    Google API のスコープ: スコープを使用すると、アプリケーションがユーザーの限定公開の Google データにアクセスできるようになります。Google アカウント リンクのユースケースでは、デフォルトのスコープ（メール、プロファイル、openid）で十分です。機密性の高いスコープを追加する必要はありません。通常は、事前にアクセスするのではなく、アクセスが必要になったときに段階的にスコープをリクエストすることをおすすめします。詳しくはこちらをご覧ください。

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

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

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

    お申し込みの利用規約へのリンク（省略可）: 承認済みドメインでホストされている必要があります。

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

  4. [Verification Status] をオンにします。申請に確認が必要な場合は、[Submit For Verification] ボタンをクリックして、確認の申請を送信します。詳しくは、OAuth 検証の要件をご覧ください。

OAuth サーバーを実装する

認証コードフローのOAuth 2.0のサーバーの実装では、あなたのサービスは、HTTPSで利用できるように2つのエンドポイント、から構成されています。最初のエンドポイントは承認エンドポイントであり、データアクセスについてユーザーからの同意を検索または取得する責任があります。承認エンドポイントは、まだサインインしていないユーザーにサインインUIを提示し、要求されたアクセスへの同意を記録します。 2番目のエンドポイントは、トークン交換エンドポイントです。これは、トークンと呼ばれる暗号化された文字列を取得するために使用され、ユーザーにサービスへのアクセスを許可します。

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

Googleによって開始されたOAuth2.0認証コードフローセッションには、次のフローがあります。

  1. Googleは、ユーザーのブラウザで認証エンドポイントを開きます。アクションの音声のみのデバイスでフローが開始された場合、Googleは実行を電話に転送します。
  2. ユーザーは、まだサインインしていない場合はサインインし、まだアクセス許可を付与していない場合は、APIを使用してデータにアクセスするためのGoogleアクセス許可を付与します。
  3. あなたのサービスは、認証コードを作成し、Googleにそれを返します。これを行うには、リクエストに認証コードを添付して、ユーザーのブラウザをGoogleにリダイレクトします。
  4. Googleは、コードの正当性を検証し、アクセストークンとリフレッシュトークンを返し、あなたのトークン交換エンドポイントに認証コードを送信します。アクセストークンは、APIにアクセスするための資格情報としてサービスが受け入れる短期間のトークンです。更新トークンは、有効期限が切れたときにGoogleが保存して、新しいアクセストークンを取得するために使用できる長期間有効なトークンです。
  5. ユーザーがアカウントのリンクフローを完了すると、Googleから送信される後続のすべてのリクエストにアクセストークンが含まれます。

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

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

承認エンドポイントパラメータ
client_id Googleに割り当てたクライアントID。
redirect_uriこのリクエストへの応答を送信するURL。
stateリダイレクトURIで変更されずにGoogleに返される簿記の値。
scopeオプション：Googleがために許可を要求しているデータを指定範囲の文字列のスペース区切りのセット。
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

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

  1. ていることを確認しclient_id Googleに割り当てられたクライアントIDと一致すること、およびredirect_uriあなたのサービスのためにGoogleが提供するリダイレクトURLと一致します。これらのチェックは、意図しないクライアントアプリや誤って構成されたクライアントアプリへのアクセスを許可しないようにするために重要です。あなたが複数のOAuth 2.0のフローをサポートしている場合、またことを確認response_typeあるcode 。
  2. ユーザーがサービスにサインインしているかどうかを確認します。ユーザーがサインインしていない場合は、サービスのサインインまたはサインアップフローを完了します。
  3. GoogleがAPIへのアクセスに使用する認証コードを生成します。認証コードには任意の文字列値を指定できますが、ユーザー、トークンの対象となるクライアント、およびコードの有効期限を一意に表す必要があり、推測できないようにする必要があります。通常、約10分後に有効期限が切れる認証コードを発行します。
  4. URLがで指定されていることを確認redirect_uriパラメータは次の形式を持っている： 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
  5. で指定されたURLにユーザーのブラウザをリダイレクトredirect_uriパラメータ。あなたが追加することによってリダイレクトするときにだけ生成された認証コードとオリジナルの、無修正の状態値を含めるcodeや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は、次の手順を実行して要求：

  1. ことを確認しclient_id認可原点として要求元を識別し、そのclient_secret期待値と一致します。
  2. 認証コードが有効で有効期限が切れていないこと、および要求で指定されたクライアントIDが認証コードに関連付けられたクライアントIDと一致することを確認してください。
  3. URLがで指定されていることを確認redirect_uriパラメータは、最初の認証要求で使用される値と同じです。
  4. あなたが上記の基準のすべてを確認できない場合は、とHTTP 400不正な要求エラーを返す{"error": "invalid_grant"}ボディとして。
  5. それ以外の場合は、認証コードのユーザーIDを使用して、更新トークンとアクセストークンを生成します。これらのトークンは任意の文字列値にすることができますが、トークンの対象となるユーザーとクライアントを一意に表す必要があり、推測可能であってはなりません。アクセストークンの場合は、トークンの有効期限も記録します。これは通常、トークンを発行してから1時間後です。更新トークンは期限切れになりません。
  6. 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次のステップを実行することにより、要求：

  1. ていることを確認しclient_idグーグルとして要求元に識別し、そのclient_secret期待値と一致しました。
  2. 更新トークンが有効であること、および要求で指定されたクライアントIDが更新トークンに関連付けられたクライアントIDと一致することを確認します。
  3. あなたが上記の基準のすべてを確認できない場合は、とHTTP 400不正な要求エラーを返す{"error": "invalid_grant"}ボディとして。
  4. それ以外の場合は、更新トークンのユーザーIDを使用してアクセストークンを生成します。これらのトークンは任意の文字列値にすることができますが、トークンの対象となるユーザーとクライアントを一意に表す必要があり、推測可能であってはなりません。アクセストークンの場合は、トークンの有効期限も記録します。通常は、トークンを発行してから1時間後です。
  5. HTTPS応答の本文で次のJSONオブジェクトを返します。
    {
"token_type": "Bearer",
"access_token": " ACCESS_TOKEN ",
"expires_in": SECONDS_TO_EXPIRATION
}
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. プラットフォームにリダイレクトされていることを確認します。