OAuth 2.0 應用程式實作

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

開啟雲端支持OAuth 2.0授權流程，帶或不帶PKCE，取決於您的客戶是否為機密或公開。

  • 機密客戶端 是能夠保密保密資格的應用程式，例如一個網站，可以在後端儲存和恢復秘密。
  • 公共客戶是無法保密的應用程式，例如手機和網頁瀏覽器應用程式。

我們建議使用 PKCE 與 OAuth 2.0 授權代碼流程對所有 客戶端 進行授權，並對公共客戶端要求它。

要實現授權代碼流程,您的應用執行以下步驟:

  1. 生成代碼驗證器和代碼挑戰（僅限 PKCE）。這讓您可以在要求中包含挑戰，而不是客戶的秘密，這有助於提高安全。
  2. 向授權端點發送 GET 要求，並使用適當的參數。
  3. 處理授權回調。獲得授權後,使用 Roblox 的授權代碼在重定向請求到你在應用程式作品期間指定的 URL。解析授權代碼以供稍後使用。
  4. 將授權代碼傳送到代幣端點的 POST 請求。成功時，您將收到用於發出 API 呼叫的存取和刷新代幣。
  5. 呼叫任何支持 OAuth 2.0 認證的開放雲 API，以基於資源參考文件來存取您想要存使用權 通行權 存取的資源。

以下部分進一步說明每一步。

生成代碼挑戰（僅針對 PKCE）

在啟動授權過程之前，您需要從代碼驗證器生成一個代碼挑戰。您可以使用您選擇的程序語言中的圖形庫或內置功能來創建代碼驗證器、計算哈希並進行 Base64 編碼以生成代碼挑戰。

當創建代碼驗證器時，只使用未保留的字符，包括大/小寫字母（A-Z，a-z）、十進位數字（0-9）、橫條 (-)、時間（.,）、下劍 (_) 和撇號（~），最短長度為 43 個字符，最長長度為 128 個字符。

以下範例顯示如何使用 JavaScript 創建代碼驗證器，並使用 SHA-256 散列算法生成代碼挑戰：

Generate Code Challenge
const crypto = require('crypto');



// base64URL encode the verifier and challenge

function base64URLEncode(str) {

  return str.toString('base64')

      .replace(/\+/g, '-')

      .replace(/\//g, '_')

      .replace(/=/g, '');

}



// create sha256 hash from code verifier

function sha256(buffer) {

  return crypto.createHash('sha256').update(buffer).digest(`base64`);

}



// create a random code verifier

var code_verifier = base64URLEncode(crypto.randomBytes(32));

// generate a challenge from the code verifier

var code_challenge = base64URLEncode(sha256(code_verifier));

對於 PKCE，您需要在後續步驟中使用代碼驗證器和挑戰值。

建立授權 URL

要啟動使用者認証過程，請使用所需參數建立一個授權URL：

  • client_id : 您的App用程式客戶ID在註冊您的應用程式後獲得。
  • redirect_uri : 您應用App的重定向 URI，您應用App式的重新入口點。
  • scope : 要求的範圍，定義了你應用程式在空白分隔列表中需要的存取權限。
  • response_type : 將其設為 code 以指示授權代碼流。 僅適用於PKCE
  • code_challenge : 從代碼驗證器生成的代碼挑戰。
  • code_challenge_method : 將此參數值設為 S256 來表示代碼挑戰使用了 SHA-256 算法轉換，這是最廣泛支持和最安全的代碼挑戰方法。
  • state : 不透明、安全的隨機值，用於維持請求和回呼之間的狀態。 僅適用於非PKCE
  • client_secret : 您的App用程式的客戶端秘密在 註冊您的應用程式 後獲得。如果您使用 PKCE 驗證，請忽略此參數。您的授權請求 URL 必須格式良好，如下面的範例：
PKCE 授權 URL 範例
https://apis.roblox.com/oauth/v1/authorize?client_id=7290610391231237934964

    &code_challenge=PLEKKVCjdD1V_07wOKlAm7P02NC-LZ_1hQfdu5XSXEI

    &code_challenge_method=S256

    &redirect_uri=https://example.com/redirect

    &scope=openid%20profile

    &response_type=code

    &state=abc123

當使用者訪問 URL 時，他們會經過授權流程。 如果成功，Roblox 將導引使用者到指定的 redirect_uri 。

處理授權回呼

當授權流程成功時，您的應用程式會從指定的 GET 位置收到來自 Roblox 授權伺服器的 redirect_uri 請求。在請邀請中，您收到 code (授權代碼) 和 state (如果您之前提供了值) 參數。

  • code 參數包含一個授權代碼，應用程式可以從授權伺服器兌換為存取代碼的存取代碼。大多數後端伺服器語言都有標準方式來存取查詢參數作為解碼的對象。您需要獲得 code 參數並使用它來交換取得存取代碼。

  • state 參數是您最初在授權請邀請中提供的不透明值。您可以使用此參數來維持授權過程的狀態或上下文。

例如，如果你指定你的重定向 URI 為 https://example.com/redirect，你可能會收到以下 URL 的 GET 請求。

範例重定向URL
https://example.com/redirect?code=10c45PNuquKnFJ6pUcy5-fHkghEM6lSegm-7hj9mVEprub1dSDuStuKK_EAUXY7AHTD63xcnmvxSLthp-C8g3jzIGZVzuXSd20Y2dEYI9hx0LZmPg95ME4z2K03UheiZbroyXUjYyB3ReoMqobzDVPzyx6IS8kj2Uu-11Xq_0JiTYxtDatuqXRNIAmJT8gMJmbSyOLOP_vnDvbeMUiBsqCRrkTGVbWSwYSc8sTVVE-535kYdqQOgNjH1ffCoZLGl8YYxLnpb2CXJlRQPrcjkA&state=6789

如果授權失敗，您的應用程式會收到 要求轉到指定的重定向 URL 與 、 》、和 》(如果適用) 參數。

  • error 參數指示在授權過程中發生的特定 OAuth 2.0 錯誤。
  • error_description 參數提供額外錯誤的細節。
  • state 參數可幫助您的應用程式在發生故障時維持狀態。

交換授權代碼以取得存取代幣

當您解析了授權 code 時，將其轉換為代幣以存取所需的 Roblox 資源：

  1. 發送 POST 要求到 代幣交換端點 來請求存取代幣和刷新代幣。請求必須包含授權代碼、客戶ID和代碼驗證值(PKCE)或客戶秘密(非PKCE)在x-www-form-urlencoded格式中。

  2. 從收到的回應中解析應用的代幣。存取代碼有效期為 15 分鐘。將刷新代幣安全地存儲在服務器側，通常在服務器側，以便您將來可以使用它來獲得新的代幣。

    範例代幣終端回應
    {

      "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IlBOeHhpb2JFNE8zbGhQUUlUZG9QQ3FCTE81amh3aXZFS1pHOWhfTGJNOWMiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwiYWlkIjoiM2Q2MWU3NDctM2ExNS00NTE4LWJiNDEtMWU3M2VhNDUyZWIwIiwic2NvcGUiOiJvcGVuaWQ6cmVhZCBwcm9maWxlOnJlYWQiLCJqdGkiOiJBVC5QbmFWVHpJU3k2YkI5TG5QYnZpTCIsIm5iZiI6MTY5MTYzOTY5OCwiZXhwIjoxNjkxNjQwNTk4LCJpYXQiOjE2OTE2Mzk2OTgsImlzcyI6Imh0dHBzOi8vYXBpcy5yb2Jsb3guY29tL29hdXRoLyIsImF1ZCI6IjcyOTA2MTAzOTc5ODc5MzQ5Nj1234.BjwMkC8Q5a_iP1Q5Th8FrS7ntioAollv_zW9mprF1ats9CD2axCvupZydVzYphzQ8TawunnYXp0Xe8k0t8ithg",

      "refresh_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoidGpHd1BHaURDWkprZEZkREg1dFZ5emVzRWQyQ0o1NDgtUi1Ya1J1TTBBRSIsInR5cCI6IkpXVCJ9..nKYZvjvXH6msDG8Udluuuw.PwP-_HJIjrgYdY-gMR0Q3cabNwIbmItcMEQHx5r7qStVVa5l4CbrKwJvjY-w9xZ9VFb6P70WmXndNifnio5BPZmivW5QkJgv5_sxLoCwsqB1bmEkz2nFF4ANLzQLCQMvQwgXHPMfCK-lclpVEwnHk4kemrCFOvfuH4qJ1V0Q0j0WjsSU026M67zMaFrrhSKwQh-SzhmXejhKJOjhNfY9hAmeS-LsLLdszAq_JyN7fIvZl1fWDnER_CeDAbQDj5K5ECNOHAQ3RemQ2dADVlc07VEt2KpSqUlHlq3rcaIcNRHCue4GfbCc1lZwQsALbM1aSIzF68klXs1Cj_ZmXxOSOyHxwmbQCHwY7aa16f3VEJzCYa6m0m5U_oHy84iQzsC-_JvBaeFCachrLWmFY818S-nH5fCIORdYgc4s7Fj5HdULnnVwiKeQLKSaYsfneHtqwOc_ux2QYv6Cv6Xn04tkB2TEsuZ7dFwPI-Hw2O30vCzLTcZ-Fl08ER0J0hhq4ep7B641IOnPpMZ1m0gpJJRPbHX_ooqHol9zHZ0gcLKMdYy1wUgsmn_nK_THK3m0RmENXNtepyLw_tSd5vqqIWZ5NFglKSqVnbomEkxneEJRgoFhBGMZiR-3FXMaVryUjq-N.Q_t4NGxTUSMsLVEppkTu0Q6rwt2rKJfFGuvy3s12345",

      "token_type": "Bearer",

      "expires_in": 899,

      "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IkNWWDU1Mi1zeWh4Y1VGdW5vNktScmtReFB1eW15YTRQVllodWdsd3hnNzgiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pY2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwibm9uY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg",

      "scope": "openid profile"

    }

呼叫資源方法

現在您已擁有所需的認證代碼，您可以使用它來向資源方法發出認證呼叫。包含使用權代碼在所有 API 請求的標題中，以授權它們。

例如，您可以通過走過整個授權流程來測試應用程式是否正常運作，然後使用存取代碼將 GET 請求發送到 使用者資訊端點 以進行測試。確保在呼叫此端點之前，你有 openid 或兩個 openid 和 profile 範圍。如果成功，從該端點的回應看起來像這樣：

範例使用者資訊回應
{

  "sub": "12345678",

  "name": "Jane Doe",

  "nickname": "robloxjanedoe",

  "preferred_username": "robloxjanedoe",

  "created_at": 1607354232,

  "profile": "https://www.roblox.com/users/12345678/profile"

}