Google致力於提高黑人社區的種族平等。 怎麼看。
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

適用於移動和桌面應用程序的OAuth 2.0

本文檔說明了在手機,平板電腦和計算機等設備上安裝的應用程序如何使用Google的OAuth 2.0端點來授權對Google API的訪問。

OAuth 2.0允許用戶與應用程序共享特定數據,同時將用戶名,密碼和其他信息保密。例如,應用程序可以使用OAuth 2.0獲得用戶的許可,以將文件存儲在其Google雲端硬盤中。

已安裝的應用程序被分發到各個設備,並且假定這些應用程序不能保守秘密。當用戶出現在應用程序中或應用程序在後台運行時,他們可以訪問Google API。

此授權流程類似於用於Web服務器應用程序的授權流程。主要區別在於已安裝的應用程序必須打開系統瀏覽器並提供本地重定向URI,以處理來自Google授權服務器的響應。

備擇方案

對於移動應用程序,您可能希望使用適用於AndroidiOS的Google登錄。 Google登錄客戶端庫處理身份驗證和用戶授權,它們可能比此處描述的低級協議更易於實現。

對於在不支持系統瀏覽器或輸入功能受限的設備(例如電視,遊戲機,相機或打印機)上運行的應用程序,請參閱用於電視和設備的OAuth 2.0用於設備的Google登錄

圖書館和样品

我們建議使用以下庫和示例,以幫助您實現本文檔中描述的OAuth 2.0流程:

先決條件

為您的項目啟用API

任何調用Google API的應用程序都需要在API Console中啟用這些API。

為您的項目啟用API:

  1. Google API Console中的Open the API Library
  2. If prompted, select a project, or create a new one.
  3. API Library列出了所有可用的API,並按產品系列和受歡迎程度分組。如果您要啟用的API在列表中不可見,請使用搜索找到它,或單擊其所屬產品系列中的“查看全部”。
  4. 選擇要啟用的API,然後單擊“啟用”按鈕。
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

創建授權憑證

使用OAuth 2.0訪問Google API的任何應用程序都必須具有授權憑據,以將應用程序標識到Google的OAuth 2.0服務器。以下步驟說明瞭如何為您的項目創建憑據。然後,您的應用程序可以使用憑據來訪問為該項目啟用的API。

  1. Go to the Credentials page.
  2. 點擊創建憑據> OAuth客戶端ID
  3. 以下各節介紹了Google授權服務器支持的客戶端類型和重定向方法。選擇適合您的應用程序的客戶端類型,命名OAuth客戶端,然後在表格中適當設置其他字段。

自定義URI方案(Android,iOS,UWP)

對於Android應用程序,iOS應用程序和通用Windows平台(UWP)應用程序,建議使用自定義URI方案。

安卓
  1. 選擇Android應用程序類型。
  2. 輸入OAuth客戶端的名稱。此名稱顯示在項目的Credentials page上以標識客戶端。
  3. 輸入您的Android應用的軟件包名稱。此值在應用清單文件中<manifest>元素package屬性中定義。
  4. 輸入應用程序分發版本的SHA-1簽名證書指紋。
    • 如果您的應用使用Google Play進行的應用簽名,請從Play控制台的應用簽名頁面複製SHA-1指紋。
    • 如果您管理自己的密鑰庫和簽名密鑰,請使用Java附帶的keytool實用程序以人類可讀的格式打印證書信息。將SHA1值複製到keytool輸出的“ Certificate fingerprints部分中。有關更多信息,請參閱Google APIs for Android文檔中的身份驗證客戶端
  5. 點擊創建
的iOS
  1. 選擇iOS應用程序類型。
  2. 輸入OAuth客戶端的名稱。此名稱顯示在項目的Credentials page上以標識客戶端。
  3. 輸入您的應用程序的捆綁包標識符。捆綁包ID是應用程序的信息屬性列表資源文件( info.plist )中CFBundleIdentifier鍵的值。該值最通常顯示在Xcode項目編輯器的“常規”窗格或“簽名和功能”窗格中。捆綁軟件ID也顯示在Apple的App Store Connect網站上該應用程序的“應用程序信息”頁面的“常規信息”部分中。
  4. (可選的)

    如果該應用程序已在Apple的App Store中發布,請輸入您的應用程序的App Store ID。商店ID是每個Apple App Store URL中包含的數字字符串。

    1. 在iOS或iPadOS設備上打開Apple App Store應用程序
    2. 搜索您的應用。
    3. 選擇共享按鈕(方形和向上箭頭符號)。
    4. 選擇複製鏈接
    5. 將鏈接粘貼到文本編輯器中。 App Store ID是URL的最後一部分。

      示例: https://apps.apple.com/app/google/id 284815942

  5. (可選的)

    輸入您的團隊ID。有關更多信息,請參閱Apple Developer Account文檔中的“ 找到您的團隊ID”

  6. 點擊創建
超寬工作計劃
  1. 選擇通用Windows平台應用程序類型。
  2. 輸入OAuth客戶端的名稱。此名稱顯示在項目的Credentials page上以標識客戶端。
  3. 輸入應用程序的12個字符的Microsoft Store ID。您可以在“應用程序管理”部分的“ 應用程序標識”頁面上的Microsoft合作夥伴中心中找到此值。
  4. 點擊創建

對於UWP應用,自定義URI方案不能超過39個字符。

回送IP地址(macOS,Linux,Windows桌面)

要使用此URL接收授權代碼,您的應用程序必須在本地Web服務器上進行偵聽。在許多(但不是全部)平台上,這是可能的。但是,如果您的平台支持它,則這是獲取授權代碼的推薦機制。

當您的應用收到授權響應時,為了獲得最佳可用性,它應該通過顯示一個HTML頁面來響應,該頁面指示用戶關閉瀏覽器並返回到您的應用。

推薦用法macOS,Linux和Windows桌面(而非通用Windows平台)應用
表單值將應用程序類型設置為桌面應用程序

手動複製/粘貼

程序提取

確定訪問範圍

範圍使您的應用程序僅可以請求訪問其所需的資源,同時還使用戶能夠控制他們授予您的應用程序的訪問量。因此,請求的範圍數與獲得用戶同意的可能性之間可能存在反比關係。

在開始實施OAuth 2.0授權之前,我們建議您確定您的應用需要訪問權限的範圍。

OAuth 2.0 API範圍文檔包含您可以用來訪問Google API的範圍的完整列表。

獲取OAuth 2.0訪問令牌

以下步驟顯示了您的應用程序如何與Google的OAuth 2.0服務器進行交互以獲取用戶的同意,以代表用戶執行API請求。您的應用必須先獲得同意,然後才能執行需要用戶授權的Google API請求。

步驟1:產生程式碼驗證器和質詢

Google支持代碼交換證明密鑰(PKCE)協議,以使安裝的應用程序流程更安全。為每個授權請求創建一個唯一的代碼驗證器,並將其轉換後的值稱為“ code_challenge”發送到授權服務器以獲取授權代碼。

創建代碼驗證器

code_verifier是使用非保留字符[AZ] / [az] / [0-9] /“-” /“”的高熵密碼隨機字符串。 /“ _” /“〜”,最小長度為43個字符,最大長度為128個字符。

代碼驗證程序應具有足夠的熵,以使其無法猜測該值。

創建代碼挑戰

支持兩種創建代碼質詢的方法。

代碼挑戰生成方法
S256(推薦)代碼挑戰是代碼驗證程序的Base64URL(無填充)編碼的SHA256哈希。
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
清楚的代碼質詢與上面生成的代碼驗證器的值相同。
code_challenge = code_verifier

第2步:將請求發送到Google的OAuth 2.0服務器

要獲得用戶授權,請通過https://accounts.google.com/o/oauth2/v2/auth向Google的授權服務器發送請求。該端點處理活動會話查找,認證用戶並獲得用戶同意。只能通過SSL訪問該端點,並且它拒絕HTTP(非SSL)連接。

授權服務器支持以下針對已安裝應用程序的查詢字符串參數:

參數
client_id必需的

您的應用程序的客戶端ID。您可以在API Console Credentials page中找到該值。

redirect_uri必需的

確定Google的授權服務器如何將響應發送到您的應用。有幾個重定向選項可用於已安裝的應用程序,並且您將在設置授權憑證時考慮到特定的重定向方法。

該值必須與您在客戶端的API Console Credentials page中配置的OAuth 2.0客戶端的授權重定向重定向URI之一完全匹配。如果此值與授權的URI不匹配,則會收到redirect_uri_mismatch錯誤。

下表顯示了每種方法的適當的redirect_uri參數值:

redirect_uri
自定義URI方案com.example.app : redirect_uri_path

或者

com.googleusercontent.apps.123 : redirect_uri_path
  • com.example.app是您所控制的域的反向DNS表示法。自定義方案必須包含一個有效期限。
  • com.googleusercontent.apps.123是客戶端ID的反向DNS表示法。
  • redirect_uri_path是可選的路徑組件,例如/oauth2redirect 。請注意,該路徑應以單個斜杠開頭,該斜杠與常規HTTP URL不同。
環回IP地址http://127.0.0.1: porthttp://[::1]: port

在平台上查詢相關的回送IP地址,並在隨機可用端口上啟動HTTP偵聽器。用您的應用程序偵聽的實際端口號替換port

手動複製/粘貼urn:ietf:wg:oauth:2.0:oob
程序提取urn:ietf:wg:oauth:2.0:oob:auto
response_type必需的

確定Google OAuth 2.0端點是否返回授權碼。

將參數值設置為已安裝應用程序的code

scope必需的

用空格分隔的範圍列表,這些範圍標識應用程序可以代表用戶訪問的資源。這些值將告知Google向用戶顯示的同意屏幕。

範圍使您的應用程序僅可以請求訪問其所需的資源,同時還使用戶能夠控制他們授予您的應用程序的訪問量。因此,在所請求範圍的數量與獲得用戶同意的可能性之間存在反比關係。

code_challenge受到推崇的

指定一個編碼的code_verifier ,它將在授權代碼交換期間用作服務器端質詢。此參數必須與上述code_challenge參數一起使用。有關更多信息,請參見上面的創建代碼挑戰部分。

code_challenge_method受到推崇的

指定在授權代碼交換期間將使用哪種方法對code_verifier進行編碼。此參數必須與code_challenge參數一起使用。如果在包含code_challenge的請求中不存在code_challenge_method的值,則默認為plain code_challenge 。此參數僅支持的值為S256plain

state受到推崇的

指定應用程序用來維護授權請求和授權服務器的響應之間的狀態的任何字符串值。在用戶同意或拒絕您的應用程序的訪問請求之後,服務器會在redirect_uri的URL片段標識符( # )中返回您作為name=value對發送的確切值。

您可以將此參數用於多種目的,例如將用戶定向到應用程序中的正確資源,發送隨機數以及減輕跨站點請求偽造。由於您可以猜測您的redirect_uri ,因此使用state值可以增加您對傳入連接是身份驗證請求的結果的保證。如果您生成隨機字符串或對Cookie的哈希值或其他捕獲客戶端狀態的值進行編碼,則可以驗證響應以進一步確保請求和響應源自同一瀏覽器,從而提供針對跨站點等攻擊的防護要求偽造。有關如何創建和確認state令牌的示例,請參見OpenID Connect文檔。

login_hint可選的

如果您的應用程序知道哪個用戶正在嘗試進行身份驗證,則可以使用此參數向Google身份驗證服務器提供提示。服務器通過預填寫登錄表單中的電子郵件字段或通過選擇適當的多登錄會話來使用提示來簡化登錄流程。

將參數值設置為電子郵件地址或sub標識符,與用戶的Google ID等效。

授權URL樣本

下面的標籤顯示了不同重定向URI選項的示例授權URL。

redirect_uri參數的值外,其他URL相同。這些URL還包含必需的response_typeclient_id參數以及可選的state參數。每個URL都包含換行符和空格,以提高可讀性。

自定義URI方案

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

環回IP地址

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

複製粘貼

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&
 client_id=client_id

程序提取

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
 client_id=client_id

第3步:Google提示用戶同意

在此步驟中,用戶決定是否向您的應用程序授予所請求的訪問權限。在此階段,Google將顯示一個同意窗口,其中顯示您的應用程序的名稱以及它請求使用用戶的授權憑證進行訪問的Google API服務以及要授予的訪問範圍的摘要。然後,用戶可以同意授予對您的應用程序請求的一個或多個範圍的訪問權限,或拒絕該請求。

您的應用程序在此階段不需要執行任何操作,因為它等待來自Google的OAuth 2.0服務器的響應(指示是否已授予任何訪問權限)。該響應將在以下步驟中進行說明。

步驟4:處理OAuth 2.0服務器響應

您的應用程序接收授權響應的方式取決於它使用的重定向URI方案。無論採用哪種方案,響應都將包含授權碼( code )或錯誤( error )。例如, error=access_denied表示用戶拒絕了該請求。

如果用戶授予對您的應用程序的訪問權限,則可以按照下一步中的說明,將授權代碼交換為訪問令牌和刷新令牌。

步驟5:將授權代碼交換為刷新和訪問令牌

要交換訪問令牌的授權代碼,請調用https://oauth2.googleapis.com/token端點並設置以下參數:

領域
client_id從API Console Credentials page獲得的客戶端ID。
client_secret從API Console Credentials page獲得的客戶端密鑰。
code從初始請求返回的授權碼。
code_verifier您在步驟1中創建的代碼驗證程序。
grant_type根據OAuth 2.0規範中的定義,該字段的值必須設置為authorization_code
redirect_uri給定client_id的API Console Credentials page中為您的項目列出的重定向URI之一。

以下代碼段顯示了一個示例請求:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
grant_type=authorization_code

Google通過返回一個JSON對象來響應此請求,該對象包含一個短暫的訪問令牌和一個刷新令牌。

響應包含以下字段:

領域
access_token您的應用程序發送的用於授權Google API請求的令牌。
expires_in訪問令牌的剩餘生存時間(以秒為單位)。
id_token注意:僅當您的請求包含身份範圍(例如openidprofileemail ,才返回此屬性。該值是一個JSON Web令牌(JWT),其中包含有關用戶的經過數字簽名的身份信息。
refresh_token可用於獲取新的訪問令牌的令牌。刷新令牌在用戶撤銷訪問權限之前一直有效。請注意,始終為安裝的應用程序返回刷新令牌。
scope access_token授予的訪問範圍以空格分隔,區分大小寫的字符串列表表示。
token_type返回的令牌類型。目前,此字段的值始終設置為Bearer

以下代碼段顯示了示例響應:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

調用Google API

您的應用程序獲取訪問令牌後,如果已授予該API所需的訪問範圍,則可以使用該令牌代表給定的用戶帳戶對Google API進行調用。為此,請通過包含access_token查詢參數或Authorization HTTP標頭Bearer值,在對API的請求中包含訪問令牌。盡可能使用HTTP標頭,因為查詢字符串在服務器日誌中趨於可見。在大多數情況下,您可以使用客戶端庫來設置對Google API的調用(例如,在調用Drive Files API時)。

您可以在OAuth 2.0 Playground試用所有Google API並查看其範圍。

HTTP GET示例

使用Authorization: Bearer HTTP標頭對drive.files端點(Drive Files API)的調用可能如下所示。請注意,您需要指定自己的訪問令牌:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

這是使用access_token查詢字符串參數對已驗證用戶使用相同API的調用:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl例子

您可以使用curl命令行應用程序測試這些命令。這是使用HTTP標頭選項(首選)的示例:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

或者,或者查詢字符串參數選項:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

刷新訪問令牌

訪問令牌會定期過期,並成為相關API請求的無效憑據。如果您請求脫機訪問與令牌關聯的範圍,則可以刷新訪問令牌而無需提示用戶許可(包括當用戶不存在時)。

要刷新訪問令牌,您的應用程序將HTTPS POST請求發送到Google的授權服務器( https://oauth2.googleapis.com/token ),該請求包含以下參數:

領域
client_idAPI Console獲得的客戶端ID。
client_secretAPI Console獲得的客戶機密。 ( client_secret不適用於來自註冊為Android,iOS或Chrome應用程序的客戶端的請求。)
grant_type根據OAuth 2.0規範中的定義,此字段的值必須設置為refresh_token
refresh_token從授權代碼交換返回的刷新令牌。

以下代碼段顯示了一個示例請求:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

只要用戶尚未撤消授予該應用程序的訪問權限,令牌服務器就會返回一個包含新訪問令牌的JSON對象。以下代碼段顯示了示例響應:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

請注意,對將要發出的刷新令牌的數量有限制;每個客戶/用戶組合一個限制,所有客戶中每個用戶一個限制。您應該將刷新令牌保存在長期存儲中,並在它們仍然有效的情況下繼續使用它們。如果您的應用程序請求太多刷新令牌,則可能會遇到這些限制,在這種情況下,較早的刷新令牌將停止工作。

吊銷令牌

在某些情況下,用戶可能希望撤消對應用程序的訪問權限。用戶可以通過訪問“帳戶設置”來撤消訪問權限。有關更多信息,請參閱有權訪問您的帳戶支持文檔的第三方網站和應用程序的“刪除網站或應用程序訪問權限”部分

應用程序也有可能以編程方式撤銷對它的訪問。在用戶取消訂閱,刪除應用程序或應用程序所需的API資源發生重大變化的情況下,程序吊銷非常重要。換句話說,刪除過程的一部分可以包括API請求,以確保刪除先前授予該應用程序的權限。

要以編程方式撤消令牌,您的應用程序會向https://oauth2.googleapis.com/revoke發出請求,並將令牌作為參數包括在內:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

令牌可以是訪問令牌或刷新令牌。如果令牌是訪問令牌,並且具有相應的刷新令牌,則刷新令牌也將被吊銷。

如果撤消已成功處理,則響應的HTTP狀態代碼為200 。對於錯誤情況,將返回HTTP狀態代碼400和錯誤代碼。

進一步閱讀

適用於本機應用程序的IETF最新最佳實踐OAuth 2.0建立了此處記錄的許多最佳實踐。