OAuth と Google ログインによる効率的なリンク

概要

OAuth ベースの Google ログインの効率的なリンクにより、Google ログインが OAuth リンク。これにより、シームレスなリンク体験が実現します。 また、アカウントの作成が可能になります。アカウントの作成により、ユーザーは自分の Google アカウントを使用して、サービスの新しいアカウントを作成できます。

OAuth と Google ログインを使用してアカウント リンクを行うには、次の一般的な手順に従います。

  1. まず、ユーザーの Google プロフィールにアクセスすることについてユーザーに同意を求めます。
  2. プロフィールの情報を使用して、ユーザー アカウントが存在するかどうかを確認します。
  3. 既存のユーザーの場合は、アカウントをリンクします。
  4. 一致する Google ユーザーが認証システムで見つからなかった場合は、 Google から受け取った ID トークンを検証する。その後、IP アドレスなどの ID トークンに含まれるプロフィール情報に照らし合わせます。
この図は、ユーザーが効率的なリンクフローを使用して Google アカウントをリンクする手順を示しています。1 つ目のスクリーンショットは、ユーザーがリンク対象のアプリを選択する方法を示しています。2 番目のスクリーンショットでは、ユーザーがサービスの既存のアカウントを持っているかどうかを確認できます。3 番目のスクリーンショットでは、ユーザーがリンクする Google アカウントを選択します。4 番目のスクリーンショットは、Google アカウントとアプリをリンクすることの確認を示しています。5 番目のスクリーンショットは、Google アプリでユーザー アカウントに正常にリンクされた状態を示しています。

図 1. ユーザーのスマートフォンでのアカウントのリンク（合理化されたリンク設定）

リンクを効率化するための要件

  • 基本的なウェブ OAuth リンクフローを実装します。サービスが OAuth 2.0 に準拠している必要がある 認可エンドポイントとトークン交換エンドポイント。
  • トークン交換エンドポイントは、JSON Web Token（JWT）アサーションをサポートし、check、create、get インテントを実装する必要があります。
で確認できます。

OAuth サーバーを実装する

トークン交換エンドポイントは、check、create、get の各インテントをサポートしている必要があります。以下に、アカウント リンクのフロー全体で完了した手順と、さまざまなインテントが呼び出されるタイミングを示します。

  1. ユーザーは、認証システムのアカウントを持っているか？（ユーザーが「はい」または「いいえ」を選択） <ph type="x-smartling-placeholder">
      </ph>
    1. 「はい」の場合 : ユーザーは Google アカウントに関連付けられているメールアドレスを使用してプラットフォームにログインしていますか？（ユーザーが「はい」または「いいえ」を選択） <ph type="x-smartling-placeholder">
        </ph>
      1. はい : ユーザーは、認証システムに一致するアカウントをお持ちですか？（確認のため check intent が呼び出されます）。 <ph type="x-smartling-placeholder">
          </ph>
        1. YES : get intent が呼び出され、get インテントが正常に返されるとアカウントがリンクされます。
        2. いいえ : 新しいアカウントを作成しますか？（ユーザーが「はい」または「いいえ」を選択） <ph type="x-smartling-placeholder">
            </ph>
          1. YES : 作成インテントが正常に返されると、create intent が呼び出され、アカウントがリンクされます。
          2. いいえ : ウェブ OAuth フローがトリガーされ、ユーザーはブラウザに転送されます。ユーザーは別のメールアドレスでリンクできます。
      2. いいえの場合 : ウェブ OAuth フローがトリガーされ、ユーザーはブラウザに転送されます。ユーザーは別のメールアドレスでリンクできます。
    2. いいえ : ユーザーは、認証システムに一致するアカウントを持っているか？（確認のため check intent が呼び出されます）。 <ph type="x-smartling-placeholder">
        </ph>
      1. YES : get intent が呼び出され、get インテントが正常に返されるとアカウントがリンクされます。
      2. いいえ : 作成インテントが正常に返されると、create intent が呼び出され、アカウントがリンクされます。

既存のユーザー アカウントを確認する（インテントを確認する）

ユーザーが Google プロフィールへのアクセスに同意すると、 Google ユーザーの ID に関する署名付きアサーションを含むリクエスト。「 アサーションには、ユーザーの Google アカウント ID、 表示されます。アプリケーション用に構成されたトークン交換エンドポイント プロジェクトがリクエストを処理できます

対応する Google アカウントが認証にすでに存在する場合 トークン交換エンドポイントは account_found=true を返します。もし Google アカウントが既存のユーザーと一致しません。トークン交換エンドポイントがあります account_found=false で HTTP 404 Not Found エラーを返す。

リクエストは次のようになります。

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

トークン交換エンドポイントでは、以下のパラメータを処理する必要があります。

トークン交換エンドポイントのパラメータ
intent これらのリクエストでは、このパラメータの値は check。
grant_type 交換されるトークンの種類。これらのリクエストでは、 パラメータの値は urn:ietf:params:oauth:grant-type:jwt-bearer です。
assertion Google ユーザー ID の署名付きアサーションを提供する JSON Web Token（JWT）。この JWT には、ユーザーの認証情報、 Google アカウント ID、名前、メールアドレス。
client_id Google に割り当てたクライアント ID。
client_secret Google に割り当てたクライアント シークレット。

check インテント リクエストに応答するには、トークン交換エンドポイントで次の手順を行う必要があります。

  • JWT アサーションを検証してデコードします。
  • Google アカウントが認証システムにすでに存在するかどうかを確認します。
Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example: 

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

  • email has a @gmail.com suffix, this is a Gmail account.
  • email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

Google アカウントが認証システムに存在するかどうかの確認

次のいずれかの条件を満たしていることを確認します。

  • アサーションの sub フィールドにある Google アカウント ID がユーザーのものである データベースです
  • アサーションに含まれているメールアドレスが、ユーザーのデータベースに登録されているユーザーと一致している。

いずれかの条件が true の場合、ユーザーは登録済みです。その場合、 次のようなレスポンスが返されます。

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Google アカウント ID もメールアドレスも アサーションがデータベース内のユーザーと一致した場合、ユーザーはまだ登録されていません。イン この場合、トークン交換エンドポイントは HTTP 404 エラーを返す必要があります。 "account_found": "false" を指定します。次に例を示します。

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

自動リンクを処理する（インテントの取得）

ユーザーが Google プロフィールへのアクセスに同意すると、 Google ユーザーの ID に関する署名付きアサーションを含むリクエスト。「 アサーションには、ユーザーの Google アカウント ID、 表示されます。アプリケーション用に構成されたトークン交換エンドポイント プロジェクトがリクエストを処理できます

対応する Google アカウントが認証にすでに存在する場合 トークン交換エンドポイントはユーザーにトークンを返します。もし Google アカウントが既存のユーザーと一致しない（トークン交換エンドポイント） linking_error エラーとオプションの login_hint を返します。

リクエストは次のようになります。

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

トークン交換エンドポイントでは、以下のパラメータを処理する必要があります。

トークン交換エンドポイントのパラメータ
intent これらのリクエストでは、このパラメータの値は get になります。
grant_type 交換されるトークンの種類。これらのリクエストでは、 パラメータの値は urn:ietf:params:oauth:grant-type:jwt-bearer です。
assertion Google ユーザー ID の署名付きアサーションを提供する JSON Web Token（JWT）。この JWT には、ユーザーの認証情報、 Google アカウント ID、名前、メールアドレス。
scope 省略可: Google がリクエストするように構成したスコープ できます。
client_id Google に割り当てたクライアント ID。
client_secret Google に割り当てたクライアント シークレット。

get インテント リクエストに応答するには、トークン交換エンドポイントで次の手順を行う必要があります。

  • JWT アサーションを検証してデコードします。
  • Google アカウントが認証システムにすでに存在するかどうかを確認します。
Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example: 

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

  • email has a @gmail.com suffix, this is a Gmail account.
  • email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

Google アカウントが認証システムに存在するかどうかの確認

次のいずれかの条件を満たしていることを確認します。

  • アサーションの sub フィールドにある Google アカウント ID がユーザーのものである データベースです
  • アサーションに含まれているメールアドレスが、ユーザーのデータベースに登録されているユーザーと一致している。

ユーザーのアカウントが見つかった場合、アクセス トークンを発行し、次の例のように HTTPS レスポンスの本文で JSON オブジェクトの値を返します。 

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

場合によっては、ユーザーが ID トークンに基づくアカウントのリンクが失敗することがあります。もし トークン交換エンドポイントは、HTTP HTTPS レスポンスで応答する必要があります。 error=linking_error を指定する 401 エラーが返されます。

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Google は、linking_error で 401 エラー レスポンスを受信すると、 login_hint をパラメータとして使用して、ユーザーを認可エンドポイントに送信します。「 ユーザーがブラウザで OAuth リンクフローを使用してアカウントのリンクを完了します。

Google ログインを介したアカウント作成の処理（インテントの作成）

ユーザーがニュース メディアのサービスでアカウントを作成する必要がある場合、Google は intent=create を指定するトークン交換エンドポイントに追加します。

リクエストは次のようになります。

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

トークン交換エンドポイントは、次のパラメータを処理できる必要があります。

トークン交換エンドポイントのパラメータ
intent これらのリクエストでは、このパラメータの値は create になります。
grant_type 交換されるトークンの種類。これらのリクエストでは、 パラメータの値は urn:ietf:params:oauth:grant-type:jwt-bearer です。
assertion Google ユーザー ID の署名付きアサーションを提供する JSON Web Token（JWT）。この JWT には、ユーザーの認証情報、 Google アカウント ID、名前、メールアドレス。
client_id Google に割り当てたクライアント ID。
client_secret Google に割り当てたクライアント シークレット。

assertion パラメータ内の JWT には、ユーザーの Google アカウント ID が含まれます。 名前とメールアドレスです。これらの情報を使用して、 あります。

create インテント リクエストに応答するには、トークン交換エンドポイントで次の手順を行う必要があります。

  • JWT アサーションを検証してデコードします。
  • ユーザー情報を確認し、新しいアカウントを作成する。
Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example: 

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

  • email has a @gmail.com suffix, this is a Gmail account.
  • email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

ユーザー情報を検証して新しいアカウントを作成する

次のいずれかの条件を満たしていることを確認します。

  • アサーションの sub フィールドにある Google アカウント ID がユーザーのものである データベースです
  • アサーションに含まれているメールアドレスが、ユーザーのデータベースに登録されているユーザーと一致している。

いずれかの条件が true の場合、既存のアカウントをリンクするようユーザーに促す ログインする必要がありますそのためには、リクエストに対して HTTP 401 エラーを返します。 error=linking_error を指定し、ユーザーのメールアドレスを login_hint。レスポンスの例を次に示します。

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Google は、linking_error で 401 エラー レスポンスを受信すると、 login_hint をパラメータとして使用して、ユーザーを認可エンドポイントに送信します。「 ユーザーがブラウザで OAuth リンクフローを使用してアカウントのリンクを完了します。

どちらの条件も当てはまらない場合は、その情報で新しいユーザー アカウントを作成します。 JWT で提供します。通常、新しいアカウントにはパスワードが設定されていません。です。 他のプラットフォームにも Google ログインを追加して、ユーザーが Google でログインできるようになります。または パスワードの再設定フローを開始するリンクをメールで送信できます。 ユーザーが他のプラットフォームにログインするためのパスワードを設定できるようにする必要があります。

作成が完了したら、アクセス トークンを発行します。 更新トークンを使用して JSON オブジェクトで値を HTTPS レスポンスの本文に URL を付加します。 

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

Google API クライアント ID を取得する

Google API クライアント ID は、アカウントのリンクの登録プロセスの際に提供する必要があります。

OAuth リンクの手順で作成したプロジェクトを使用して、API クライアント ID を取得する。そのための手順は次のとおりです。

  1. Google Cloud コンソールの [認証情報] ページを開きます。 Google API コンソール。

  2. Google API プロジェクトを作成または選択します。

    プロジェクトにウェブ アプリケーション タイプのクライアント ID がない場合は、[ 認証情報を作成 >OAuth Client-ID を使用してクライアント ID を作成します。必ず サイトのドメインを [承認済みの JavaScript 生成元] ボックスに入力します。パフォーマンス ローカルテストまたは開発環境では、http://localhost と http://localhost:<port_number> を [承認済みの JavaScript 生成元] フィールドに入力します。

実装の検証

実装を検証するには、OAuth 2.0 Playground ツールを使用します。

ツールで、次の操作を行います。

  1. [Configuration] をクリックして [OAuth 2.0 Configuration] ウィンドウを開きます。
  2. [OAuth flow] フィールドで、[Client-side] を選択します。
  3. [OAuth Endpoints]（OAuth エンドポイント）で、[Custom]（カスタム）を選択します。
  4. 対応するフィールドに、OAuth 2.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. プラットフォームにリダイレクトされることを確認します。