行動與電腦版應用程式的 OAuth 2.0

本文說明如何在手機、平板電腦和電腦等裝置上安裝應用程式，以便使用 Google 的 OAuth 2.0 端點授權存取 Google API。

OAuth 2.0 可讓使用者與應用程式共用特定資料，同時保有使用者名稱、密碼和其他資訊的隱私。舉例來說，應用程式可以使用 OAuth 2.0 取得使用者的權限，以便將檔案儲存在 Google 雲端硬碟中。

已安裝的應用程式會分發至個別裝置，且這些應用程式無法保留機密資料。使用者在應用程式中，或應用程式在背景執行時，都可以存取 Google API。

這個授權流程與網頁伺服器應用程式的流程類似。主要差異在於已安裝的應用程式必須開啟系統���覽器，並提供本機重新導向 URI，才能處理 Google 授權伺服器的回應。

替代方案

如果是行動應用程式，建議您使用 Android 或 iOS 版的 Google 登入功能。Google 登入用戶端程式庫會處理驗證和使用者授權���業，而且可能比這裡所述的低階通訊協定更容易導入。

如果應用程式在裝置上執行，但該裝置不支援系統瀏覽器或輸入功能受限 (例如電視、遊戲主機、相機或印表機)，請參閱 適用於電視和裝置的 OAuth 2.0 或在電視和輸入功能受限的裝置上登入。

程式庫與範例

建議您使用下列程式庫和範例，實作本文所述的 OAuth 2.0 流程：

• AppAuth for Android 程式庫
• AppAuth for iOS 程式庫
• 應用程式專用 OAuth：Windows 範例

必要條件

為專案啟用 API

任何會呼叫 Google API 的應用程式，都必須在 API Console中啟用這些 API。

如要為專案啟用 API，請按照下列步驟操作：

1. Open the API Library 在 Google API Console中。
2. If prompted, select a project, or create a new one.
3. API Library 會列出所有可用的 API，並按照產品系列和熱門程度分組。如果清單裡找不到您想啟用的 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. 按一下 [Create credentials] (建立憑證) > [OAuth client ID] (OAuth 用戶端 ID)。
3. 以下各節說明 Google 授權伺服器支援的用戶端類型。請選擇應用程式建議的用戶端類型、為 OAuth 用戶端命名，並視需要設定表單中的其他欄位。

找出存取權範圍

範圍可讓應用程式僅要求存取其需要的資源，也能讓使用者控制對應用程式授予的存取量。因此，要求的範圍數量與取得使用者同意的可能性之間可能呈現反比關係。

開始實作 OAuth 2.0 授權之前，建議您找出應用程式需要權限存取的範圍。

「OAuth 2.0 API 範圍」文件包含您可能用於存取 Google API 的範圍完整清單。

取得 OAuth 2.0 存取權杖

以下步驟說明應用程式如何與 Google 的 OAuth 2.0 伺服器互動，取得使用者同意，代表使用者執行 API 要求。應用程式必須取得同意聲明，才能執行需要使用者授權的 Google API 要求。

步驟 1：產生驗證碼和驗證碼挑戰

Google 支援 Proof Key for Code Exchange (PKCE) 通訊協定，讓安裝應用程式流程更加安全。系統會為每個授權要求建立專屬的代碼驗證器，並將其轉換值 (稱為「code_challenge」) 傳送至授權伺服器，以取得授權碼。

建立程式碼驗證器

code_verifier 是使用未保留字元 [A-Z] / [a-z] / [0-9] /「-」/「.」/「_」/「~」的高熵加密隨機字串，長度最短為 43 個字元，最長為 128 個字元。

程式碼驗證器應具備足夠的熵，讓值無法被猜測。

建立驗證碼問題

系統支援兩種建立程式碼挑戰的方法。

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

步驟 2：向 Google 的 OAuth 2.0 伺服器傳送要求

如要取得使用者授權，請傳送要求至 Google 授權伺服器 (https://accounts.google.com/o/oauth2/v2/auth)。這個端點會處理有效工作階段查詢、驗證使用者，以及取得使用者同意聲明。端點只能透過 SSL 存取，且會拒絕 HTTP (非 SSL) 連線。

授權伺服器支援下列已安裝應用程式的查詢字串參數：

授權網址範例

下方分頁會顯示不同重新導向 URI 選項的授權網址範例。

除了 redirect_uri 參數的值不同，其他部分的網址都相同。網址也包含必要的 response_type 和 client_id 參數，以及選用的 state 參數。每個網址都包含換行符號和空格，方便閱讀。

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

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

步驟 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 端點並設定下列參數：

以下程式碼片段為要求範例：

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=http://127.0.0.1:9004&
grant_type=authorization_code

Google 會傳回 JSON 物件來回應這項要求，其中包含短效存取權杖和重新整理權杖。

回應包含下列欄位：

以下程式碼片段為回應範例：

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

步驟 6：檢查使用者授予的範圍

一次要求多個權限範圍時，使用者可能不會授予應用程式要求的所有權限範圍。 應用程式應一律檢查使用者授予的存取範圍，並透過停用相關功能來處理任何存取範圍拒絕的情況。詳情請參閱如何處理精細權限。

如要檢查使用者是否已授予應用程式存取特定範圍的權限，請查看存取權存取金鑰回應中的 scope 欄位。由 access_token 授予的存取權範圍，以空格分隔的字串清單表示，並區分大小寫。

舉例來說，下列存取權存取權杖回應範例指出，使用者已授予應用程式存取權，可存取唯讀的 Google 雲端硬碟活動和日曆活動：

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

呼叫 Google API

應用程式取得存取權權杖後，如果已授予 API 所需的存取範圍，您就可以使用權杖代表特定使用者帳戶呼叫 Google API。如要這樣做，請在 API 要求中加入存取權杖，方法是加入 access_token 查詢參數或 Authorization HTTP 標頭 Bearer 值。盡可能使用 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 要求的無效憑證。如果您要求與權杖相關聯的範圍的離線存取權，則可以重新整理存取權杖，而無須提示使用者授予權限 (包括使用者不在場時)。

如要重新整理存取權杖，應用程式會向 Google 的授權伺服器 (https://oauth2.googleapis.com/token) 傳送 HTTPS POST 要求，其中包含下列參數：

以下程式碼片段為要求範例：

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 https://www.googleapis.com/auth/calendar.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」中，已建立許多這裡所述的最佳做法。