ウェブサイト向け Google 第三者認証 JavaScript ライブラリ - API リファレンス

このリファレンスでは、Google 3P Authorization JavaScript Library 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 サーバーがユーザーをリダイレクトする場所を指定します。値は OAuth 2.0 クライアントの承認済みリダイレクト URI のいずれかと完全に一致している必要があります。これは、API Console で構成し、リダイレクト URI 検証ルールに従う必要があります。このプロパティはポップアップ UX で無視されます。
callback ポップアップ UX では必須。返されたコード レスポンスを処理する JavaScript 関数。リダイレクト UX ではプロパティは無視されます。
state (省略可)リダイレクト UX に推奨。アプリケーションが認証リクエストと認可サーバーのレスポンスとの間の状態を維持するために使用する文字列値を指定します。
enable_granular_consent 省略可。デフォルトは true です。false に設定すると、2019 年より前に作成された OAuth クライアント ID については、より詳細な Google アカウントの権限が無効になります。enable_granular_consentenable_serial_consent の両方が設定されている場合、enable_granular_consent 値のみが有効になり、enable_serial_consent 値は無視されます。

よりきめ細かい権限が常に有効になるため、新しい OAuth クライアント ID には影響しません。
enable_serial_consent 非推奨。代わりに enable_granular_consent を使用してください。これは enable_granular_consent と同じ効果があります。enable_serial_consent を使用する既存のアプリでは引き続き使用できますが、次のアプリケーション更新で enable_granular_consent を使用するようにコードを更新することをおすすめします。
login_hint (省略可)どのユーザーがリクエストを認証すべきかがアプリケーションにわかっている場合は、このプロパティを使用して Google にログインヒントを提供できます。成功すると、アカウントの選択がスキップされます。対象ユーザーのメールアドレスまたは ID トークンの sub フィールド値。詳細については、OpenID Connect ドキュメントの login_hint フィールドをご覧ください。
hd (省略可)ユーザーの Workspace ドメインがアプリケーションでわかっている場合は、これを使用して Google にヒントを提供してください。成功した場合、ユーザー アカウントは提供されたドメインに限定されるか、事前に選択されます。 詳細については、OpenID Connect ドキュメントの hd フィールドをご覧ください。
ux_mode (省略可)承認フローに使用する UX モード。デフォルトでは、同意フローがポップアップ表示されます。有効な値は popupredirect です。
select_account これは省略可能で、デフォルトは 'false' です。ユーザーにアカウントの選択を促すブール値。
error_callback (省略可)OAuth 以外のエラー(ポップアップ ウィンドウなど)を処理する JavaScript 関数が開かなかったり、OAuth レスポンスが返される前に閉じたりします。

入力パラメータの「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 単一の 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 省略可。デフォルトは true です。false に設定すると、2019 年より前に作成された OAuth クライアント ID については、より詳細な Google アカウントの権限が無効になります。enable_granular_consentenable_serial_consent の両方が設定されている場合、enable_granular_consent 値のみが有効になり、enable_serial_consent 値は無視されます。

よりきめ細かい権限が常に有効になるため、新しい OAuth クライアント ID には影響しません。
enable_serial_consent 非推奨。代わりに enable_granular_consent を使用してください。これは enable_granular_consent と同じ効果があります。enable_serial_consent を使用する既存のアプリでは引き続き使用できますが、次のアプリケーション更新で enable_granular_consent を使用するようにコードを更新することをおすすめします。
login_hint (省略可)どのユーザーがリクエストを認証すべきかがアプリケーションにわかっている場合は、このプロパティを使用して Google にログインヒントを提供できます。成功すると、アカウントの選択がスキップされます。対象ユーザーのメールアドレスまたは ID トークンの sub フィールド値。詳細については、OpenID Connect ドキュメントの login_hint フィールドをご覧ください。
hd (省略可)ユーザーの Workspace ドメインがアプリケーションでわかっている場合は、これを使用して Google にヒントを提供してください。成功した場合、ユーザー アカウントは提供されたドメインに限定されるか、事前に選択されます。 詳細については、OpenID Connect ドキュメントの hd フィールドをご覧ください。
state (省略可)非推奨。アプリケーションが認証リクエストと認可サーバーのレスポンスとの間の状態を維持するために使用する文字列値を指定します。
error_callback (省略可)OAuth 以外のエラー(ポップアップ ウィンドウなど)を処理する JavaScript 関数が開かなかったり、OAuth レスポンスが返される前に閉じたりします。

入力パラメータの「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 省略可。デフォルトは true です。false に設定すると、2019 年以前に作成された OAuth クライアント ID ではよりきめ細かい Google アカウントの権限が無効になります。enable_granular_consentenable_serial_consent の両方が設定されている場合、enable_granular_consent 値のみが有効になり、enable_serial_consent 値は無視されます。

よりきめ細かい権限が常に有効になるため、新しい OAuth クライアント ID には影響しません。
enable_serial_consent 非推奨。代わりに enable_granular_consent を使用してください。これは enable_granular_consent と同じ効果があります。enable_serial_consent を使用する既存のアプリでは引き続き使用できますが、次のアプリケーション更新で enable_granular_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 単一の 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 string 必須。確認するスコープ。
restScopes string[] (省略可)確認するその他のスコープ。
戻り値
ブール値 すべてのスコープが付与されている場合は True。

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

ユーザーが指定したスコープのいずれかまたは両方を許可したかどうかを確認します。

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
引数
tokenResponse TokenResponse 必須。TokenResponse オブジェクト。
firstScope string 必須。確認するスコープ。
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 文字列。成功時に未定義。単一の 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 - トークンは取り消しできません。