本參考資料說明 Google 第三方授權 JavaScript 程式庫 API,可用來從 Google 載入授權碼或存取權杖。
方法:google.accounts.oauth2.initCodeClient
initCodeClient
方法會使用參數中的設定來初始化並傳回程式碼用戶端。
google.accounts.oauth2.initCodeClient(config: CodeClientConfig)
資料類型:CodeClientConfig
下表列出 CodeClientConfig
資料類型的屬性。
屬性 | |
---|---|
client_id
|
必要。應用程式的用戶端 ID。您可以在 API 控制台中找到這個值。 |
scope
|
必要。以空格分隔的範圍清單,用於識別應用程式可代表使用者存取的資源。這些值會指示 Google 向使用者顯示的同意畫面。 |
include_granted_scopes |
選用,預設為 true 。可讓應用程式使用漸進式授權,在相關情境中要求存取其他範圍。如果您將此參數值設為 false ,且系統已獲授權要求,則新的存取權杖只會涵蓋 scope 在這個 CodeClientConfig 中要求的所有範圍。 |
redirect_uri
|
必須提供重新導向使用者體驗。決定使用者完成授權流程後,API 伺服器會將使用者重新導向的位置。這個值必須與您在 API 控制台中設定的 OAuth 2.0 用戶端的其中一個已授權重新導向 URI 完全相符,且必須符合我們的 重新導向 URI 驗證規則。彈出式視窗使用者體驗會忽略該屬性。 |
callback |
必填。處理傳回程式碼回應的 JavaScript 函式。重新導向使用者體驗會忽略該屬性。 |
state |
選用設定。建議用於重新導向使用者體驗。指定應用程式用來維持授權要求和授權伺服器回應之間狀態的任何字串值。 |
enable_granular_consent |
選用,預設為 true 。如果設為「false 」,2019 年之前建立的 OAuth 用戶端 ID 就會停用更精細的 Google 帳戶權限。如果同時設定 enable_granular_consent 和 enable_serial_consent ,系統只會套用 enable_granular_consent 值,並忽略 enable_serial_consent 值。不適用於較新的 OAuth 用戶端 ID,因為系統一律會為較新的 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 |
選用設定。用於授權流程的使用者體驗模式。根據預設,系統會在彈出式視窗中開啟同意聲明流程。有效值為 popup 和 redirect 。 |
select_account |
選用,預設為 'false'。用於提示使用者選取帳戶的布林值。 |
error_callback |
選用設定。處理部分非 OAuth 錯誤的 JavaScript 函式 (例如彈出式視窗) 無法開啟,或是在傳回 OAuth 回應前關閉。 輸入參數的「type」欄位會提供詳細原因。
|
資料類型:CodeClient
這個類別只有一個公開方法 requestCode,可啟動 OAuth 2.0 程式碼使用者體驗流程。
interface CodeClient {
requestCode(): void;
}
資料類型:CodeResponse
系統會在彈出式使用者體驗中將 CodeResponse
JavaScript 物件傳遞至 callback
方法。在重新導向使用者體驗中,CodeResponse
會以網址參數的形式傳遞。
下表列出 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 控制台中找到這個值。 |
callback |
必要。處理傳回權杖回應的 JavaScript 函式。 |
scope |
必要。以空格分隔的範圍清單,用於識別應用程式可代表使用者存取的資源。這些值會指示 Google 向使用者顯示的同意畫面。 |
include_granted_scopes |
選用,預設為 true 。可讓應用程式使用漸進式授權,在相關情境中要求存取其他範圍。如果您將此參數值設為 false ,且系統已獲授權要求,則新的存取權杖只會涵蓋 scope 在這個 TokenClientConfig 中要求的所有範圍。 |
prompt |
選用,預設為 'select_account'。以空格分隔且區分大小寫的提示清單。可能的值包括:
|
enable_granular_consent |
選用,預設為 true 。如果設為「false 」,2019 年之前建立的 OAuth 用戶端 ID 就會停用更精細的 Google 帳戶權限。如果同時設定 enable_granular_consent 和 enable_serial_consent ,系統只會套用 enable_granular_consent 值,並忽略 enable_serial_consent 值。不適用於較新的 OAuth 用戶端 ID,因為系統一律會為較新的 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」欄位會提供詳細原因。
|
資料類型:TokenClient
該類別只有一個公開方法 requestAccessToken
,可啟動 OAuth 2.0 權杖使用者體驗流程。
interface TokenClient {
requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
引數 | ||
---|---|---|
overrideConfig |
OverridableTokenClientConfig | 選用設定。這個方法中要覆寫的設定。 |
資料類型:OverridableTokenClientConfig
下表列出 OverridableTokenClientConfig
資料類型的屬性。
屬性 | |
---|---|
scope |
選用設定。以空格分隔的範圍清單,用於識別應用程式可代表使用者存取的資源。這些值會通知 Google 向使用者顯示的同意畫面。 |
include_granted_scopes |
選用,預設為 true 。可讓應用程式使用漸進式授權,在相關情境中要求存取其他範圍。如果您將此參數值設為 false ,且系統已獲授權要求,則新的存取權杖只會涵蓋 scope 在這個 OverridableTokenClientConfig 中要求的所有範圍。 |
prompt |
選用設定。以空格分隔且區分大小寫的提示清單。 |
enable_granular_consent |
選用,預設為 true 。如果設為 false ,系統會為 2019 年之前建立的 OAuth 用戶端 ID 停用更精細的 Google 帳戶權限。如果同時設定 enable_granular_consent 和 enable_serial_consent ,則系統只會套用 enable_granular_consent 值,並忽略 enable_serial_consent 值。不適用於較新的 OAuth 用戶端 ID,因為系統一律會為較新的 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 物件將會在彈出式使用者體驗中傳遞至回呼方法。
下表列出 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 |
字串 | 必要。要檢查的範圍。 |
restScopes |
string[] | 選用設定。要檢查的其他範圍。 |
傳回 | |
---|---|
boolean | 如果授予所有範圍,則為「是」。 |
方法:google.accounts.oauth2.hasGrantedAnyScope
檢查使用者是否授予任何指定範圍或範圍。
google.accounts.oauth2.hasGrantedAnyScope(
tokenResponse: TokenResponse,
firstScope: string, ...restScopes: string[]
): boolean;
引數 | ||
---|---|---|
tokenResponse |
TokenResponse
|
必要。TokenResponse 物件。 |
firstScope |
字串 | 必要。要檢查的範圍。 |
restScopes |
string[] | 選用設定。要檢查的其他範圍。 |
傳回 | |
---|---|
boolean | 如果已授予任何範圍,則為「是」。 |
方法: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 方法的常見錯誤:
|
error_description |
字串。成功時未定義。使用者可理解的 ASCII 文字提供有關 error 屬性的額外資訊。開發人員可以藉此進一步瞭解發生的錯誤。error_description 字串目前僅支援英文。如要查看 error 中列出的常見錯誤,請參閱對應的 error_description :
|