การตั้งค่า Redirect URL

redirect URI คือ URL สำหรับรับ authorization code หลังจากที่ผู้ใช้กด「อนุญาต」ในหน้าอนุญาตของโฟลว์ OAuth โดย URI ที่ลงทะเบียนตอนลงทะเบียนแอป กับ redirect_uri ที่ระบุตอนส่งคำขอไปยัง /oauth/authorize จริง ต้องตรงกันทั้งหมด (exact match)

บทบาทของ redirect URI

ในโฟลว์ OAuth authorization code ค่าจะถูกส่งต่อตามลำดับต่อไปนี้

1. แอปพาผู้ใช้ไปยังหน้าอนุญาตของ ReceiptRoller (พร้อมแนบ redirect_uri)
2. ผู้ใช้กด「อนุญาต」
3. ReceiptRoller redirect ไปยัง redirect URI ที่ลงทะเบียนไว้ พร้อมพารามิเตอร์ code
4. แอปใช้ code เพื่อขอ access token

หากระบุ URI ที่ไม่ได้ลงทะเบียน หรือ URI ที่ต่างจากค่าที่ลงทะเบียนแม้เพียงตัวอักษรเดียวใน redirect_uri ReceiptRoller จะไม่คืน authorization code และจะเกิดข้อผิดพลาด invalid_redirect_uri นี่คือกลไกที่ป้องกันผู้โจมตีขโมย code

กฎการลงทะเบียน

การแยกใช้สภาพแวดล้อม development และ production

แอปส่วนใหญ่มีหลายสภาพแวดล้อม เช่น「development」「staging」「production」ใน ReceiptRoller คุณสามารถลงทะเบียน redirect URI หลายรายการให้กับแอปเดียวได้ จึงควรเพิ่ม URI ตามแต่ละสภาพแวดล้อมเป็นพื้นฐาน

รูปแบบที่แนะนำ

https://app.example.com/oauth/callback           ← production
https://staging.example.com/oauth/callback       ← staging
http://localhost:3000/oauth/callback             ← development (เครื่องตัวเอง)

คุณสามารถแยกแอปตามสภาพแวดล้อมได้เช่นกัน แต่เราแนะนำอย่างยิ่งให้แยกแอป production กับแอป development ออกจากกันเสมอ ด้วยเหตุผลดังนี้

• ไม่ต้องแจกจ่าย client secret ของ production ให้นักพัฒนาทุกคน
• ป้องกันอุบัติเหตุที่ความผิดพลาดระหว่างพัฒนาไปทำให้ token ของผู้ใช้ production ใช้ไม่ได้โดยไม่ตั้งใจ
• การตรวจสอบ scope กลุ่ม User เสร็จสิ้นได้ที่แอป production เท่านั้น

ขั้นตอนการลงทะเบียน

1. พอร์ทัลนักพัฒนา → รายการแอป → เปิดแอปเป้าหมาย
2. คลิกปุ่ม「＋ เพิ่ม」ในส่วน「redirect URI」
3. กรอก URI แล้ว「บันทึก」
4. ทำซ้ำตามจำนวนสภาพแวดล้อมที่ต้องการ

URI ที่ลงทะเบียนจะมีผลทันที ไม่ต้อง build หรือ deploy แอปใหม่

การใช้พารามิเตอร์ state

ข้อมูลแบบไดนามิก (URL ของหน้าต้นทาง, user ID, token ป้องกัน CSRF เป็นต้น) ไม่ควรฝังลงใน redirect URI โดยตรง แต่ให้ส่งผ่านพารามิเตอร์ state เนื่องจาก ReceiptRoller จะคืน state กลับมาเหมือนเดิมหลังการอนุญาต ฝั่ง callback จึงกู้คืนได้

// คำขออนุญาต
https://receiptroller.io/oauth/authorize
  ?client_id=xxx
  &redirect_uri=https://app.example.com/oauth/callback
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9
  &scope=store.read
  &response_type=code

// callback
https://app.example.com/oauth/callback
  ?code=...
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9

state ยังจำเป็นในฐานะมาตรการป้องกัน CSRF ด้วย ให้สร้างค่าสุ่มตอนส่งคำขอ เก็บไว้ใน session และตรวจสอบว่าตรงกันตอน callback

ข้อผิดพลาดที่พบบ่อย

ข้อควรระวังเมื่อเปลี่ยนแปลง

เมื่อต้องการเปลี่ยน redirect URI ของแอปที่กำลังทำงานอยู่ ให้ทำตามลำดับต่อไปนี้

1. เพิ่ม URI ใหม่ (คง URI เดิมไว้)
2. เปลี่ยนโค้ด／ตัวแปรสภาพแวดล้อมของแอปให้เป็น URI ใหม่แล้ว deploy
3. ยืนยันการทำงานด้วย URI ใหม่
4. ลบ URI เดิม

หากลบ URI เดิมทันที คำขออนุญาตที่เกิดขึ้นระหว่างช่วงที่ deploy ยังไม่เสร็จจะล้มเหลวทั้งหมด

คู่มือที่เกี่ยวข้อง

• สร้างแอปใหม่
• รายการ OAuth scope ที่ใช้ได้
• กลับไปยังศูนย์ช่วยเหลือสำหรับนักพัฒนา