このリファレンスでは、ウェブ アプリケーションに Google ログインを実装するために使用する JavaScript のクライアント メソッドと属性について説明します。
ライブラリの使用中に問題が発生した場合は、GitHub リポジトリにご報告ください。
認証設定
Google API プラットフォーム ライブラリを読み込み、gapi
オブジェクトを作成します。
<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>
プラットフォーム ライブラリを読み込んだら、auth2
ライブラリを読み込みます。
function init() {
gapi.load('auth2', function() {
/* Ready. Make a call to gapi.auth2.init or some other API */
});
}
gapi.auth2.init(params)
GoogleAuth
オブジェクトを初期化します。このメソッドは、gapi.auth2.GoogleAuth
のメソッドを呼び出す前に行う必要があります。
GoogleAuth
オブジェクトを初期化するときに、OAuth 2.0 クライアント ID と指定する追加オプションを使用してオブジェクトを構成します。その後、ユーザーがすでにログインしている場合、GoogleAuth
オブジェクトは前のセッションからユーザーのログイン状態を復元します。
引数 | |
---|---|
params |
クライアントの構成データの Key-Value ペアを含むオブジェクト。構成可能なさまざまなプロパティについては、gapi.auth2.ClientConfig をご覧ください。例: { client_id: 'CLIENT_ID.apps.googleusercontent.com' } |
戻り値 | |
---|---|
gapi.auth2.GoogleAuth |
gapi.auth2.GoogleAuth オブジェクト。then() メソッドを使用して、gapi.auth2.GoogleAuth オブジェクトの初期化が完了したときに解決される Promise を取得します。
|
GoogleAuth.then(onInit、onError)
GoogleAuth
オブジェクトが完全に初期化されると、onInit 関数を呼び出します。初期化中にエラーが発生した場合(これは、サポートされていない古いブラウザで発生する可能性があります)、代わりに onError 関数が呼び出されます。
引数 | |
---|---|
onInit |
完全に初期化されたときに GoogleAuth オブジェクトで呼び出される関数。 |
onError |
GoogleAuth の初期化に失敗した場合、error プロパティを含むオブジェクトで呼び出される関数。
|
戻り値 | |
---|---|
Promise | onInit 関数の完了時に処理される Promise 、または初期化エラーが発生した場合は拒否される Promise 。onInit 関数から返された値があれば解決します。 |
エラーコード
idpiframe_initialization_failed
-
サポート対象外の環境が原因で、Google から必要な iframe を初期化できませんでした。
details
プロパティは、発生したエラーの詳細情報を提供します。
gapi.auth2.ClientConfig
gapi.auth2.init
メソッドのさまざまな構成パラメータを表すインターフェース。
パラメータ | ||
---|---|---|
client_id |
string |
必須。Google Developers Console で検出、作成されたアプリのクライアント ID。 |
cookie_policy |
string |
ログイン Cookie を作成するドメイン。URI、single_host_origin 、none のいずれか。指定しない場合のデフォルトは single_host_origin です。 |
scope |
string |
リクエストするスコープ(スペース区切りの文字列)。fetch_basic_profile が false に設定されていない場合は省略可能です。 |
fetch_basic_profile |
boolean |
ユーザーのログイン時に基本的なプロフィール情報を取得します。リクエストされたスコープに「profile」、「email」、「openid」を追加します。指定しない場合は true。 |
hosted_domain |
string |
ユーザーのログインに必要な G Suite ドメイン。これはクライアントによる変更に影響する可能性があるため、返されるユーザーのホストされているドメイン プロパティを必ず確認してください。クライアントで GoogleUser.getHostedDomain() を使用し、サーバーの ID トークンの hd クレームを使用して、ドメインが期待どおりであることを確認します。 |
ux_mode |
string |
ログインフローに使用する UX モード。デフォルトでは、同意フローがポップアップに表示されます。有効な値は popup と redirect です。 |
redirect_uri |
string |
ux_mode='redirect' を使用している場合、このパラメータを使用すると、同意フローの最後で使用されるデフォルトの redirect_uri をオーバーライドできます。デフォルトの redirect_uri は、クエリ パラメータとハッシュ フラグメントが削除された現在の URL です。 |
plugin_name |
string |
(省略可)この値が設定されている場合、2022 年 7 月 29 日より前に作成された新しいクライアント ID では、古い Google プラットフォーム ライブラリを使用できます。デフォルトでは、新しく作成されたクライアント ID はプラットフォーム ライブラリの使用をブロックされ、新しい Google Identity Services ライブラリを使用する必要があります。任意の値を選択できます。識別しやすいように、プロダクト名やプラグイン名など、わかりやすい名前をおすすめします。例: plugin_name: 'YOUR_STRING_HERE' |
認証
GoogleAuth
は、ユーザーが Google アカウントでログインし、ユーザーの現在のログイン ステータスを取得し、ユーザーの Google プロフィールから特定のデータを取得して、追加のスコープをリクエストし、現在のアカウントからログアウトできるようにするメソッドを提供するシングルトン クラスです。
gapi.auth2.getAuthInstance()
GoogleAuth
オブジェクトを返します。このメソッドを呼び出す前に、gapi.auth2.init()
で GoogleAuth
オブジェクトを初期化する必要があります。
戻り値 | |
---|---|
gapi.auth2.GoogleAuth |
gapi.auth2.GoogleAuth オブジェクト。このオブジェクトを使用して gapi.auth2.GoogleAuth のメソッドを呼び出します。 |
GoogleAuth.isSignedIn.get()
現在のユーザーが現在ログインしているかどうかを返します。
戻り値 | |
---|---|
ブール値 |
true ユーザーがログインしている場合、またはfalse ユーザーがログアウトしている場合、または GoogleAuth オブジェクトが初期化されていない場合。 |
GoogleAuth.isSignedIn.listen(listener)
現在のユーザーのログイン状態の変化をリッスンします。
引数 | |
---|---|
listener |
ブール値を受け取る関数。listen() は、ユーザーがログインしたときに true をこの関数に渡し、ユーザーがログアウトしたときに false をこの関数に渡します。 |
GoogleAuth.signIn()
gapi.auth2.init()
に指定されているオプションを使用してユーザーのログインを行います。
戻り値 | |
---|---|
Promise | ユーザーが認証に成功して付与すると GoogleUser インスタンスで処理される Promise 。エラーが発生した場合は、error プロパティを含むオブジェクトで拒否されます(エラーコードについては以下をご覧ください)。 |
エラーコード
GoogleAuth.signIn(options)
をご確認ください。
GoogleAuth.signIn(options)
指定されたオプションを使用してユーザーのログインを行います。
引数 | |
---|---|
options |
次のいずれかを行います。
|
戻り値 | |
---|---|
Promise | ユーザーが認証に成功して付与すると GoogleUser インスタンスで処理される Promise 。エラーが発生した場合は、error プロパティを含むオブジェクトで拒否されます(エラーコードについては以下をご覧ください)。 |
エラーコード
popup_closed_by_user
- ログインフローが完了する前にユーザーがポップアップを閉じた。
access_denied
- ユーザーが、必要なスコープに対する権限を拒否しました。
immediate_failed
-
同意フローのプロンプトを表示せずにユーザーを自動的に選択することはできません。
prompt: 'none'
オプションを指定してsignIn
を使用するとエラーが発生しました。以前にセッションにログインしたことがある場合は、gapi.auth2.init
によって自動的にユーザーのログインが行われるため、このオプションの使用は必須ではありません。
gapi.auth2.SignInOptions
GoogleAuth.signIn(options)
メソッドのさまざまな構成パラメータを表すインターフェース。
パラメータ | ||
---|---|---|
prompt |
string |
同意フローに特定のモードを強制します。省略可。 取り得る値は次のとおりです。
|
scope |
string |
gapi.auth2.init パラメータで定義されたスコープの上に、スペースで区切った文字列としてリクエストするスコープ。fetch_basic_profile が false に設定されていない場合は省略可能です。 |
ux_mode |
string |
ログインフローに使用する UX モード。デフォルトでは、同意フローがポップアップに表示されます。有効な値は popup と redirect です。 |
redirect_uri |
string |
ux_mode='redirect' を使用している場合、このパラメータを使用すると、同意フローの最後で使用されるデフォルトの redirect_uri をオーバーライドできます。デフォルトの redirect_uri は、クエリ パラメータとハッシュ フラグメントが削除された現在の URL です。 |
GoogleAuth.signOut()
現在のアカウントからログアウトします。
戻り値 | |
---|---|
Promise | ユーザーがログアウトしたときに処理される Promise 。 |
GoogleAuth.disconnect()
ユーザーが付与したすべてのスコープを取り消します。
GoogleAuth.grantOfflineAccess(options)
指定したスコープにオフラインでアクセスする権限をユーザーから取得します。
引数 | |
---|---|
options |
パラメータの Key-Value ペアを含む gapi.auth2.OfflineAccessOptions オブジェクト。次に例を示します。 { scope: 'profile email' } |
戻り値 | |
---|---|
Promise | ユーザーがリクエストされたスコープを付与し、認証コードを含むオブジェクトを Promise のフルフィルメント ハンドラに渡すと処理される Promise 。次に例を示します。 auth2.grantOfflineAccess().then(function(resp) { var auth_code = resp.code; }); |
エラーコード
popup_closed_by_user
- ユーザーは、同意フローを完了する前にポップアップを閉じました。
access_denied
- ユーザーが、必要なスコープに対する権限を拒否しました。
immediate_failed
-
同意フローのプロンプトを表示せずにユーザーを自動的に選択することはできません。
prompt: 'none'
オプションを指定してsignIn
を使用するとエラーが発生しました。以前にセッションにログインしたことがある場合は、gapi.auth2.init
によって自動的にユーザーのログインが行われるため、このオプションの使用は必須ではありません。
gapi.auth2.OfflineAccessOptions
GoogleAuth.grantOfflineAccess(options)
メソッドのさまざまな構成パラメータを表すインターフェース。
パラメータ | ||
---|---|---|
prompt |
string |
同意フローに特定のモードを強制します。省略可。 取り得る値は次のとおりです。
|
scope |
string |
gapi.auth2.init パラメータで定義されたスコープの上に、スペースで区切った文字列としてリクエストするスコープ。fetch_basic_profile が false に設定されていない場合は省略可能です。 |
GoogleAuth.attachClickHandler(container、options、onsuccess、onfailure)
指定されたコンテナのクリック ハンドラにログインフローを接続します。
引数 | |
---|---|
container | クリック ハンドラを接続する div 要素の ID または参照。 |
options | パラメータの Key-Value ペアを含むオブジェクト。GoogleAuth.signIn() をご覧ください。 |
onsuccess | ログインの完了後に呼び出す関数。 |
onfailure | ログインが失敗した場合に呼び出す関数。 |
ユーザー
GoogleUser
オブジェクトは 1 つのユーザー アカウントを表します。
GoogleUser
オブジェクトは通常、GoogleAuth.currentUser.get() を呼び出して取得します。
GoogleAuth.currentUser.get()
現在のユーザーを表す GoogleUser
オブジェクトを返します。新しく初期化された GoogleAuth
インスタンスでは、現在のユーザーが設定されていないことに注意してください。初期化された GoogleAuth
インスタンスを取得するには、currentUser.listen()
メソッドまたは GoogleAuth.then()
を使用します。
戻り値 | |
---|---|
GoogleUser |
現在のユーザー |
GoogleAuth.currentUser.listen(listener)
currentUser の変更をリッスンします。
引数 | |
---|---|
listener |
GoogleUser パラメータを受け取る関数。listen は、currentUser を変更するすべての変更で GoogleUser インスタンスをこの関数に渡します。 |
GoogleUser.getId()
ユーザーの一意の ID 文字列を取得します。
戻り値 | |
---|---|
String | ユーザーの一意の ID |
GoogleUser.isSignedIn()
ユーザーがログインしている場合は true を返します。
戻り値 | |
---|---|
ブール値 | ユーザーがログインしている場合は true |
GoogleUser.getHostedDomain()
ユーザーが G Suite アカウントでログインしている場合は、ユーザーの G Suite ドメインを取得します。
戻り値 | |
---|---|
String | ユーザーの G Suite ドメイン |
GoogleUser.getGrantedScopes()
ユーザーがスペースで区切った文字列として付与したスコープを取得します。
戻り値 | |
---|---|
String | ユーザーが付与したスコープ |
GoogleUser.getBasicProfile()
ユーザーの基本的なプロフィール情報を取得します。
戻り値 | |
---|---|
gapi.auth2.BasicProfile |
gapi.auth2.BasicProfile のプロパティは、次の方法で取得できます。
|
GoogleUser.getAuthResponse(includeAuthorizationData)
ユーザーの認証セッションからレスポンス オブジェクトを取得します。
引数 | |
---|---|
includeAuthorizationData | 省略可: アクセス トークンとスコープを常に返すかどうかを指定するブール値。デフォルトでは、fetch_basic_profile が true(デフォルト値)で、追加のスコープがリクエストされていない場合、アクセス トークンとリクエストされたスコープは返されません。 |
戻り値 | |
---|---|
gapi.auth2.AuthResponse |
gapi.auth2.AuthResponse オブジェクト。
|
GoogleUser.reloadAuthResponse()
アクセス トークンを強制的に更新してから、新しい AuthResponse の Promise を返します。
戻り値 | |
---|---|
Promise |
OAuth トークンの再読み込みが完了したときに、再読み込みされた gapi.auth2.AuthResponse で処理される Promise 。 |
gapi.auth2.AuthResponse
GoogleUser.getAuthResponse(includeAuthorizationData)
メソッドまたは GoogleUser.reloadAuthResponse()
メソッドを呼び出すときに返されるレスポンス。
プロパティ | ||
---|---|---|
access_token |
string |
付与されたアクセス トークン。 |
id_token |
string |
付与される ID トークン。 |
scope |
string |
アクセス トークンで付与されるスコープ。 |
expires_in |
number |
アクセス トークンが期限切れになるまでの秒数。 |
first_issued_at |
number |
ユーザーが最初にリクエストしたスコープを付与した時点のタイムスタンプ。 |
expires_at |
number |
アクセス トークンが期限切れになるタイムスタンプ。 |
GoogleUser.hasGrantedScopes(scopes)
ユーザーが指定されたスコープを付与した場合に true を返します。
引数 | |
---|---|
scopes | スコープのスペース区切りの文字列。 |
戻り値 | |
---|---|
ブール値 | スコープが付与されている場合は true |
GoogleUser.grant(options)
ユーザーに追加のスコープをリクエストします。
パラメータのリストとエラーコードについては、GoogleAuth.signIn()
をご覧ください。
GoogleUser.grantOfflineAccess(options)
指定したスコープにオフラインでアクセスする権限をユーザーから取得します。
引数 | |
---|---|
options |
パラメータの Key-Value ペアを含む gapi.auth2.OfflineAccessOptions オブジェクト。次に例を示します。 { scope: 'profile email' } |
GoogleUser.disconnect()
ユーザーがアプリケーションに付与したスコープをすべて取り消します。
UI 要素
gapi.signin2.render(id、options)
options オブジェクトで指定された設定を使用して、指定された ID の要素にログインボタンをレンダリングします。
引数 | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | ログインボタンをレンダリングする要素の ID。 | ||||||||||||||||
options |
ボタンのレンダリングに使用する設定を含むオブジェクト。次に例を示します。
{ scope: 'email', width: 200, height: 50, longtitle: true, theme: 'dark', onsuccess: handleSuccess, onfailure: handleFailure }次のオプションを指定できます。
|
高度
gapi.auth2.authorization(params、callback)
OAuth 2.0 認証を 1 回実行します。使用するパラメータに応じて、Google ログインフローのポップアップを開くか、ユーザーの操作なしでリクエストされたレスポンスを通知なしに読み込みます。
この方法が役立つユースケースには、次のようなものがあります。
- ユーザーが Google API エンドポイントを最初にリクエストする必要があるのは、たとえばユーザーがログインしたときにお気に入りの YouTube 動画を読み込む場合などです。
- アプリケーションには独自のセッション管理インフラストラクチャがあり、バックエンドでユーザーを識別するために ID トークンが 1 回だけ必要になります。
- 同じページ内で複数のクライアント ID を使用している。
引数 | |
---|---|
params |
構成データの Key-Value ペアを含むオブジェクト。構成可能なさまざまなプロパティについては、gapi.auth2.AuthorizeConfig をご覧ください。例: { client_id: 'CLIENT_ID.apps.googleusercontent.com', scope: 'email profile openid', response_type: 'id_token permission' } |
callback |
リクエストの完了後(成功または失敗で)、gapi.auth2.AuthorizeResponse オブジェクトで呼び出される関数。 |
例
gapi.auth2.authorize({
client_id: 'CLIENT_ID.apps.googleusercontent.com',
scope: 'email profile openid',
response_type: 'id_token permission'
}, function(response) {
if (response.error) {
// An error happened!
return;
}
// The user authorized the application for the scopes requested.
var accessToken = response.access_token;
var idToken = response.id_token;
// You can also now use gapi.client to perform authenticated requests.
});
エラーコード
idpiframe_initialization_failed
-
サポート対象外の環境が原因で、Google から必要な iframe を初期化できませんでした。
details
プロパティは、発生したエラーの詳細情報を提供します。 popup_closed_by_user
- ログインフローが完了する前にユーザーがポップアップを閉じた。
access_denied
- ユーザーが、必要なスコープに対する権限を拒否しました。
immediate_failed
-
同意フローのプロンプトを表示せずにユーザーを自動的に選択することはできません。
prompt: 'none'
オプションを指定してsignIn
を使用するとエラーが発生しました。
gapi.auth2.AuthorizeConfig
gapi.auth2.authorize
メソッドのさまざまな構成パラメータを表すインターフェース。
プロパティ | ||
---|---|---|
client_id |
string |
必須。Google Developers Console で検出、作成されたアプリのクライアント ID。 |
scope |
string |
必須。リクエストするスコープ(スペース区切りの文字列)。 |
response_type |
string |
スペース区切りのレスポンス タイプのリスト。デフォルトは 'permission' です。値は次のいずれかです。
|
prompt |
string |
同意フローに特定のモードを強制します。値は次のいずれかです。
|
cookie_policy |
string |
ログイン Cookie を作成するドメイン。URI、single_host_origin 、none のいずれか。指定しない場合のデフォルトは single_host_origin です。 |
hosted_domain |
string |
ユーザーのログインに必要な G Suite ドメイン。これはクライアントによる変更に影響する可能性があるため、返されるユーザーのホストされているドメイン プロパティを必ず確認してください。 |
login_hint |
string |
ログインフローで事前に選択するユーザーのメールアドレスまたはユーザー ID。prompt: "none" を使用している場合を除き、ユーザーがこの変更の影響を受ける可能性があります。 |
include_granted_scopes |
boolean |
ユーザーがアプリに以前に付与したすべてのスコープを含むアクセス トークンをリクエストするか、現在の呼び出しでリクエストされたスコープのみをリクエストするか。デフォルトは true です。 |
plugin_name |
string |
(省略可)設定すると、2022 年 7 月 29 日より前に作成されたクライアント ID で Google プラットフォーム ライブラリを使用できます。デフォルトでは、新しく作成されたクライアント ID はプラットフォーム ライブラリの使用をブロックされているため、新しい Google Identity Services ライブラリを使用する必要があります。任意の値を選択できます。簡単に識別できるように、プロダクト名やプラグイン名など、わかりやすい名前をおすすめします。例: plugin_name: 'YOUR_STRING_HERE' |
gapi.auth2.AuthorizeResponse
gapi.auth2.authorize
メソッドのコールバックに返されたレスポンス。
プロパティ | ||
---|---|---|
access_token |
string |
アクセス トークンが付与されました。response_type で permission または token が指定されている場合のみ存在します。
|
id_token |
string |
付与される ID トークン。response_type で id_token を指定した場合のみ存在します。 |
code |
string |
承認された認証コード。response_type で code を指定した場合のみ存在します。 |
scope |
string |
アクセス トークンで付与されるスコープ。response_type で permission または token が指定されている場合のみ存在します。
|
expires_in |
number |
アクセス トークンが期限切れになるまでの秒数。response_type で permission または token を指定した場合のみ存在します。
|
first_issued_at |
number |
ユーザーが最初にリクエストしたスコープを付与した時点のタイムスタンプ。response_type で permission または token が指定されている場合のみ存在します。
|
expires_at |
number |
アクセス トークンが期限切れになるタイムスタンプ。response_type で permission または token を指定した場合のみ存在します。
|
error |
string |
リクエストが失敗した場合、エラーコードが含まれます。 |
error_subtype |
string |
リクエストが失敗した場合は、返されるエラーコードに関する追加情報も含まれる可能性があります。 |