OAuth 2.0 應用程式實現

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

開啟雲朵支援 OAuth 2.0 授權流程，並且包含或不包含 PKCE，取決於您的客戶是否是私人或公開共客戶。

  • 機密客戶端 是能儲存和取回秘密的網站，例如可以在後端安全存取秘密的網站。
  • 公開客戶端是可以保持秘密的應用程式，例如行動和網頁瀏覽器應用程式。

我們推薦使用 PKCE 對所有客戶端使用 OAuth 2.0 授權碼流程，並且要求公共客戶端使用。

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

  1. 生成代碼驗證器和代碼挑戰(僅限 PKCE)。這允許您包含挑戰在您的請求中，而不是客戶端的秘密，這提升了安全。
  2. 發送 GET 請求至授權端點，並且提供相應的參數。
  3. 處理授權回來。 獲得授權後，從 Roblox 的引導回調求中使用 Roblox 的授權代碼來到您指定的網頁。 處理授權代碼以獲得後續使用。
  4. 發送授權代碼的 POST 請求到代幣端口。如果成功，你將獲得使用 API 呼叫的權限，並且重設代幣。
  5. 調用任何支持 OAuth 2.0 鑑別基於引用資料庫的資源的開放雲 API。

下列部分描述每個步驟的更深入程度。

生成代碼挑戰(僅適用於 PKCE)

在啟動授權過程之前，您需要從代碼驗證器生成代碼挑戰。 您可以使用語言選擇的程式語言生成代碼驗證器，計算哈希，並執行 Base64 編碼，以生成代碼挑戰。

創建代碼驗證器時，只能使用不保留的字符，包括上下文字母（A-Z，a-z）、十六進制數字（0-9、hyphen (-、期（.）、下條（.）、底條（_）和撇條（~）），以及最小為 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：

  • client_id : 您註冊應用App式後獲得的客戶端 ID。
  • redirect_uri : 您的AppApp的重新入口點。
  • scope : 您要求的鏡像，在空格分開的列表中定義您應用程序需要的使用權限。
  • response_type : 設定它為 code 以表示授權代碼流程。 僅適用於 PKCE
  • code_challenge : 由代碼驗證器生成的代碼挑戰。
  • code_challenge_method : 將此參數值設置為 S256 來表示代碼挑戰使用了 SHA-256 算法，最廣泛且最安全的代碼挑戰方法。
  • state : 一個隱藏的、安全的隨機值來維持狀態之間的請求和回調。 僅限於非 PKCE 的情況下需要
  • client_secret : 您的應用程App的客戶端秘密在 註冊您的應用程序 後獲得。如果您使用 PKCE 的驗證，請略過此參數。您的授權請求 URL 必須是以下示例所示的格式：
 PKCE 授權網頁範例
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。

處理授權回來

當授權流程成功時，您的應用從 Roblox 授權服務器獲得 GET 請求，您指定的 redirect_uri 。在請邀請中，您獲得 code (授權代碼) 和 1> state1> (如果您以前提供了值) 參數。

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

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

舉例來說，如果您指定您的重新定向網址為 GET，您將收到一個 https://example.com/redirect 請求，以下是該請求的內容。

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

如果授權失敗，您的應用程式將收到一個 GET 請求，以指定的重新導航網址，並且有 error , error_description 和 2> state2> (如適用) 參數。

  • error 參數指定在授權過程中發生的特定 OAuth 2.0 錯誤。
  • error_description 參數提供額外的錯誤細節。
  • state 參數可幫助您的應用維持狀態，如果發生失敗。

交換授權代碼取得資產管理員的代碼

當您解析授權 code 時，與它交換代幣來存取所需 Roblox 資源：

  1. 請發送 POST 請求到 token exchange endpoint ，以取得使用者授權代碼、客戶端 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 請求到 user 資訊端口 使用存取代幣。確認您有 openid 或兩個 2>openid2> 和 5>個人檔案rofile

範例使用者資訊回應
{

  "sub": "12345678",

  "name": "Jane Doe",

  "nickname": "robloxjanedoe",

  "preferred_username": "robloxjanedoe",

  "created_at": 1607354232,

  "profile": "https://www.roblox.com/用戶/12345678/個人檔案"

}