Triển khai ứng dụng OAuth 2.0 | Tài liệu - Trung Tâm Nhà Sáng Tạo Roblox

Open Cloud hỗ trợ quy trình ủy quyền OAuth 2.0 với và không có PKCE, tuỳ thuộc vào việc các khách hàng của bạn là bí mật hay công khai.

Khách hàng bí mật là các ứng dụng có khả năng giữ bí mật thông tin bí mật, chẳng hạn như một trang web có thể lưu trữ và truy xuất bí mật một cách an toàn qua backend của nó.
Khách hàng công khai là các ứng dụng không thể giữ bí mật, chẳng hạn như ứng dụng di động và ứng dụng trình duyệt web.

Chúng tôi khuyến nghị sử dụng quy trình mã ủy quyền OAuth 2.0 với PKCE cho tất cả khách hàng và yêu cầu điều này đối với các khách hàng công khai.

Lưu trữ bí mật khách hàng ở một nơi an toàn và không bao giờ để lộ thông tin này ra công chúng. Các actor xấu có thể sử dụng nó để mạo danh ứng dụng của bạn.

Để triển khai quy trình mã ủy quyền, ứng dụng của bạn thực hiện các bước sau:

Tạo một mã xác thực và mã thách thức (chỉ PKCE). Điều này cho phép bạn bao gồm một thách thức trong các yêu cầu của bạn thay vì bí mật khách hàng, điều này nâng cao bảo mật.
Gửi một yêu cầu GET đến điểm cuối ủy quyền với các tham số thích hợp.
Xử lý callback ủy quyền. Sau khi đạt được quyền ủy quyền, sử dụng mã ủy quyền từ Roblox trong một yêu cầu chuyển hướng đến URL mà bạn đã chỉ định trong quá trình tạo ứng dụng. Phân tích mã ủy quyền để sử dụng sau này.
Gửi một yêu cầu POST đến điểm cuối token với mã ủy quyền. Nếu thành công, bạn sẽ nhận được mã truy cập và mã làm mới để thực hiện các cuộc gọi API.
Gọi bất kỳ API Open Cloud nào hỗ trợ xác thực OAuth 2.0 dựa trên tài liệu tham khảo cho các tài nguyên bạn muốn truy cập.

Các phần sau mô tả từng bước một cách chi tiết hơn.

Tạo thách thức mã (chỉ cho PKCE)

Trước khi bắt đầu quy trình ủy quyền, bạn cần tạo một mã thách thức từ một mã xác thực. Bạn có thể sử dụng các thư viện hoặc hàm tích hợp trong ngôn ngữ lập trình của bạn để tạo mã xác thực, tính toán băm và thực hiện mã hóa Base64 để tạo thách thức mã.

Khi tạo mã xác thực, chỉ sử dụng các ký tự không bị giữ chỗ, bao gồm các chữ cái viết hoa và viết thường (A-Z, a-z), các chữ số thập phân (0-9), dấu gạch ngang (-), dấu chấm (.), dấu gạch dưới (_), và dấu ngã (~), với độ dài tối thiểu 43 ký tự và độ dài tối đa 128 ký tự.

Ví dụ sau cho thấy cách sử dụng Javascript để tạo mã xác thực và tạo thách thức mã sử dụng thuật toán băm SHA-256:

Tạo Thách Thức Mã
const crypto = require('crypto');

// mã hóa base64URL mã xác thực và thách thức
function base64URLEncode(str) {
  return str.toString('base64')
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '');
}

// tạo băm sha256 từ mã xác thực
function sha256(buffer) {
  return crypto.createHash('sha256').update(buffer).digest(`base64`);
}

// tạo một mã xác thực ngẫu nhiên
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// tạo một thách thức từ mã xác thực
var code_challenge = base64URLEncode(sha256(code_verifier));

Đối với PKCE, bạn cần cả giá trị mã xác thực và thách thức trong các bước tiếp theo.

Xây dựng URL ủy quyền

Xem tài liệu tham khảo điểm cuối ủy quyền để biết thông tin đầy đủ về cách xây dựng URL ủy quyền.

Để bắt đầu quy trình ủy quyền người dùng, hãy xây dựng một URL ủy quyền với các tham số bắt buộc:

client_id: ID khách hàng của ứng dụng bạn nhận được sau khi đăng ký ứng dụng của bạn.
redirect_uri: URI chuyển hướng của ứng dụng bạn, điểm tái nhập của ứng dụng.
scope: Các phạm vi yêu cầu định nghĩa các quyền truy cập mà ứng dụng bạn cần trong danh sách các phạm vi cách nhau bằng khoảng trắng.
response_type: Đặt giá trị này thành code để chỉ định quy trình mã ủy quyền.

Bắt buộc chỉ cho PKCE

code_challenge: Thách thức mã được tạo từ một mã xác thực.
code_challenge_method: Đặt giá trị tham số này thành S256 để chỉ định rằng thách thức mã đã được biến đổi bằng thuật toán SHA-256, phương pháp thách thức mã được hỗ trợ rộng rãi nhất và an toàn nhất.
state: Một giá trị ngẫu nhiên trong suốt, bảo mật để duy trì trạng thái giữa yêu cầu và callback.

Bắt buộc chỉ cho không-PKCE

client_secret: Bí mật khách hàng của ứng dụng bạn nhận được sau khi đăng ký ứng dụng của bạn. Nếu bạn đang sử dụng xác thực với PKCE, hãy bỏ qua tham số này. URL yêu cầu ủy quyền của bạn phải được định dạng tốt, như trong ví dụ sau:

Ví dụ URL Ủy Quyền 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

Khi người dùng truy cập URL, họ sẽ được đưa qua quy trình ủy quyền. Nếu thành công, Roblox sẽ chuyển hướng người dùng đến redirect_uri đã chỉ định.

Xử lý các callback ủy quyền

Khi một quy trình ủy quyền thành công, ứng dụng của bạn nhận được một yêu cầu GET từ máy chủ ủy quyền Roblox tại redirect_uri mà bạn đã chỉ định. Trong yêu cầu, bạn nhận được code (mã ủy quyền) và state (nếu bạn đã cung cấp giá trị trước đó).

Tham số code chứa một mã ủy quyền mà ứng dụng có thể trao đổi để lấy mã truy cập từ máy chủ ủy quyền. Hầu hết các ngôn ngữ máy chủ backend có cách tiêu chuẩn để truy cập các tham số truy vấn dưới dạng các đối tượng đã giải mã. Bạn sẽ cần lấy tham số code và sử dụng nó để trao đổi lấy mã truy cập.
Tham số state là một giá trị không rõ mà bạn đã cung cấp ban đầu trong yêu cầu ủy quyền. Bạn có thể sử dụng tham số này để duy trì trạng thái hoặc ngữ cảnh của quy trình ủy quyền.

Ví dụ, bạn có thể nhận được một yêu cầu GET với URL sau nếu bạn đã chỉ định URI chuyển hướng của bạn là https://example.com/redirect.

Ví dụ URL Chuyển Hướng
https://example.com/redirect?code=10c45PNuquKnFJ6pUcy5-fHkghEM6lSegm-7hj9mVEprub1dSDuStuKK_EAUXY7AHTD63xcnmvxSLthp-C8g3jzIGZVzuXSd20Y2dEYI9hx0LZmPg95ME4z2K03UheiZbroyXUjYyB3ReoMqobzDVPzyx6IS8kj2Uu-11Xq_0JiTYxtDatuqXRNIAmJT8gMJmbSyOLOP_vnDvbeMUiBsqCRrkTGVbWSwYSc8sTVVE-535kYdqQOgNjH1ffCoZLGl8YYxLnpb2CXJlRQPrcjkA&state=6789

Nếu việc ủy quyền không thành công, ứng dụng của bạn nhận một yêu cầu GET tới URL chuyển hướng đã chỉ định với các tham số error, error_description, và state (nếu có).

Tham số error chỉ ra lỗi OAuth 2.0 cụ thể đã xảy ra trong quy trình ủy quyền.
Tham số error_description cung cấp thêm chi tiết về lỗi.
Tham số state giúp ứng dụng của bạn duy trì trạng thái trong trường hợp thất bại.

Trao đổi mã ủy quyền để lấy mã truy cập

Khi bạn đã phân tích được code ủy quyền, hãy trao đổi nó để lấy các mã truy cập cần thiết cho các tài nguyên Roblox mong muốn:

Yêu cầu một mã truy cập và mã làm mới bằng cách gửi một yêu cầu POST đến điểm cuối trao đổi mã. Yêu cầu phải bao gồm mã ủy quyền, ID khách hàng, và giá trị mã xác thực (PKCE) hoặc bí mật khách hàng (không-PKCE) ở định dạng x-www-form-urlencoded.

Phân tích các mã áp dụng từ phản hồi nhận được. Mã truy cập là hợp lệ trong 15 phút. Lưu trữ mã làm mới một cách an toàn, thường là ở phía máy chủ, để bạn có thể sử dụng nó để nhận mã mới trong tương lai.

Ví dụ Phản Hồi Điểm Cuối Mã
{
  "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"
}

Thực hiện cuộc gọi đến phương thức tài nguyên

Bây giờ bạn đã có mã truy cập cần thiết, bạn có thể sử dụng nó để thực hiện các cuộc gọi xác thực đến các phương thức tài nguyên. Bao gồm mã truy cập trong tiêu đề của tất cả các yêu cầu API để cấp quyền cho chúng.

Ví dụ, bạn có thể kiểm tra xem ứng dụng của bạn có hoạt động chính xác không bằng cách thực hiện quy trình ủy quyền hoàn chỉnh và sau đó gửi một yêu cầu GET đến điểm cuối thông tin người dùng với mã truy cập. Đảm bảo bạn có phạm vi openid hoặc cả hai phạm vi openid và profile trước khi gọi điểm cuối này. Nếu thành công, phản hồi từ điểm cuối đó trông như thế này:

Ví dụ Phản Hồi Thông Tin Người Dùng
{
  "sub": "12345678",
  "name": "Jane Doe",
  "nickname": "robloxjanedoe",
  "preferred_username": "robloxjanedoe",
  "created_at": 1607354232,
  "profile": "https://www.roblox.com/users/12345678/profile"
}