ウェブサイト向け Google サードパーティ認証 JavaScript ライブラリ - API リファレンス

このリファレンスでは、Google サードパーティ認証 JavaScript ライブラリ API について説明します。この API を使用すると、Google から認証コードまたはアクセス トークンを読み込むことができます。

メソッド: google.accounts.oauth2.initCodeClient

initCodeClient メソッドは、パラメータの構成を使用してコード クライアントを初期化して返します。

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

データ型: CodeClientConfig

次の表に、CodeClientConfig データ型のプロパティを示します。

プロパティ
client_id 必須。アプリケーションのクライアント ID。この値は API Console で確認できます。
scope 必須。アプリケーションがユーザーの代わりにアクセスできるリソースを特定するスコープのスペース区切りのリストです。これらの値は、Google がユーザーに表示する同意画面に反映されます。
include_granted_scopes 省略可。デフォルトは true です。アプリが段階的認可を使用して、コンテキスト内の追加のスコープへのアクセスをリクエストできるようにします。このパラメータの値を false に設定し、認可リクエストが承認された場合、新しいアクセス トークンは、この CodeClientConfig で scope がリクエストしたスコープにのみ適用されます。
redirect_uri リダイレクト UX に必須です。ユーザーが認可フローを完了した後に API サーバーがユーザーをリダイレクトする先を指定します。この値は、API Console で構成した OAuth 2.0 クライアントの承認済みリダイレクト URI のいずれかと完全に一致している必要があります。また、リダイレクト URI の検証ルールに準拠している必要があります。このプロパティは、ポップアップ UX で無視されます。
callback ポップアップの UX に必要です。返されたコード レスポンスを処理する JavaScript 関数。このプロパティは、リダイレクト UX によって無視されます。
state 省略可。リダイレクト UX に推奨されます。認可リクエストと認可サーバーのレスポンス間で状態を維持するために、アプリケーションが使用する文字列値を指定します。
enable_granular_consent 非推奨。設定しても効果はありません。同意の動作の詳細については、 きめ細かい権限をご覧ください。
enable_serial_consent 非推奨。設定しても効果はありません。同意の動作の詳細については、 きめ細かい権限をご覧ください。
login_hint 省略可。アプリがリクエストを承認するユーザーを把握している場合は、このプロパティを使用して Google にログインヒントを提供できます。正常に完了すると、アカウントの選択はスキップされます。対象ユーザーのメールアドレスまたは ID トークンの sub フィールド値。詳細については、OpenID Connect ドキュメントの login_hint フィールドをご覧ください。
hd 省略可。アプリケーションがユーザーが属する Workspace ドメインを把握している場合は、この情報を Google にヒントとして提供します。成功すると、ユーザー アカウントは指定されたドメインに限定されるか、そのドメイン用に事前選択されます。詳細については、OpenID Connect ドキュメントの hd フィールドをご覧ください。
ux_mode 省略可。認可フローに使用する UX モード。デフォルトでは、同意フローがポップアップで開きます。有効な値は popup と redirect です。
select_account 省略可。デフォルトは 'false' です。アカウントの選択を求めるブール値。
error_callback 省略可。OAuth 以外のエラー（ポップアップ ウィンドウが開かない、OAuth レスポンスが返される前に閉じられるなど）を処理する JavaScript 関数。

入力パラメータの「type」フィールドに詳細な理由が示されます。
  • popup_failed_to_open ポップアップ ウィンドウを開けませんでした。
  • popup_closed OAuth レスポンスが返される前にポップアップ ウィンドウが閉じられました。
  • unknown 他のエラーのプレースホルダ。

データ型: CodeClient

このクラスには、OAuth 2.0 コード UX フローを開始するパブリック メソッド requestCode が 1 つだけあります。

interface CodeClient {
  requestCode(): void;
}

データ型: CodeResponse

CodeResponse JavaScript オブジェクトがポップアップ UX の callback メソッドに渡されます。リダイレクト UX では、CodeResponse が URL パラメータとして渡されます。

次の表に、CodeResponse データ型のプロパティを示します。

プロパティ
code 成功したトークン レスポンスの認証コード。
scope ユーザーが承認したスコープのスペース区切りのリスト。
state アプリケーションが認可リクエストとレスポンスの間で状態を維持するために使用する文字列値。
error 1 つの ASCII エラーコード。
error_description 追加情報を提供する判読可能な ASCII テキスト。発生したエラーをクライアント デベロッパーが理解するのに役立ちます。
error_uri エラーに関する情報が記載された人間が判読できるウェブページを識別する URI。クライアント デベロッパーにエラーに関する追加情報を提供するために使用されます。

メソッド: google.accounts.oauth2.initTokenClient

initTokenClient メソッドは、パラメータの構成を使用してトークン クライアントを初期化して返します。

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

データ型: TokenClientConfig

次の表に、TokenClientConfig データ型のプロパティを示します。

プロパティ
client_id 必須。アプリケーションのクライアント ID。この値は API Console で確認できます。
callback 必須。返されたトークン レスポンスを処理する JavaScript 関数。
scope 必須。アプリケーションがユーザーの代わりにアクセスできるリソースを特定するスコープのスペース区切りのリストです。これらの値は、Google がユーザーに表示する同意画面に反映されます。
include_granted_scopes 省略可。デフォルトは true です。アプリが段階的認可を使用して、コンテキスト内で追加のスコープへのアクセスをリクエストできるようにします。このパラメータの値を false に設定し、認可リクエストが承認された場合、新しいアクセス トークンは、この TokenClientConfig で scope がリクエストしたスコープにのみ適用されます。
prompt 省略可。デフォルトは 'select_account' です。ユーザーに表示するプロンプトのスペース区切りのリスト（大文字と小文字が区別されます）。指定できる値は次のとおりです。
  • 空の文字列 アプリがアクセス権をリクエストするのは、初めてアクセス権をリクエストしたときのみです。他の値で指定することはできません。
  • none: 認証画面や同意画面は表示されません。他の値と指定しないでください。
  • consent: ユーザーに同意を求めます。
  • 'select_account' アカウントを選択するようユーザーに求めるプロンプト。
enable_granular_consent 非推奨。設定しても効果はありません。同意の動作の詳細については、 きめ細かい権限をご覧ください。
enable_serial_consent 非推奨。設定しても効果はありません。同意の動作の詳細については、 きめ細かい権限をご覧ください。
login_hint 省略可。アプリがリクエストを承認するユーザーを把握している場合は、このプロパティを使用して Google にログインヒントを提供できます。正常に完了すると、アカウントの選択はスキップされます。対象ユーザーのメールアドレスまたは ID トークンの sub フィールド値。詳細については、OpenID Connect ドキュメントの login_hint フィールドをご覧ください。
hd 省略可。アプリケーションがユーザーが属する Workspace ドメインを把握している場合は、この情報を使用して Google にヒントを提供します。成功すると、ユーザー アカウントは指定されたドメインに限定されるか、そのドメイン用に事前選択されます。詳細については、OpenID Connect ドキュメントの hd フィールドをご覧ください。
state 省略可。非推奨。認可リクエストと認可サーバーのレスポンス間で状態を維持するために、アプリケーションが使用する文字列値を指定します。
error_callback 省略可。OAuth 以外のエラー（ポップアップ ウィンドウが開かない、OAuth レスポンスが返される前に閉じられるなど）を処理する JavaScript 関数。

入力パラメータの「type」フィールドに詳細な理由が示されます。
  • popup_failed_to_open ポップアップ ウィンドウを開けませんでした。
  • popup_closed OAuth レスポンスが返される前にポップアップ ウィンドウが閉じられました。
  • unknown 他のエラーのプレースホルダ。

データ型: TokenClient

このクラスには、OAuth 2.0 トークンの UX フローを開始する公開メソッド requestAccessToken が 1 つだけあります。

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
引数
overrideConfig OverridableTokenClientConfig 省略可。このメソッドでオーバーライドする構成。

データ型: OverridableTokenClientConfig

次の表に、OverridableTokenClientConfig データ型のプロパティを示します。

プロパティ
scope 省略可。アプリケーションがユーザーに代わってアクセスできるリソースを識別するスコープのスペース区切りリスト。これらの値は、Google がユーザーに表示する同意画面に通知されます。
include_granted_scopes 省略可。デフォルトは true です。アプリが段階的認可を使用して、コンテキスト内で追加のスコープへのアクセスをリクエストできるようにします。このパラメータの値を false に設定し、認可リクエストが承認された場合、新しいアクセス トークンは、この OverridableTokenClientConfig で scope がリクエストしたスコープにのみ適用されます。
prompt 省略可。ユーザーに表示するプロンプトのスペース区切りのリスト（大文字と小文字が区別されます）。
enable_granular_consent 非推奨。設定しても効果はありません。同意の動作の詳細については、 きめ細かい権限をご覧ください。
enable_serial_consent 非推奨。設定しても効果はありません。同意の動作の詳細については、 きめ細かい権限をご覧ください。
login_hint 省略可。アプリがリクエストを承認するユーザーを把握している場合は、このプロパティを使用して Google にログインヒントを提供できます。正常に完了すると、アカウントの選択はスキップされます。対象ユーザーのメールアドレスまたは ID トークンの sub フィールド値。詳細については、OpenID Connect ドキュメントの login_hint フィールドをご覧ください。
state 省略可。非推奨。認可リクエストと認可サーバーのレスポンス間で状態を維持するために、アプリケーションが使用する文字列値を指定します。

データ型: TokenResponse

TokenResponse JavaScript オブジェクトがポップアップ UX のコールバック メソッドに渡されます。

次の表に、TokenResponse データ型のプロパティを示します。

プロパティ
access_token 成功したトークン レスポンスのアクセス トークン。
expires_in アクセス トークンの有効期間（秒単位）。
hd ログインしたユーザーが属するホストドメイン。
prompt TokenClientConfig または OverridableTokenClientConfig で指定された値のリストから使用されたプロンプト値。
token_type 発行されたトークンのタイプ。
scope ユーザーが承認したスコープのスペース区切りのリスト。
state アプリケーションが認可リクエストとレスポンスの間で状態を維持するために使用する文字列値。
error 1 つの ASCII エラーコード。
error_description 追加情報を提供する人間が判読可能な ASCII テキスト。発生したエラーをクライアント デベロッパーが理解するのに役立ちます。
error_uri エラーに関する情報が記載された人間が判読できるウェブページを識別する URI。クライアント デベロッパーにエラーに関する追加情報を提供するために使用されます。

メソッド: google.accounts.oauth2.hasGrantedAllScopes

ユーザーが指定されたスコープをすべて付与しているかどうかを確認します。

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
引数
tokenResponse TokenResponse 必須。TokenResponse オブジェクト。
firstScope 文字列 必須。確認するスコープ。
restScopes string[] 省略可。確認すべきその他のスコープ。
戻り値
ブール値 すべてのスコープが付与されている場合は true です。

メソッド: google.accounts.oauth2.hasGrantedAnyScope

ユーザーが指定されたスコープを付与したかどうかを確認します。

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
引数
tokenResponse TokenResponse 必須。TokenResponse オブジェクト。
firstScope 文字列 必須。確認するスコープ。
restScopes string[] 省略可。確認すべきその他のスコープ。
戻り値
ブール値 いずれかのスコープが付与されている場合、true。

メソッド: google.accounts.oauth2.revoke

revoke メソッドは、ユーザーがアプリに付与したすべてのスコープを取り消します。権限を取り消すには、有効なアクセス トークンが必要です。

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
引数
accessToken 文字列 必須。有効なアクセス トークン。
callback 関数 省略可。RevocationResponse ハンドラ。

データ型: RevocationResponse

RevocationResponse JavaScript オブジェクトがコールバック メソッドに渡されます。

次の表に、RevocationResponse データ型のプロパティを示します。

プロパティ
successful ブール値。成功した場合は true、失敗した場合は false。
error 文字列。成功した場合は未定義です。1 つの ASCII エラーコード。これには、標準の OAuth 2.0 エラーコードが含まれますが、これらに限定されません。revoke メソッドの一般的なエラー:
  • invalid_token - revoke メソッドが呼び出される前に、トークンがすでに期限切れまたは取り消されている。ほとんどの場合、accessToken に関連付けられている権限は取り消されたと見なすことができます。
  • invalid_request - トークンは取り消せません。accessToken が有効な Google OAuth 2.0 認証情報であることを確認する必要があります。
error_description 文字列。成功した場合は未定義です。人が読める ASCII テキストは、error プロパティに関する追加情報を提供します。デベロッパーは、この情報を使用して発生したエラーを詳しく把握できます。error_description 文字列は英語のみです。 error に記載されている一般的なエラーの場合、対応する error_description は次のとおりです。
  • invalid_token - トークンが期限切れまたは取り消されています。
  • invalid_request - トークンは取り消せません。