このリファレンスでは、ウェブ アプリケーションに 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 | Promise 。onInit 関数が完了したときに履行されるか、初期化エラーが発生した場合に拒否されます。onInit 関数からの戻り値(存在する場合)で解決されます。 |
エラーコード
idpiframe_initialization_failed
-
サポートされていない環境などが原因で、Google から必要な iframe を初期化できませんでした。
details
プロパティは、発生したエラーに関する詳細情報を提供します。
gapi.auth2.ClientConfig
gapi.auth2.init
メソッドのさまざまな構成パラメータを表すインターフェース。
パラメータ | ||
---|---|---|
client_id |
string |
必須。Google API 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 クレームを使用して、ドメインが想定どおりであることを確認します。 |
use_fedcm |
boolean |
省略可。デフォルトは True です。ログイン時のブラウザの FedCM API の使用を有効または無効にします。 |
ux_mode |
string |
ログインフローに使用する UX モード。デフォルトでは、同意フローがポップアップで開きます。有効な値は popup と redirect です。 |
redirect_uri |
string |
ux_mode='redirect' を使用している場合、このパラメータを使用すると、同意フローの最後に使用されるデフォルトの redirect_uri をオーバーライドできます。デフォルトの redirect_uri は、クエリ パラメータとハッシュ フラグメントが削除された現在の URL です。 |
enable_granular_consent |
boolean |
省略可。きめ細かい権限を有効にするかどうか。false に設定した場合、2019 年より前に作成された OAuth クライアント ID に対して、より詳細な Google アカウント権限が無効になります。2019 年中またはそれ以降に作成された OAuth クライアント ID については、よりきめ細かい権限が常に有効になっているため、影響はありません。
|
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 。ユーザーがログアウトしている場合、または GoogleAuth オブジェクトが初期化されていない場合は false 。 |
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 | Promise 。ユーザーが認証に成功してリクエストされたスコープを付与した場合に GoogleUser インスタンスで解決されます。エラーが発生した場合は、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
インスタンスでは、現在のユーザーが設定されていないことに注意してください。currentUser.listen()
メソッドまたは GoogleAuth.then()
を使用して、初期化された GoogleAuth
インスタンスを取得します。
戻り値 | |
---|---|
GoogleUser |
現在のユーザー |
GoogleAuth.currentUser.listen(listener)
currentUser の変更をリッスンする。
引数 | |
---|---|
listener |
GoogleUser パラメータを受け取る関数。listen は、currentUser を変更するたびに、この関数に GoogleUser インスタンスを渡します。 |
GoogleUser.getId()
ユーザーの一意の ID 文字列を取得します。
戻り値 | |
---|---|
文字列 | ユーザーの一意の ID |
GoogleUser.isSignedIn()
ユーザーがログインしている場合は true を返します。
戻り値 | |
---|---|
ブール値 | ユーザーがログインしている場合は true |
GoogleUser.getHostedDomain()
ユーザーが G Suite アカウントでログインしている場合は、ユーザーの G Suite ドメインを取得します。
戻り値 | |
---|---|
文字列 | ユーザーの G Suite ドメイン |
GoogleUser.getGrantedScopes()
ユーザーが付与したスコープをスペース区切りの文字列として取得します。
戻り値 | |
---|---|
文字列 | ユーザーが付与したスコープ |
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.authorize(params, callback)
1 回限りの OAuth 2.0 認証を行います。使用するパラメータに応じて、Google ログインフローのポップアップが表示されるか、リクエストされたレスポンスをユーザーの操作なしで読み込みを試行します。
この方法は、次のようなユースケースに役立ちます。
- アプリケーションで Google API エンドポイントをリクエストする必要があるのは 1 回のみです。たとえば、ユーザーが初めてログインしたときにお気に入りの 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 API 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 です。 |
enable_granular_consent |
boolean |
省略可。きめ細かい権限を有効にするかどうか。false に設定した場合、2019 年より前に作成された OAuth クライアント ID に対して、より詳細な Google アカウント権限が無効になります。2019 年中またはそれ以降に作成された OAuth クライアント ID については、よりきめ細かい権限が常に有効になっているため、影響はありません。
|
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 |
リクエストが失敗した場合、返されるエラーコードに追加情報が含まれる場合があります。 |