「Google でログイン」の HTML API リファレンス

このリファレンス ページでは、Sign In with Google HTML データ属性 API について説明します。API を使用して、ワンタップ プロンプトや [Google でログイン] ボタンをウェブページに表示できます。

ID が「g_id_onload」の要素

「Google でログイン」のデータ属性は、<div> や <span> などの表示要素または非表示要素に設定できます。唯一の要件は、要素 ID を g_id_onload に設定することです。この ID を複数の要素に設定しないでください。

データ属性

次の表に、データ属性とその説明を示します。

属性タイプ

以降のセクションでは、各属性のタイプと例について詳しく説明します。

data-client_id

この属性は、アプリのクライアント ID です。この ID は Google Cloud コンソールで検索して作成できます。詳しくは、次の表をご覧ください。

data-auto_prompt

この属性は、ワンタップ表示するかどうかを指定します。デフォルト値は true です。この値が false の場合、Google One Tap は表示されません。詳しくは、次の表をご覧ください。

data-auto_select

この属性は、1 つの Google セッションのみがアプリを承認した場合に、ユーザー操作なしで ID トークンを自動的に返すかどうかを決定します。デフォルト値は false です。詳しくは、以下の表をご覧ください。

data-login_uri

この属性は、ログイン エンドポイントの URI です。

この値は、API Console で構成した OAuth 2.0 クライアントの承認済みリダイレクト URI のいずれかと完全に一致し、リダイレクト URI の検証ルールに準拠している必要があります。

現在のページがログイン ページである場合は、この属性を省略できます。この場合、認証情報はデフォルトでこのページに投稿されます。

コールバック関数が定義されておらず、ユーザーが [Google でログイン] ボタンまたは [ワンタップ] ボタンをクリックした場合、または自動ログインが行われた場合、ID トークン認証情報レスポンスがログイン エンドポイントに投稿されます。

詳しくは、次の表をご覧ください。

ログイン エンドポイントは、本文に ID トークン値を持つ credential キーを含む POST リクエストを処理する必要があります。

ログイン エンドポイントへのリクエストの例を次に示します。

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

credential=ID_TOKEN

データ コールバック

この属性は、返された ID トークンを処理する JavaScript 関数の名前です。詳しくは、次の表をご覧ください。

data-login_uri 属性と data-callback 属性のいずれかを使用できます。これは、次のコンポーネントと UX モードの構成に依存します。

• data-login_uri 属性は、「Google でログイン」ボタン redirect UX モードに必要です。このモードでは data-callback 属性は無視されます。

• Google ワンタップと Google ログイン ボタンの popup UX モードには、次の 2 つの属性のいずれかを設定する必要があります。両方を設定した場合は、data-callback 属性が優先されます。

名前空間内の JavaScript 関数は、HTML API ではサポートされていません。代わりに、名前空間のないグローバル JavaScript 関数を使用してください。（たとえば、mylib.callback ではなく mylibCallback を使用しているなど）。

data-native_login_uri

この属性は、パスワード認証情報ハンドラ エンドポイントの URL です。data-native_login_uri 属性または data-native_callback 属性のいずれかを設定すると、Google セッションがない場合、JavaScript ライブラリはネイティブ認証情報マネージャーにフォールバックします。data-native_callback 属性と data-native_login_uri 属性の両方を設定することはできません。詳しくは、次の表をご覧ください。

データ ネイティブ コールバック

この属性は、ブラウザのネイティブ認証情報マネージャーから返されたパスワード認証情報を処理する JavaScript 関数の名前です。data-native_login_uri 属性または data-native_callback 属性を設定した場合、Google セッションがない場合、JavaScript ライブラリはネイティブの認証情報マネージャーにフォールバックします。data-native_callback と data-native_login_uri の両方を設定することはできません。詳しくは、次の表をご覧ください。

名前空間内の JavaScript 関数は、HTML API ではサポートされていません。代わりに、名前空間のないグローバル JavaScript 関数を使用してください。（たとえば、mylib.callback ではなく mylibCallback を使用しているなど）。

data-native_id_param

パスワード認証情報をパスワード認証情報ハンドラ エンドポイントに送信するときに、credential.id フィールドにパラメータ名を指定できます。デフォルト名は email です。詳しくは、以下の表をご覧ください。

data-native_password_param

パスワード認証情報をパスワード認証情報ハンドラ エンドポイントに送信するときに、credential.password 値のパラメータ名を指定できます。デフォルト名は password です。詳しくは、次の表をご覧ください。

data-cancel_on_tap_outside

この属性は、ユーザーがプロンプトの外側をクリックした場合にワンタップ リクエストをキャンセルするかどうかを設定します。デフォルト値は true です。無効にするには、値を false に設定します。詳しくは、以下の表をご覧ください。

data-prompt_parent_id

この属性は、コンテナ要素の DOM ID を設定します。設定されていない場合は、ウィンドウの右上にワンタップ プロンプトが表示されます。詳しくは、次の表をご覧ください。

data-skip_prompt_cookie

指定された Cookie に空でない値がある場合、この属性はワンタップをスキップします。詳しくは、次の表をご覧ください。

data-nonce

この属性は、ID トークンがリプレイ攻撃を防ぐために使用するランダムな文字列です。詳しくは、以下の表をご覧ください。

ノンスの長さは、環境でサポートされている JWT の最大サイズと、個々のブラウザとサーバーの HTTP サイズの制約によって制限されます。

data-context

この属性は、ワンタップ プロンプトに表示されるタイトルとメッセージのテキストを変更します。詳しくは、以下の表をご覧ください。

次の表に、使用可能なコンテキストとその説明をすべて示します。

data-moment_callback

この属性は、プロンプト UI ステータス通知リスナーの関数名です。詳細については、データ型 PromptMomentNotification をご覧ください。

詳しくは、以下の表をご覧ください。

名前空間内の JavaScript 関数は、HTML API ではサポートされていません。代わりに、名前空間のないグローバル JavaScript 関数を使用してください。たとえば、mylib.callback ではなく mylibCallback を使用します。

data-state_cookie_domain

親ドメインとそのサブドメインにワンタップを表示する必要がある場合は、親ドメインをこの属性に渡して、単一の共有状態 Cookie が使用されるようにします。詳しくは、以下の表をご覧ください。

data-ux_mode

この属性は、[Google でログイン] ボタンで使用される UX フローを設定します。デフォルト値は popup です。この属性はワンタップの UX には影響しません。詳しくは、次の表をご覧ください。

次の表に、使用可能な UX モードとその説明を示します。

data-allowed_parent_origin

中間 iframe の埋め込みを許可するオリジン。この属性が存在する場合、ワンタップは中間 iframe モードで実行されます。詳しくは、次の表をご覧ください。

次の表に、サポートされている値の型とその説明を示します。

data-allowed_parent_origin 属性の値が無効な場合、中間 iframe モードのワンタップ初期化は失敗して停止します。

ワイルドカードの接頭辞もサポートされています。たとえば、"https://*.example.com" は、すべてのレベル（news.example.com、login.news.example.com など）で example.com とそのサブドメインに一致します。ワイルドカードを使用する際は、次の点に注意してください。

• パターン文字列をワイルドカードとトップレベル ドメインのみで構成することはできません。たとえば、https://*.com と https://*.co.uk は無効です。上記のとおり、"https://*.example.com" は example.com とそのサブドメインと一致します。カンマ区切りのリストを使用して、2 つの異なるドメインを表すこともできます。たとえば、"https://example1.com,https://*.example2.com" はドメイン example1.com、example2.com、example2.com のサブドメインと一致します。
• ワイルドカード ドメインはセキュアな https:// スキームで始まる必要があるため、"*.example.com" は無効と見なされます。

data-intermediate_iframe_close_callback

ユーザーがワンタップ UI の [X] ボタンをタップして手動でワンタップを閉じた場合、デフォルトの中間 iframe の動作をオーバーライドします。デフォルトの動作では、中間 iframe は DOM からすぐに削除されます。

data-intermediate_iframe_close_callback フィールドは、中間 iframe モードでのみ有効になります。また、影響はワンタップ iframe ではなく、中間 iframe にのみ及ぶため、コールバックが呼び出される前に、ワンタップ UI が削除されます。

名前空間内の JavaScript 関数は、HTML API ではサポートされていません。代わりに、名前空間のないグローバル JavaScript 関数を使用してください。（たとえば、mylib.callback ではなく mylibCallback を使用しているなど）。

data-itp_support

このフィールドは、Intelligent Tracking Prevention（ITP）をサポートするブラウザで アップグレードされたワンタップ UX を有効にするかどうかを決定します。デフォルト値は false です。詳しくは、次の表をご覧ください。

data-login_hint

アプリがログインするユーザーを事前に把握している場合は、Google にログイン ヒントを提供できます。成功すると、アカウントの選択はスキップされます。指定できる値は、メールアドレスまたは ID トークンの sub フィールドです。

詳細については、 login_hint の OpenID Connect ドキュメントをご覧ください。

データ HD

ユーザーが複数のアカウントを持っていて、Workspace アカウントでのみログインする必要がある場合は、この値を使用して Google にドメイン名のヒントを提供します。成功すると、アカウント選択時に表示されるユーザー アカウントは、指定されたドメインに限定されます。ワイルドカード値: * は、ユーザーに Workspace アカウントのみを提供し、アカウント選択時に一般ユーザー アカウント（user@gmail.com）を除外します。

詳細については、 hd の OpenID Connect ドキュメントをご覧ください。

data-use_fedcm_for_prompt

ブラウザがユーザーのログイン プロンプトを制御し、ウェブサイトと Google の間でログインフローを仲介できるようにします。デフォルトは false です。詳細については、FedCM への移行をご覧ください。

data-enable_redirect_uri_validation

リダイレクト URI の検証ルールに準拠したボタンのリダイレクト フローを有効にします。

クラスが「g_id_signin」の要素

要素の class 属性に g_id_signin を追加すると、要素は [Google でログイン] ボタンとしてレンダリングされます。

同じページに複数の [Google でログイン] ボタンをレンダリングできます。各ボタンには、独自のビジュアル設定を指定できます。この設定は、次のデータ属性によって定義されます。

ビジュアル データの属性

次の表に、画像データ属性とその説明を示します。

属性タイプ

以降のセクションでは、各属性のタイプの詳細と例について説明します。

data-type

ボタンのタイプ。デフォルト値は standard です。詳細については、次の表をご覧ください。

次の表に、使用可能なすべてのボタンタイプとその説明を示します。

タイプ
standard
icon

data-theme

ボタンのテーマ。デフォルト値は outline です。詳しくは、次の表をご覧ください。

次の表に、使用可能なテーマとその説明を示します。

テーマ
outline
filled_blue
filled_black

データサイズ

ボタンのサイズ。デフォルト値は large です。詳しくは、次の表をご覧ください。

次の表に、利用可能なボタンのサイズとその説明を示します。

サイズ
large
medium
small

データテキスト

ボタンのテキスト。デフォルト値は signin_with です。data-text 属性が異なるアイコンボタンのテキストに視覚的な違いはありません。唯一の例外は、画面のユーザー補助のためにテキストが読み上げられる場合です。

詳しくは、以下の表をご覧ください。

次の表に、使用可能なボタンテキストとその説明を示します。

テキスト
signin_with
signup_with
continue_with
signin

data-shape

ボタンの形状。デフォルト値は rectangular です。詳しくは、次の表をご覧ください。

次の表に、使用可能なボタンの形状とその説明を示します。

図形
rectangular
pill
circle
square

data-logo_alignment

Google ロゴの配置。デフォルト値は left です。この属性は、standard ボタンタイプにのみ適用されます。詳しくは、次の表をご覧ください。

次の表に、使用可能なアライメントとその説明を示します。

logo_alignment
left
center

データ幅

ボタンの最小幅（ピクセル単位）。使用できる最大幅は 400 ピクセルです。

詳しくは、以下の表をご覧ください。

data-locale

省略可。指定した言語 / 地域を使用してボタンのテキストを表示します。指定しない場合、ユーザーの Google アカウントまたはブラウザの設定がデフォルトになります。ライブラリを読み込むときに、hl パラメータと言語コードを src ディレクティブに追加します（例: gsi/client?hl=<iso-639-code>）。

設定されていない場合は、ブラウザのデフォルトのロケールまたは Google セッション ユーザーの設定が使用されます。そのため、ユーザーによって、ローカライズされたボタンのバージョンやサイズが異なることがあります。

詳しくは、以下の表をご覧ください。

data-click_listener

data-click_listener 属性を使用して、[Google でログイン] ボタンがクリックされたときに呼び出される JavaScript 関数を定義できます。

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

この例では、[Google でログイン] ボタンがクリックされると、「Sign in with Google ボタンのクリック...」というメッセージがコンソールに記録されます。

data-state

省略可。同じページに複数の [Google でログイン] ボタンをレンダリングできるため、各ボタンに固有の文字列を割り当てることができます。同じ文字列が ID トークンと共に返されるため、ユーザーがクリックしてログインしたボタンを特定できます。

詳しくは、以下の表をご覧ください。

サーバーサイドの統合

サーバーサイド エンドポイントは、次の HTTP POST リクエストを処理する必要があります。

ID トークン ハンドラのエンドポイント

ID トークン ハンドラ エンドポイントは、ID トークンを処理します。対応するアカウントのステータスに基づいて、ユーザーをログインさせ、登録ページに誘導するか、アカウントのリンクページに誘導して詳細情報を確認します。

HTTP POST リクエストには、次の情報が含まれます。

証明書

デコードされた ID トークンは次の例のようになります。

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

sub フィールドは、Google アカウントのグローバルに一意の識別子です。sub フィールドは、すべての Google アカウントに固有で、決して再利用されないため、ユーザーの ID としてのみ使用してください。Google アカウントには異なる時点で複数のメールアドレスを設定できるため、メールアドレスを ID として使用しないでください。

email、email_verified、hd フィールドを使用して、Google がメールアドレスをホストし、そのメールアドレスに対して信頼できるかどうかを判断できます。Google が正式な場合、お客様が正当なアカウント所有者であることが確認されます。

Google が正式な情報源となるケース:

• email に @gmail.com という接尾辞が付いている場合は、Gmail アカウントです。
• email_verified が true で hd が設定されている場合、これは Google Workspace アカウントです。

ユーザーは Gmail や Google Workspace を使用せずに Google アカウントに登録できます。 email に @gmail.com 接尾辞が含まれず、hd がない場合、Google は信頼できる情報源ではなく、ユーザーの確認にはパスワードなどのチャレンジ方法をおすすめします。email_verified は、Google アカウントの作成時に Google がユーザーを最初に確認したため true になることもありますが、サードパーティのメール アカウントの所有権がそれ以降変更されている可能性があります。

exp フィールドには、サーバーサイドでトークンを検証するための有効期限が表示されます。Google でログインから取得した ID トークンは 1 時間です。有効期限が切れる前にトークンを確認する必要があります。セッション管理に exp を使用しないでください。ID トークンの有効期限が切れた場合、ユーザーがログアウトされたわけではありません。ユーザーのセッション管理はアプリが行います。

select_by

次の表に、select_by フィールドで使用できる値を示します。値の設定には、セッションと同意ステータスとともに使用されるボタンのタイプが使用されます。

• ユーザーが [ワンタップ] ボタンまたは [Google でログイン] ボタンを押しているか、非接触の自動ログイン プロセスを使用した場合。

• 既存のセッションが見つかったか、ユーザーが Google アカウントを選択してログインし、新しいセッションを確立した。

• ユーザーは、アプリと ID トークンの認証情報を共有する前に、次のいずれかを行います。

  • [確認] ボタンを押して認証情報の共有に同意した
  • 以前に同意を許可し、[アカウントを選択] を使用して Google アカウントを選択している。

このフィールドの値は、次のいずれかのタイプに設定します。

state

このパラメータは、ユーザーが [Google でログイン] ボタンをクリックしてログインし、クリックしたボタンの data-state 属性が指定されている場合にのみ定義されます。このフィールドの値は、ボタンの data-state 属性で指定した値と同じです。

同じページに複数の [Google でログイン] ボタンをレンダリングできるため、各ボタンに固有の文字列を割り当てることができます。したがって、この state パラメータを使用して、ユーザーがログインするためにクリックしたボタンを特定できます。

パスワード認証情報ハンドラのエンドポイント

パスワード認証情報ハンドラ エンドポイントは、ネイティブ認証情報マネージャーが取得したパスワード認証情報を処理します。

HTTP POST リクエストには、次の情報が含まれます。