การนำไปใช้แอป OAuth 2.0 | เอกสาร - ศูนย์กลางครีเอเตอร์ Roblox

Open Cloud รองรับการไหลของการอนุญาต OAuth 2.0 โดยมีและไม่มี PKCE ขึ้นอยู่กับว่าลูกค้าของคุณเป็นแบบลับหรือสาธารณะ

ลูกค้ารับข้อมูลที่เป็นความลับ คือแอปที่สามารถเก็บรักษา ข้อมูลรับรองได้อย่างเป็นความลับ เช่น เว็บไซต์ที่สามารถเก็บและเรียกคืนความลับได้อย่างปลอดภัยใน ส่วนหลังของตน
ลูกค้าสาธารณะ คือแอปที่ไม่สามารถเก็บความลับได้ เช่น แอปบน มือถือและเว็บเบราว์เซอร์

เราขอแนะนำให้ใช้การไหลของรหัสอนุญาต OAuth 2.0 ร่วมกับ PKCE สำหรับ ลูกค้าทั้งหมด และขอให้ใช้สำหรับลูกค้าสาธารณะ

เก็บข้อมูลความลับของลูกค้าไว้ในที่ปลอดภัยและไม่เปิดเผยต่อสาธารณะ ผู้ไม่หวังดี สามารถใช้มันเพื่อปลอมแปลงคุณ

ในการนำไปใช้การรวบรวมรหัสอนุญาต แอปของคุณจะทำตามขั้นตอนต่อไปนี้:

สร้างตัวตรวจสอบรหัสและการท้าทายรหัส (เฉพาะ PKCE) ซึ่งช่วยให้คุณ รวมการท้าทายในคำขอของคุณแทนข้อมูลรับรองลูกค้า ซึ่ง ช่วยปรับปรุงความปลอดภัย
ส่งคำขอ GET ไปยังจุดสิ้นสุดการอนุญาตพร้อมกับพารามิเตอร์ที่เหมาะสม
จัดการการเรียกกลับการอนุญาต หลังจากได้รับอนุญาตให้ใช้ รหัสอนุญาตจาก Roblox ในคำขอการเปลี่ยนเส้นทางไปยัง URL ที่คุณระบุ ระหว่างการสร้างแอป แยกวิเคราะห์รหัสอนุญาตเพื่อใช้ในภายหลัง
ส่งคำขอ POST ไปยังจุดสิ้นสุดโทเค็นพร้อมกับรหัสอนุญาต หาก สำเร็จ คุณจะได้รับโทเค็นการเข้าถึงและการรีเฟรชเพื่อทำการเรียก API
เรียกใช้ Open Cloud API ใด ๆ ที่รองรับการพิสูจน์ตัวตน OAuth 2.0 ตาม เอกสารอ้างอิงสำหรับทรัพยากรที่คุณต้องการเข้าถึง

ส่วนถัดไปจะอธิบายแต่ละขั้นตอนให้ละเอียดยิ่งขึ้น

สร้างการท้าทายรหัส (เฉพาะสำหรับ PKCE)

ก่อนที่จะเริ่มกระบวนการอนุญาต คุณต้องสร้างการท้าทายรหัสจากตัวตรวจสอบรหัส คุณสามารถใช้ไลบรารีหรือฟังก์ชันในตัวใน ภาษาการเขียนโปรแกรมที่คุณเลือกเพื่อสร้างตัวตรวจสอบรหัส คำนวณ แฮช และดำเนินการเข้ารหัส Base64 เพื่อสร้างการท้าทายรหัส

เมื่อสร้างตัวตรวจสอบรหัส ให้ใช้เฉพาะตัวอักษรที่ไม่ได้สำรอง รวมถึง ตัวอักษรพิมพ์ใหญ่และพิมพ์เล็ก (A-Z, a-z) ตัวเลขฐานสิบ (0-9) เครื่องหมายขีด (-), จุด (.), เครื่องหมายขีดต่ำ (_) และเครื่องหมายท tilde (~) โดยมีความยาวขั้นต่ำ 43 ตัวอักษรและความยาวสูงสุด 128 ตัวอักษร

ตัวอย่างต่อไปนี้แสดงให้เห็นถึงวิธีการใช้ Javascript เพื่อสร้างตัวตรวจสอบรหัสและ สร้างการท้าทายรหัสโดยใช้วิธีการแฮช SHA-256:

สร้างการท้าทายรหัส
const crypto = require('crypto');

// base64URL encode ตัวตรวจสอบและการท้าทาย
function base64URLEncode(str) {
  return str.toString('base64')
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '');
}

// create sha256 hash จากตัวตรวจสอบรหัส
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: ค่าที่สุ่มและเป็นความลับเพื่อรักษาสถานะ ระหว่างคำขอและการเรียกกลับ

จำเป็นสำหรับ non-PKCE เท่านั้น

client_secret: ความลับของลูกค้าแอปของคุณที่ได้รับหลังจาก ลงทะเบียนแอปของคุณ. หากคุณใช้การพิสูจน์ตัวตนด้วย PKCE ให้ละเว้นพารามิเตอร์นี้ URL คำขอการอนุญาตของคุณต้องมีรูปแบบที่ดี เช่นในตัวอย่าง ต่อไปนี้:

ตัวอย่าง 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 ที่ระบุ

จัดการการเรียกกลับการอนุญาต

เมื่อกระบวนการอนุญาตสำเร็จ แอปของคุณจะได้รับคำขอ GET จาก เซิร์ฟเวอร์การอนุญาตของ Roblox ที่ redirect_uri ที่คุณระบุ ใน คำขอ คุณจะได้รับพารามิเตอร์ code (รหัสอนุญาต) และ state(ถ้าคุณให้ค่าไว้ก่อนหน้านี้)

พารามิเตอร์ code ประกอบด้วยรหัสอนุญาตที่แอปสามารถ แลกเปลี่ยนเพื่อรับโทเค็นการเข้าถึงจากเซิร์ฟเวอร์การอนุญาต ภาษาเซิร์ฟเวอร์ส่วนใหญ่มีวิธีการมาตรฐานในการเข้าถึงพารามิเตอร์การคิวในฐานะวัตถุที่ถูกถอดรหัส คุณจะต้องได้รับพารามิเตอร์ code และใช้มันเพื่อแลกเปลี่ยน สำหรับโทเค็นการเข้าถึง
พารามิเตอร์ state เป็นค่าที่ไม่โปร่งใสที่คุณให้ไว้ในตอนแรกในคำขอการอนุญาต คุณสามารถใช้พารามิเตอร์นี้เพื่อรักษาสถานะหรือ บริบทของกระบวนการอนุญาต

ตัวอย่างเช่น คุณอาจได้รับคำขอ GET ที่มี URL ดังต่อไปนี้หากคุณ ระบุให้ URI การเปลี่ยนเส้นทางของคุณเป็น https://example.com/redirect.

ตัวอย่าง URL เปลี่ยนเส้นทาง
https://example.com/redirect?code=10c45PNuquKnFJ6pUcy5-fHkghEM6lSegm-7hj9mVEprub1dSDuStuKK_EAUXY7AHTD63xcnmvxSLthp-C8g3jzIGZVzuXSd20Y2dEYI9hx0LZmPg95ME4z2K03UheiZbroyXUjYyB3ReoMqobzDVPzyx6IS8kj2Uu-11Xq_0JiTYxtDatuqXRNIAmJT8gMJmbSyOLOP_vnDvbeMUiBsqCRrkTGVbWSwYSc8sTVVE-535kYdqQOgNjH1ffCoZLGl8YYxLnpb2CXJlRQPrcjkA&state=6789

หากการอนุญาตล้มเหลว แอปของคุณจะได้รับคำขอ GET ไปยัง URL เปลี่ยนเส้นทางที่ระบุพร้อมพารามิเตอร์ error, error_description และ state (ถ้าจำเป็น)

พารามิเตอร์ error แสดงถึงข้อผิดพลาด OAuth 2.0 ที่เกิดขึ้น ขณะทำการอนุญาต
พารามิเตอร์ error_description ให้รายละเอียดเพิ่มเติมของข้อผิดพลาด
พารามิเตอร์ state ช่วยแอปของคุณรักษาสถานะในกรณีที่เกิดความล้มเหลว

แลกเปลี่ยนรหัสอนุญาตสำหรับโทเค็นการเข้าถึง

เมื่อคุณแยกวิเคราะห์รหัสอนุญาต code แล้ว ให้แลกเปลี่ยนโทเค็นสำหรับ เข้าถึงทรัพยากร Roblox ที่ต้องการ:

ขอโทเค็นการเข้าถึงและโทเค็นการรีเฟรชโดยการส่งคำขอ POST ไปยัง จุดสิ้นสุดการแลกเปลี่ยนโทเค็น. คำขอจะต้องรวมรหัสอนุญาต ID ลูกค้า และค่า ตัวตรวจสอบรหัส (PKCE) หรือความลับของลูกค้า (non-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.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"
}