適用於資料方案代理程式的 OAuth

OAuth 2.0 已標準化為 RFC 6749。如需詳細文件，請前往 https://oauth.net/2。HTTP 基本驗證是在 RFC 2617 第 2 節中定義的。

總覽

一般來說，為了讓第三方應用程式能存取受限資源，例如數據方案與錢包詳細資料，使用者 (資源擁有者) 需要與第三方共用憑證。這會產生許多問題和限制，例如憑證儲存空間、密碼驗證、使用者存取資源和密碼外洩等。OAuth2.0 藉由導入授權層來解決這些問題，因此能保護並限制使用者的受保護資源存取權。

GTAF 不會使用使用者的憑證存取受保護的資源，例如數據方案詳細資料，而是取得存取權杖。存取權杖會依照 GTAF 的 ##99 憑證核發給 GTAF。接著，GTAF 會使用存取權杖存取 DPA 代管的數據方案詳細資料。

下圖提供高階資訊流：

圖 1. 抽象的 OAuth 流程。

存取權仗

存取權杖是指 GTAF 用來存取電信業者 DPA 數據方案詳細資料的憑證。存取權杖是指代表 GTAF 授權的授權字串。字串通常與 GTAF 不透明。 權杖表示特定範圍與存取期限，可由使用者授予電信業者，以及由 DPA 和電信業者的 OAuth 伺服器強制執行。

存取權杖提供抽象層，將不同的授權結構 (例如使用者名稱和密碼) 替換為 DPA 能瞭解的單一權杖結構。這種抽象化的核發權杖比使用當初取得授權的授權範圍更嚴格，而且移除了 DPA' 需要瞭解多種驗證方法。

根據電信業者的安全性規定，存取權杖可能會採用不同的格式、結構和使用率方法 (例如加密編譯屬性)。 GTAF 僅支援 [RFC6750] 中定義的承受類型存取權杖。

用戶端驗證

GTAF 的身分為「機密用戶端」，可用來保護密碼安全。GTAF 目前僅支援透過 HTTP 基本驗證向 DPA 進行驗證。用戶端 ID 是透過「application/x-www-form-urlencoded" 編碼演算法」編碼，並將編碼值做為使用者名稱；密碼使用與演算法相同的演算法進行編碼。

核發用戶端憑證的機密用戶端 (例如 GTAF) 會透過電信業者的 OAuth 伺服器進行驗證，同時向權杖端點發出要求。用戶端驗證用於：\

  • 停用用戶端或變更其憑證，即可從遭到入侵的用戶端復原，進而防止攻擊者濫用竊取的重新整理權杖。 變更撤銷一組用戶端憑證，速度比撤銷一組更新權杖更快。
  • 實作驗證管理最佳做法，而需要定期輪替憑證。

傳送請求至權杖端點時，GTAF 會使用「client_id"」要求參數來識別身分。

請特別注意輪替輪替用戶端憑證的能力。OAuth 伺服器必須能夠在輪替過程中同時支援兩組憑證，而且必須能夠停用憑證。在一般憑證輪替中：

  1. 電信業者會在 OAuth 伺服器上建立新憑證，並以安全的方式將憑證傳送給技術帳戶管理員。
  2. Google 會測試新的憑證，並變更 GTAF 設定以使用新憑證。
  3. Google 會通知電信業者，舊版憑證可能會停用。
  4. 電信業者會停用憑證，並通知 Google
  5. Google 會驗證舊憑證已失效

OAuth 伺服器必須支援上述輪替程序。

權杖端點

GTAF 會使用權杖端點提供授權授權或更新權杖來取得存取權杖。除了隱含授權類型外，權杖端點也會與每次授權授權一起使用 (因為直接發出存取憑證)。

設定權杖端點時，請注意以下幾點：

  • 您應在服務說明文件中提供權杖端點的位置。
  • 端點 URI 可能包含「application/x-www-form-urlencoded&quot」格式化查詢元件，新增查詢參數時必須一併保留。端點 URI 不得包含片段元件。
  • 因為向權杖端點發出的要求會導致系統傳送明文憑證 (在 HTTP 要求和回應中)，因此電信業者的 OAuth 伺服器必須使用傳輸層安全標準 (TLS) 將要求傳送至權杖端點。
  • GTAF 使用存取權杖時，使用 HTTP「POST」方法。
  • 傳送不含值的參數時，必須視為在請求中省略。 OAuth 伺服器必須忽略無法辨識的要求參數。要求和回應參數不能重複出現。
  • GTAF 僅支援持有者的存取權杖。

存取權仗範圍

授權和權杖端點可讓用戶端使用「範圍」要求參數指定存取要求的範圍。授權伺服器隨後會使用「範圍」回應參數告知用戶端已核發的存取權杖範圍。

範圍參數的值以空格分隔且區分大小寫的字串表示。字串由授權伺服器定義。如果值含有多個以空格分隔的字串，順序就沒有影響，每個字串都會針對要求的範圍新增額外的存取權範圍。

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF 不需要實作範圍，但支援這項功能。詳情請參閱 RFC 6749 的第 3.3 節。

核發存取權杖

如果 GTAF 傳送的存取權杖要求有效且已獲授權，OAuth 伺服器會核發存取權杖，並提供選用重新整理權杖。如果要求失敗用戶端驗證或無效，OAuth 伺服器會傳回錯誤回應，如下一節所述。

成功的回應

GTAF 傳送要求時，OAuth 伺服器會發出存取權杖和選用的重新整理權杖，並附加以下參數以建立回應，方法是在 200 (OK) 狀態碼的 HTTP 回應實體中加入以下參數： \

  • access_token：必要。OAuth 伺服器核發的存取權杖。GTAF 預期權杖端點會傳回不傳回的權杖。
  • expires_in: 必填。存取權杖的生命週期 (以秒為單位)。例如，「3600」值表示存取權杖將在回應產生後的一小時內失效。如果已省略，OAuth 伺服器應透過其他方式提供到期時間，或記錄預設值。
  • token_type：必要。核發權杖的類型。如要進一步瞭解不同類型的權杖，請參閱 RFC 6749 的第 7.1 節。這個值不會區分大小寫。撰寫本文時，GTAF 僅支援持有憑證。
  • refresh_token: 選用。重新整理權杖，可用來使用相同的授權取得新存取權杖。
  • 範圍：選用，如果已實作，且與 GTAF 要求的範圍相同，否則為必要。

系統會使用「quo/;application/json"」在 HTTP 回應的實體主體中加入這些參數。藉由將參數新增至最高結構層級的每個參數，並序列化為 JavaScript Object Notation (JSON) 結構。參數名稱和字串值會納入 JSON 字串。含有數值的 JSON 數字。參數的順序無關緊要，可能會有所不同。

授權伺服器「必須」包含 HTTP、“快取和控制”回應標頭欄位，以及任何含有權杖、憑證或其他機密資訊的回應，以及含有「無回應快取」的回應回應欄位。

例如：

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

以下是需要留意的事項：

  • GTAF 會忽略回應中的無法辨識值名稱。
  • 從 OAuth 伺服器收到的權杖大小和其他值並未定義。
  • GTAF 應避免假設值大小。OAuth 伺服器應記錄其所發出的任何值的大小。

錯誤回應

如果授權要求因任何原因 (例如缺少、無效或不一致的重新導向 URI) 而失敗，或者用戶端 ID 遺失或無效，則 OAuth 伺服器應傳回 HTTP 400 (Bad Request) 狀態碼 (除非另有指定)，且應該至少加入一個錯誤和錯誤回應代碼區段所列的參數。

GTAF 授權

授權是一種憑證，代表使用者的授權 (用來存取資料餘額資訊等受保護的資源)，以便取得 GTAF 來取得存取權杖。

GTAF 使用 client_credentials 授權類型。在 client_credentials 授權類型中，GTAF 使用 HTTP POST 要求和 HTTP 基本驗證要求權杖。所有要求都會透過傳輸層安全標準 (TLS) 傳送 (例如HTTPS) 和 GTAF 無法與有效的傳輸層安全標準 (TLS) 憑證整合。GTAF 能夠傳遞可設定的權杖範圍，如果尚未設定，則系統會傳遞空白範圍。

GTAF 預期系統會傳回存取權杖以及「expires_in&quot」值 (存留時間)。expiration_in 值應至少為 900 秒，而且不得超過數小時。要求新權杖不會導致現有的權杖提前過期。

如要進一步瞭解各種授權類型，請參閱 RFC 6749 的第 1.3 節。

要求與回應範例

假設 GTAF 包含下列 OAuth 伺服器的設定：

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

注意：實際 DPA 的用戶端密碼必須比範例所示的密鑰更安全。

為了產生授權字串，用戶端 ID & & 39;:' 和密碼會經過串連與 Base64 編碼。您可以在指令列介面中複製，如下所示：

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

接著，GTAF 會使用這些憑證、client_credentials 授權類型，以及您設定的範圍向 OAuth 伺服器發出 HTTPS POST 要求。例如，GTAF' 的要求看起來會像這樣：

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

GTAF 使用的標頭不會與 curl 傳送的標頭不符，但授權標頭相同。

GTAF 預期的回應格式如下：

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

以下是有效回應的範例：

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

注意：回應必須是有效的 JSON。

錯誤回應和代碼

如果 GTAF 的授權要求因「錯誤回應」部分所述的原因而失敗，OAuth 伺服器就必須傳回 HTTP 400 (Bad Request) 狀態碼 (除非另有指定)，並在回應中加上下列其中一個參數：

例如：\

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF 預期 OAuth 伺服器支援下列錯誤回應：

錯誤代碼 回應 原因
HTTP 400 Invalid_request 要求缺少必要參數 (包含受支援的類型除外)、重複參數、包含多個憑證、使用多種機制向 GTAF 進行驗證，或是以其他方式格式錯誤。
HTTP 401 無效用戶端 用戶端驗證失敗，例如未知用戶端、未納入用戶端驗證或不支援此驗證方法。OAuth 伺服器可能會傳回 HTTP 401 (未經授權) 狀態碼，指出支援的 HTTP 驗證機制。如果用戶端嘗試透過「授權」要求欄位進行驗證，OAuth 伺服器必須傳回 HTTP 401 (未經授權) 狀態碼，且包含「WWW-Authenticate&quot」回應標頭欄位，該值與用戶端使用的驗證配置相符。
HTTP 500 OAuth 伺服器失敗

如要進一步瞭解可用於偵錯的其他回應，請參閱 RFC 6749 的第 5.2 節。