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. 作成をクリックします

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

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

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で使用可能認可エンドポイントになります。このエンドポイントは、データアクセスの認証とユーザーからの同意の取得を担当します。承認エンドポイントは、まだサインインしていないユーザーにサインイン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オプション:ユーザーのプロフィール画像。

実装の検証

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.