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

アカウントは、業界標準のOAuth2.0暗黙的および認証コードフローを使用してリンクされます。サービスは、OAuth2.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. 作成をクリックします

To view your project ID:

  1. Go to the Google API Console.
  2. Find your project in the table on the landing page. The project ID appears in the ID column.

Google アカウントのリンク処理には、データにアクセスするアプリ、ユーザーがリクエストしているデータの種類、適用される条件についてユーザーに知らせる同意画面があります。Google API クライアント ID を生成する前に、OAuth 同意画面を設定する必要があります。

  1. Google API Console の [OAuth 同意画面] ページを開きます。
  2. プロンプトが表示されたら、作成したプロジェクトを選択します。
  3. [OAuth 同意画面] ページで、フォームに入力して [保存] ボタンをクリックします。

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

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

    サポートメール: お客様から同意に関する問い合わせがあった場合のサポートメールです。

    Google API のスコープ: アプリケーションは、ユーザーの非公開の Google データにアクセスします。Google アカウントのリンクのユースケースでは、デフォルトのスコープ(メール、プロファイル、openid)で十分です。機密性の高いスコープを追加する必要はありません。一般的には、アクセス権を必要なときに事前にリクエストするのではなく、段階的に増分リクエストを送信することをおすすめします。詳細

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

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

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

    アプリケーションの利用規約へのリンク(省略可): 承認済みドメインでホストする必要があります。

    図 1. 架空のアプリ、Tunery の Google アカウントのリンクの同意画面

  4. 「適格性確認のステータス」を確認します。申請者が申請を必要とする場合は、[適格性確認のために送信] ボタンをクリックして申請フォームを送信します。詳しくは、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パラメータ。あなたが追加することによってリダイレクトするときにだけ生成された認証コードとオリジナルの、無修正の状態値を含めるcodestateのパラメータを。以下は、得られた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オプション:ユーザーのプロフィール画像。

実装の検証

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

  1. Click Configuration to open the OAuth 2.0 Configuration window.
  2. In the OAuth flow field, select Client-side.
  3. In the OAuth Endpoints field, select Custom.
  4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
  5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
  6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

  1. Click the Sign-in with Google button.
  2. Choose the account you'd like to link.
  3. Enter the service ID.
  4. Optionally enter one or more scopes that you will request access for.
  5. Click Start Demo.
  6. When prompted, confirm that you may consent and deny the linking request.
  7. Confirm that you are redirected to your platform.