Open Cloud 支援 OAuth 2.0 授權流程，無論是否使用 PKCE，取決於您的客戶端是機密型還是公共型。
- 機密型客戶端 是能夠保持憑證機密的應用程式，例如能在其後端安全地存儲和檢索密碼的網站。
- 公共型客戶端 是不能保持密碼的應用程式，例如行動應用程式和網頁瀏覽器應用程式。
我們建議所有客戶端使用帶有 PKCE 的 OAuth 2.0 授權碼流程，並要求公共客戶端必須使用此流程。
請將客戶端密碼存儲在安全的地方，切勿公開。壞人可能會利用它來冒充您的應用程式。
要實作授權碼流程，您的應用程式需執行以下步驟：
- 生成代碼驗證碼和代碼挑戰（僅限 PKCE）。這允許您在請求中包含一個挑戰，而不是客戶端密碼，從而提高安全性。
- 向授權端點發送包含適當參數的 GET 請求。
- 處理授權回呼。在獲得授權後，使用 Roblox 的授權碼進行重定向請求，指向您在應用程式創建過程中指定的 URL。解析授權碼以供稍後使用。
- 向令牌端點發送帶有授權碼的 POST 請求。如果成功，您將獲得訪問令牌和刷新令牌，以進行 API 調用。
- 根據您要訪問的資源的參考文件，調用任何支持 OAuth 2.0 認證的 Open Cloud API。
以下各節將更深入地說明每一步。
生成代碼挑戰（僅限 PKCE）
在啟動授權過程之前，您需要從代碼驗證碼生成代碼挑戰。您可以使用所選編程語言中的庫或內置函數來創建代碼驗證碼，計算哈希並執行 Base64 編碼以生成代碼挑戰。
在創建代碼驗證碼時，只使用未保留的字符，包括大寫和小寫字母（A-Z, a-z），十進制數字（0-9），連字符（-），句點（.），下劃線（_）和波浪號（~），最小長度為 43 個字符，最大長度為 128 個字符。
以下範例顯示如何使用 Javascript 創建代碼驗證碼並使用 SHA-256 哈希算法生成代碼挑戰：
生成代碼挑戰
const crypto = require('crypto');
// base64URL 編碼驗證碼和挑戰
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// 從代碼驗證碼創建 sha256 哈希
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// 創建隨機代碼驗證碼
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// 從代碼驗證碼生成挑戰
var code_challenge = base64URLEncode(sha256(code_verifier));
對於 PKCE，您在後續步驟中需要代碼驗證碼和挑戰值。
構建授權 URL
請參見 授權端點參考文件 以獲取有關如何構建授權 URL 的完整資訊。
要啟動用戶授權流程，構建一個包含必需參數的授權 URL：
- client_id: 您的應用程式的客戶端 ID，在 註冊應用程式 後獲得。
- redirect_uri: 您的應用程式的重定向 URI，您的應用程式的重新進入點。
- scope: 以空格分隔的列表，請求的範圍，定義您的應用程式所需的訪問權限。
- response_type: 設置為 code 以指示授權碼流程。
僅 PKCE 所需
- code_challenge: 從代碼驗證碼生成的代碼挑戰。
- code_challenge_method: 將此參數值設置為 S256，以指示代碼挑戰是使用 SHA-256 算法變換的，這是最廣泛支持且安全的代碼挑戰方法。
- state: 一個不透明的安全隨機值，在請求和回呼之間維持狀態。
僅非 PKCE 所需
- client_secret: 您的應用程式的客戶端密碼，在 註冊應用程式 後獲得。如果您使用帶有 PKCE 的認證，則省略此參數。 您的授權請求 URL 必須格式正確，如以下範例所示：
示例 PKCE 授權 URL
當用戶訪問該 URL 時，他們將被帶入授權流程。如果成功，Roblox 將用戶重定向到指定的 redirect_uri。
處理授權回呼
當授權流程成功時，您的應用程式將從您指定的 redirect_uri 收到來自 Roblox 授權伺服器的 GET 請求。在請求中，您將收到 code（授權碼）和 state（如果您之前提供了值）參數。
code 參數包含一個授權碼，應用程式可以用它向授權伺服器交換訪問令牌。大多數後端伺服器語言都有標準的方法來訪問查詢參數作為解碼對象。您需要獲取 code 參數並用它來交換訪問令牌。
state 參數是您最初在授權請求中提供的一個不透明值。您可以使用此參數來維持授權流程的狀態或上下文。
例如，如果您將重定向 URI 指定為 https://example.com/redirect，則可能會收到帶有以下 URL 的 GET 請求。
示例重定向 URL
如果授權失敗，您的應用程式將收到對指定重定向 URL 的 GET 請求，其中包含 error、error_description 和 state（如果適用）參數。
- error 參數指示在授權過程中發生的特定 OAuth 2.0 錯誤。
- error_description 參數提供有關錯誤的其他詳細信息。
- state 參數幫助您的應用程式在失敗情況下維持狀態。
用授權碼交換訪問令牌
當您解析了授權 code 後，可用其交換訪問令牌，以訪問所需的 Roblox 資源：
通過向 令牌交換端點 發送 POST 請求來請求訪問令牌和刷新令牌。請求必須包含授權碼、客戶端 ID 和代碼驗證碼值（PKCE）或客戶端密碼（非 PKCE），格式為 x-www-form-urlencoded。
從接收到的回應中解析適用的令牌。訪問令牌有效期為 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.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pY2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwib25jZWUiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.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"
}